Windows 開發環境極簡安裝指南

本指南採用 Windows 原生 WinGet 與 Python 極速套件管理器 uv。
請開啟 Windows PowerShell（一般使用者身分即可；Git、Node.js 等安裝程式若跳出 UAC 視窗，按「是」允許即可）。

偵測到已存在的工具會保留現有版本、不會自動升級；請以各模組的「驗證」結果為準。
以下命令會自動接受 WinGet 來源條款與各套件的授權協議，請確認你同意後再執行。
安裝時請勿在已啟用 Python 虛擬環境（.venv）的視窗中執行。

開始之前：若要把安裝工作交給 AI，請先完成階段一的第 1 步（安裝 Antigravity IDE）與第 2 步（取得教材）。

事前確認：WinGet

Windows 11 已內建 WinGet；部分未更新的 Windows 10 可能沒有。先執行：

powershell

winget --version

若出現「無法辨識 winget」，請開啟 Microsoft Store 搜尋「應用程式安裝程式（App Installer）」安裝或更新，重新開啟 PowerShell 後再繼續。

模組一：核心開發工具

包含：Git、uv、Node.js LTS、GitHub CLI (gh)、Pandoc（Markdown、Word、HTML 等格式互轉，階段二起使用）。

複製以下指令貼入 PowerShell 執行（已存在則自動跳過）：

powershell

# 1. 允許執行本機 PowerShell 腳本（避免 npm.ps1 報錯；僅影響目前使用者）
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned -Force

# 2. 定義核心工具清單
$coreTools = @(
    @{ Cmd = "git";  Id = "Git.Git" },
    @{ Cmd = "uv";   Id = "astral-sh.uv" },
    @{ Cmd = "node"; Id = "OpenJS.NodeJS.LTS" },
    @{ Cmd = "gh";   Id = "GitHub.cli" },
    @{ Cmd = "pandoc"; Id = "JohnMacFarlane.Pandoc" }
)

# 3. 已存在則跳過，缺少才安裝；記錄失敗項目
$failed = @()
foreach ($tool in $coreTools) {
    if (Get-Command $tool.Cmd -ErrorAction SilentlyContinue) {
        $ver = (& $tool.Cmd --version 2>$null) -join " "
        Write-Host "[已安裝] $($tool.Cmd) ($ver)，跳過。" -ForegroundColor Yellow
    } else {
        Write-Host "[缺少] 正在安裝 $($tool.Id) ..." -ForegroundColor Cyan
        winget install --id $tool.Id -e --source winget --accept-package-agreements --accept-source-agreements
        if ($LASTEXITCODE -notin 0, -1978335189) { $failed += $tool.Id }  # -1978335189：已安裝、沒有可用的升級
    }
}

# 4. 即時重載環境變數 PATH（保留目前視窗原有的路徑）
$env:Path = [Environment]::GetEnvironmentVariable("Path", "Machine") + ";" + [Environment]::GetEnvironmentVariable("Path", "User") + ";" + $env:Path

# 5. 檢查 Node.js 版本（階段四需要 22.12 以上，或 20.19 以上的 20 版）
if (Get-Command node -ErrorAction SilentlyContinue) {
    node -e "const [a,b]=process.versions.node.split('.').map(Number);process.exit(a>22||(a===22&&b>=12)||(a===20&&b>=19)?0:1)"
    if ($LASTEXITCODE -ne 0) {
        Write-Host "[版本過舊] Node.js $(node --version)：請執行 winget upgrade --id OpenJS.NodeJS.LTS -e；若顯示找不到已安裝的套件，改用 winget install --id OpenJS.NodeJS.LTS -e，再重新開啟 PowerShell。" -ForegroundColor Red
        $failed += "Node.js 版本過舊"
    }
}

if ($failed) {
    Write-Host "`n以下項目安裝失敗：$($failed -join ', ')。請查看上方錯誤訊息，處理後重新執行本段。" -ForegroundColor Red
} else {
    Write-Host "`n核心工具安裝檢查完成！" -ForegroundColor Green
}

核心工具驗證

powershell

git --version
uv --version
node --version        # 階段四需要 22.12 以上（或 20.19 以上的 20 版）
npm --version
npx --version
gh --version
pandoc --version

再實際把一份含中文表格的 Markdown 轉成 Word，確認 Pandoc 正常：

powershell

Set-Location $env:TEMP
[IO.File]::WriteAllText("$env:TEMP\pandoc-test.md", "# 轉檔測試`n`n| 欄位 | 內容 |`n| --- | --- |`n| 中文 | 正常顯示 |", [Text.UTF8Encoding]::new($false))
pandoc pandoc-test.md -o pandoc-test.docx
if ($LASTEXITCODE -eq 0 -and (Test-Path pandoc-test.docx)) {
    Write-Host "Word 轉檔成功！" -ForegroundColor Green
    Start-Process pandoc-test.docx
} else {
    Write-Host "Word 轉檔失敗，請查看上方錯誤訊息。" -ForegroundColor Red
}

Pandoc 使用範例：

powershell

pandoc report.md -o report.docx     # Markdown 轉 Word
pandoc report.docx -o report.md     # Word 轉 Markdown（方便交給 AI 整理）
pandoc report.md -o report.html     # Markdown 轉網頁

模組二：多媒體與進階 CLI 工具

分類安裝原則：

WinGet：安裝系統原生二進位工具（ffmpeg, ripgrep, jq, ImageMagick）。
uv tool：安裝 Python 生態獨立工具（edge-tts, yt-dlp）。

請先完成模組一（需要 uv），再複製以下指令執行（已存在則自動跳過）：

powershell

$failed = @()

# 1. WinGet 安裝原生系統工具
$systemTools = @(
    @{ Cmd = "ffmpeg";  Id = "Gyan.FFmpeg" },
    @{ Cmd = "rg";      Id = "BurntSushi.ripgrep.MSVC" },
    @{ Cmd = "jq";      Id = "jqlang.jq" },
    @{ Cmd = "magick";  Id = "ImageMagick.ImageMagick" }
)

foreach ($tool in $systemTools) {
    if (Get-Command $tool.Cmd -ErrorAction SilentlyContinue) {
        Write-Host "[已安裝] $($tool.Cmd)，跳過。" -ForegroundColor Yellow
    } else {
        Write-Host "[缺少] 正在安裝 $($tool.Id) ..." -ForegroundColor Cyan
        winget install --id $tool.Id -e --source winget --accept-package-agreements --accept-source-agreements
        if ($LASTEXITCODE -notin 0, -1978335189) { $failed += $tool.Id }  # -1978335189：已安裝、沒有可用的升級
    }
}

# 2. uv tool 安裝 Python 獨立命令列工具
#    edge-tts 與 yt-dlp 依賴外部服務，服務改版後舊版就會失效（例如 edge-tts 出現 403 錯誤），
#    所以不論是否已安裝，一律更新到最新版：沒裝會安裝，已裝會升級
$pyTools = @("edge-tts", "yt-dlp")

foreach ($pkg in $pyTools) {
    Write-Host "正在透過 uv 安裝或更新 $pkg ..." -ForegroundColor Cyan
    uv tool install --upgrade $pkg
    if ($LASTEXITCODE -ne 0) { $failed += $pkg }
}

# 3. 確保 uv tool 的執行檔目錄（位置可用 uv tool dir --bin 查詢）已加入使用者 PATH
#    若顯示「Restart your shell to apply changes」可忽略，下一步會立即生效
uv tool update-shell

# 4. 再次重載 PATH（保留目前視窗原有的路徑）
$env:Path = [Environment]::GetEnvironmentVariable("Path", "Machine") + ";" + [Environment]::GetEnvironmentVariable("Path", "User") + ";" + $env:Path

if ($failed) {
    Write-Host "`n以下項目安裝失敗：$($failed -join ', ')。請查看上方錯誤訊息，處理後重新執行本段。" -ForegroundColor Red
} else {
    Write-Host "`n擴充工具安裝檢查完成！" -ForegroundColor Green
}

擴充工具驗證

powershell

ffmpeg -version
rg --version
jq --version
magick -version
edge-tts --version
yt-dlp --version

再實際產生一段語音，確認 edge-tts 能連上微軟的服務：

powershell

Set-Location $env:TEMP
edge-tts --voice zh-TW-HsiaoChenNeural --text "早安" --write-media tts-test.mp3
if ($LASTEXITCODE -eq 0 -and (Get-Item tts-test.mp3).Length -gt 0) {
    Write-Host "語音產生成功！" -ForegroundColor Green
    Start-Process tts-test.mp3
} else {
    Write-Host "語音產生失敗。若錯誤訊息含 403，執行 uv tool upgrade edge-tts 後再試一次。" -ForegroundColor Red
}

擴充工具使用範例

powershell

# 文字轉語音（台灣中文女聲）
edge-tts --voice zh-TW-HsiaoChenNeural --text "你好，這是測試" --write-media hello.mp3

# 專案全文搜尋：預設略過隱藏檔（如 .git）；在 Git 儲存庫內會遵守 .gitignore，
# 因此通常也會跳過 node_modules 與 .venv
rg "API_KEY"          # 全專案搜尋
rg -i "database_url"  # 不分大小寫
rg "def main" -t py   # 只搜 Python 檔
rg -l "TODO"          # 只列出檔名
rg "API_KEY" -g "!node_modules/**"  # 不在 Git 儲存庫時，手動排除 node_modules

模組三：LaTeX（階段六使用）

包含：MiKTeX（LaTeX 排版，用來輸出 PDF、撰寫論文格式）。安裝檔約 150 MB，第一次編譯時還會自動下載需要的套件，建議在穩定的網路環境安裝。階段六開始前再裝即可；PDF 輸出測試需要模組一的 Pandoc。

MiKTeX 只先安裝基本套件，編譯時缺什麼才自動下載。下方腳本會：
用 WinGet 下載 MiKTeX 安裝檔，再開一個獨立視窗安裝（安裝程式在 AI 代為執行的終端機裡會被中斷，WinGet 卻仍顯示「已成功安裝」，所以不直接用 winget install）。
開啟「自動安裝缺少的套件」，避免編譯時一直跳出確認視窗。
把套件更新到最新版。網路不穩時會出現 SSL connect error，腳本會自動重試。

powershell

$failed = @()

$miktexBin = "$env:LOCALAPPDATA\Programs\MiKTeX\miktex\bin\x64"
if ((Get-Command xelatex -ErrorAction SilentlyContinue) -or (Test-Path "$miktexBin\xelatex.exe")) {
    Write-Host "[已安裝] LaTeX (xelatex)，跳過。" -ForegroundColor Yellow
} else {
    Write-Host "[缺少] 正在下載並安裝 MiKTeX（約 150 MB）..." -ForegroundColor Cyan
    $dl = "$env:TEMP\miktex-setup"
    Remove-Item $dl -Recurse -Force -ErrorAction SilentlyContinue
    winget download --id MiKTeX.MiKTeX -e --source winget -d $dl --accept-package-agreements --accept-source-agreements
    $setup = Get-ChildItem $dl -Filter *.exe -ErrorAction SilentlyContinue | Select-Object -First 1
    if ($setup) {
        # 清掉先前中斷安裝留下的鎖定資料夾，否則重裝也會被取消
        Remove-Item "$env:LOCALAPPDATA\Programs\MiKTeX\miktex\lock" -Recurse -Force -ErrorAction SilentlyContinue
        Start-Process $setup.FullName -ArgumentList "--unattended", "--private" -Wait
    }
    if (-not (Test-Path "$miktexBin\xelatex.exe")) { $failed += "MiKTeX.MiKTeX" }
}

# 重載 PATH（保留目前視窗原有的路徑）
$env:Path = [Environment]::GetEnvironmentVariable("Path", "Machine") + ";" + [Environment]::GetEnvironmentVariable("Path", "User") + ";" + $env:Path

if (Get-Command initexmf -ErrorAction SilentlyContinue) {
    # 編譯時自動下載缺少的 LaTeX 套件，不再逐一跳出確認視窗
    initexmf "--set-config-value=[MPM]AutoInstall=yes"
    # 把套件更新到最新版；網路不穩出現 SSL connect error 時自動重試
    foreach ($i in 1..3) {
        miktex packages update
        if ($LASTEXITCODE -eq 0) { break }
        Write-Host "更新失敗（第 $i 次），重試中 ..." -ForegroundColor Yellow
    }
    if ($LASTEXITCODE -ne 0) { $failed += "MiKTeX 套件更新" }
}

if ($failed) {
    Write-Host "`n以下項目安裝失敗：$($failed -join ', ')。請查看上方錯誤訊息，處理後重新執行本段。" -ForegroundColor Red
} else {
    Write-Host "`nLaTeX 安裝檢查完成！" -ForegroundColor Green
}

LaTeX 驗證

powershell

xelatex --version

再實際輸出一份中文 PDF。第一次執行時 MiKTeX 會自動下載中文排版套件，可能需要幾分鐘：

powershell

Set-Location $env:TEMP
[IO.File]::WriteAllText("$env:TEMP\pandoc-test.md", "# 轉檔測試`n`n| 欄位 | 內容 |`n| --- | --- |`n| 中文 | 正常顯示 |", [Text.UTF8Encoding]::new($false))
pandoc pandoc-test.md -o pandoc-test.pdf --pdf-engine=xelatex -V CJKmainfont="Microsoft JhengHei"
if ($LASTEXITCODE -eq 0 -and (Test-Path pandoc-test.pdf)) {
    Write-Host "PDF 輸出成功！" -ForegroundColor Green
    Start-Process pandoc-test.pdf
} else {
    Write-Host "PDF 輸出失敗，請查看上方錯誤訊息。" -ForegroundColor Red
}

LaTeX 使用範例

powershell

# Markdown 轉 PDF（含中文）
pandoc report.md -o report.pdf --pdf-engine=xelatex -V CJKmainfont="Microsoft JhengHei"

# 編譯 LaTeX 論文（有參考文獻時：xelatex → bibtex → xelatex → xelatex）
xelatex paper.tex

模組四：OpenCode（選修，階段八使用）

OpenCode 是開源的終端機 AI Agent。本課程以 v1（1.19.3） 為準，用 npm 安裝指定版本。

不要執行 opencode upgrade --major，也不要用其他方式安裝最新版：那些會裝到設定方式不同的 OpenCode 2。

請先完成模組一（需要 Node.js），再複製以下指令執行（已存在則自動跳過）：

powershell

$failed = @()

if (Get-Command opencode -ErrorAction SilentlyContinue) {
    $ver = (opencode --version 2>$null) -join " "
    if ($ver -match '(\d+)\.\d+\.\d+' -and $Matches[1] -eq '1') {
        Write-Host "[已安裝] opencode ($ver)，跳過。" -ForegroundColor Yellow
    } else {
        # 已裝的是 OpenCode 2 時不自動降版，避免動到使用者原本的設定
        Write-Host "[版本不同] opencode $ver：本課程以 v1 為準。教材的設定檔在 v2 預期也能用，差異見 08-opencode/reference.md；要改用 v1，先移除目前的版本再重新執行本段。" -ForegroundColor Yellow
    }
} elseif (-not (Get-Command npm.cmd -ErrorAction SilentlyContinue)) {
    Write-Host "錯誤：找不到 npm，請先完成模組一（Node.js）。" -ForegroundColor Red
    $failed += "Node.js"
} else {
    Write-Host "[缺少] 正在安裝 OpenCode 1.19.3 ..." -ForegroundColor Cyan
    # 用 npm.cmd：學校或公司電腦無法變更執行原則時，npm.ps1 會被擋下
    npm.cmd install -g opencode-ai@1.19.3
    if ($LASTEXITCODE -ne 0) { $failed += "opencode-ai" }
}

# 重載 PATH（保留目前視窗原有的路徑）
$env:Path = [Environment]::GetEnvironmentVariable("Path", "Machine") + ";" + [Environment]::GetEnvironmentVariable("Path", "User") + ";" + $env:Path

if ($failed) {
    Write-Host "`n以下項目安裝失敗：$($failed -join ', ')。請查看上方錯誤訊息，處理後重新執行本段。" -ForegroundColor Red
} else {
    Write-Host "`nOpenCode 安裝檢查完成！" -ForegroundColor Green
}

OpenCode 驗證

powershell

opencode --version    # 應顯示 1.19.3

接上模型與使用方式，見階段八。

常見問題排除

指令找不到（Command Not Found）：
- 請直接關閉並重新開啟 PowerShell 視窗讓系統環境變數徹底刷新。
- 確認路徑：where.exe git、where.exe uv、where.exe rg。
npm 出現「這個系統上已停用指令碼執行」：
- 執行：Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned -Force
- 學校或公司管理的電腦可能被群組原則禁止變更，請改用 .cmd 版本執行：npm.cmd -v、npx.cmd。
出現「無法辨識 winget」：
- WinGet 由 Microsoft Store 的「應用程式安裝程式」（App Installer）提供，安裝或更新後重新開啟 PowerShell 再試。
winget 安裝 uv 失敗時的備用方式：
- 先執行 winget source update 後重試。
- 仍失敗時，經使用者確認後才可改用 Astral 官方安裝指令：
  powershell
```
powershell.exe -NoProfile -ExecutionPolicy Bypass -Command "irm https://astral.sh/uv/install.ps1 | iex"
```
edge-tts 出現 403 錯誤（Invalid response status）：
- 微軟的語音服務更新了驗證方式，舊版 edge-tts 會被拒絕連線，產出的 mp3 是空檔。
- 執行 uv tool upgrade edge-tts 更新到最新版後再試。新版通常在服務改版後幾天內發布。
- 更新後仍失敗，表示新版還沒推出，暫時改用其他方式處理，不要反覆重試。

🧰 01 安裝環境

第 3 步：安裝軟體

🔁 05 AI 交叉審查

🧩 06 Agent Skills

💻 08 OpenCode 入門

Windows 開發環境極簡安裝指南

事前確認：WinGet

模組一：核心開發工具

核心工具驗證

模組二：多媒體與進階 CLI 工具

擴充工具驗證

擴充工具使用範例

模組三：LaTeX（階段六使用）

LaTeX 驗證

LaTeX 使用範例

模組四：OpenCode（選修，階段八使用）

OpenCode 驗證

常見問題排除

第 3 步：安裝軟體

Windows 開發環境極簡安裝指南 ​

事前確認：WinGet ​

模組一：核心開發工具 ​

核心工具驗證 ​

模組二：多媒體與進階 CLI 工具 ​

擴充工具驗證 ​

擴充工具使用範例 ​

模組三：LaTeX（階段六使用） ​

LaTeX 驗證 ​

LaTeX 使用範例 ​

模組四：OpenCode（選修，階段八使用） ​

OpenCode 驗證 ​

常見問題排除 ​

Windows 開發環境極簡安裝指南

事前確認：WinGet

模組一：核心開發工具

核心工具驗證

模組二：多媒體與進階 CLI 工具

擴充工具驗證

擴充工具使用範例

模組三：LaTeX（階段六使用）

LaTeX 驗證

LaTeX 使用範例

模組四：OpenCode（選修，階段八使用）

OpenCode 驗證

常見問題排除