macOS 開發環境極簡安裝指南

本指南採用 macOS 套件管理器 Homebrew 與 Python 極速套件管理器 uv。
請開啟「終端機」（Terminal，預設 shell 為 zsh），以一般使用者身分執行；遇到要求輸入密碼時，輸入本機登入密碼即可（輸入時畫面不會顯示字元）。

本課程只支援 Apple Silicon（M 系列晶片）Mac、macOS 12 以上。Homebrew 官方安裝腳本在 Intel Mac 上會直接中止（顯示「Homebrew on macOS is only supported on Apple Silicon processors!」）。
偵測到已存在的工具會保留現有版本、不會自動升級；請以各模組的「驗證」結果為準。

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

事前準備：Homebrew

已安裝者會自動跳過。若電腦缺少 Xcode Command Line Tools（提供編譯器與 git），Homebrew 安裝程式會自動引導安裝並等待完成，可能需要數分鐘。

zsh

# 1. 安裝 Homebrew（已安裝則跳過）
if command -v brew >/dev/null 2>&1; then
    echo "[已安裝] Homebrew，跳過。"
else
    echo "[缺少] 正在安裝 Homebrew ..."
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
fi

# 2. 將 brew 加入 PATH（Apple Silicon 的 Homebrew 安裝在 /opt/homebrew）
if [ -x /opt/homebrew/bin/brew ]; then
    grep -q 'brew shellenv' ~/.zprofile 2>/dev/null || echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
    eval "$(/opt/homebrew/bin/brew shellenv)"
fi

brew --version

模組一：核心開發工具

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

macOS 的 Git 由 Xcode Command Line Tools 提供，偵測到即沿用，不另外透過 Homebrew 安裝。
Homebrew 的 node 是最新版，不一定是 LTS；一般教學與開發使用沒有差別。

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

zsh

# 格式為「指令名稱:Homebrew 套件名稱」
coreTools=(git:git uv:uv node:node gh:gh pandoc:pandoc)
failed=()

if ! command -v brew >/dev/null 2>&1; then
    echo "錯誤：找不到 brew，請先完成上方「事前準備」再執行本段。"
    failed+=("Homebrew")
else
    for t in "${coreTools[@]}"; do
        cmd=${t%:*}; pkg=${t#*:}
        if command -v $cmd >/dev/null 2>&1; then
            echo "[已安裝] $cmd，跳過。"
        else
            echo "[缺少] 正在安裝 $pkg ..."
            brew install $pkg || failed+=("$pkg")
        fi
    done
fi

hash -r

# 檢查 Node.js 版本（階段四需要 22.12 以上，或 20.19 以上的 20 版）
if command -v node >/dev/null 2>&1 && ! 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)"; then
    echo "[版本過舊] Node.js $(node --version)：請執行 brew upgrade node；若顯示 node 不是用 Homebrew 安裝的，改用 brew install node，再重新開啟終端機。"
    failed+=("Node.js 版本過舊")
fi

echo
if [ ${#failed[@]} -gt 0 ]; then
    echo "以下項目安裝失敗：${failed[*]}。請查看上方錯誤訊息，處理後重新執行本段。"
else
    echo "核心工具安裝檢查完成！"
fi

核心工具驗證

zsh

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

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

zsh

cd "${TMPDIR:-/tmp}"
printf '%s\n' '# 轉檔測試' '' '| 欄位 | 內容 |' '| --- | --- |' '| 中文 | 正常顯示 |' > pandoc-test.md
if pandoc pandoc-test.md -o pandoc-test.docx; then
    echo "Word 轉檔成功！"
    open pandoc-test.docx
else
    echo "Word 轉檔失敗，請查看上方錯誤訊息。"
fi

Pandoc 使用範例：

zsh

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 工具

分類安裝原則：

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

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

zsh

failed=()

# 1. Homebrew 安裝原生系統工具
systemTools=(ffmpeg:ffmpeg rg:ripgrep jq:jq magick:imagemagick)

for t in "${systemTools[@]}"; do
    cmd=${t%%:*}; pkg=${t#*:}
    if command -v $cmd >/dev/null 2>&1; then
        echo "[已安裝] $cmd，跳過。"
    else
        echo "[缺少] 正在安裝 $pkg ..."
        brew install $pkg || failed+=("$pkg")
    fi
done

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

for pkg in "${pyTools[@]}"; do
    echo "正在透過 uv 安裝或更新 $pkg ..."
    uv tool install --upgrade $pkg || failed+=("$pkg")
done

# 3. 將 uv tool 的執行檔目錄寫入 shell 設定檔（之後新開的終端機生效）
#    若顯示「already up-to-date」或「Restart your shell」屬正常，可忽略
uv tool update-shell || true

# 4. 讓目前這個終端機視窗也立即生效
export PATH="$(uv tool dir --bin):$PATH"
hash -r

echo
if [ ${#failed[@]} -gt 0 ]; then
    echo "以下項目安裝失敗：${failed[*]}。請查看上方錯誤訊息，處理後重新執行本段。"
else
    echo "擴充工具安裝檢查完成！"
fi

擴充工具驗證

zsh

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

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

zsh

cd /tmp
if edge-tts --voice zh-TW-HsiaoChenNeural --text "早安" --write-media tts-test.mp3 && [ -s tts-test.mp3 ]; then
    echo "語音產生成功！"
    open tts-test.mp3
else
    echo "語音產生失敗。若錯誤訊息含 403，執行 uv tool upgrade edge-tts 後再試一次。"
fi

擴充工具使用範例

zsh

# 文字轉語音（台灣中文女聲）
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（階段六使用）

包含：MacTeX（LaTeX 排版，用來輸出 PDF、撰寫論文格式）。內含完整套件，下載達數 GB，建議在家中寬頻網路安裝。階段六開始前再裝即可；PDF 輸出測試需要模組一的 Pandoc。

安裝 MacTeX 時 Homebrew 會要求輸入 Mac 的登入密碼，這是正常的（不要自己在指令前加 sudo）。安裝完成後，LaTeX 指令位於 /Library/TeX/texbin。

zsh

failed=()

if command -v xelatex >/dev/null 2>&1; then
    echo "[已安裝] LaTeX (xelatex)，跳過。"
else
    echo "[缺少] 正在安裝 MacTeX（數 GB，請耐心等候）..."
    brew install --cask mactex-no-gui || failed+=("mactex-no-gui")
fi

# 讓目前視窗找得到 /Library/TeX/texbin
eval "$(/usr/libexec/path_helper)"
hash -r
echo
if [ ${#failed[@]} -gt 0 ]; then
    echo "以下項目安裝失敗：${failed[*]}。請查看上方錯誤訊息，處理後重新執行本段。"
else
    echo "LaTeX 安裝檢查完成！"
fi

LaTeX 驗證

zsh

xelatex --version

再實際輸出一份中文 PDF：

zsh

cd "${TMPDIR:-/tmp}"
printf '%s\n' '# 轉檔測試' '' '| 欄位 | 內容 |' '| --- | --- |' '| 中文 | 正常顯示 |' > pandoc-test.md
if pandoc pandoc-test.md -o pandoc-test.pdf --pdf-engine=xelatex -V CJKmainfont="Songti TC"; then
    echo "PDF 輸出成功！"
    open pandoc-test.pdf
else
    echo "PDF 輸出失敗，請查看上方錯誤訊息。"
fi

LaTeX 使用範例

zsh

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

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

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

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

不要用 brew install opencode，也不要執行 opencode upgrade --major：Homebrew 官方套件與升級指令都會裝到設定方式不同的 OpenCode 2。

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

zsh

failed=()

if command -v opencode >/dev/null 2>&1; then
    ver=$(opencode --version 2>/dev/null)
    major=$(echo "$ver" | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -n 1 | cut -d. -f1)
    if [ "$major" = "1" ]; then
        echo "[已安裝] opencode ($ver)，跳過。"
    else
        # 已裝的是 OpenCode 2 時不自動降版，避免動到使用者原本的設定
        echo "[版本不同] opencode $ver：本課程以 v1 為準。教材的設定檔在 v2 預期也能用，差異見 08-opencode/reference.md；要改用 v1，先移除目前的版本再重新執行本段。"
    fi
elif ! command -v npm >/dev/null 2>&1; then
    echo "錯誤：找不到 npm，請先完成模組一（Node.js）。"
    failed+=("Node.js")
else
    echo "[缺少] 正在安裝 OpenCode 1.19.3 ..."
    npm install -g opencode-ai@1.19.3 || failed+=("opencode-ai")
fi

hash -r
echo
if [ ${#failed[@]} -gt 0 ]; then
    echo "以下項目安裝失敗：${failed[*]}。請查看上方錯誤訊息，處理後重新執行本段。"
else
    echo "OpenCode 安裝檢查完成！"
fi

OpenCode 驗證

zsh

opencode --version    # 應顯示 1.19.3

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

常見問題排除

指令找不到（command not found）：
- 請關閉並重新開啟終端機讓 PATH 設定生效。
- 確認路徑：command -v git、command -v uv、command -v rg。
安裝 Homebrew 後 brew 找不到（Apple Silicon）：
- 重新執行「事前準備」第 2 步，或手動執行：eval "$(/opt/homebrew/bin/brew shellenv)"。
出現 xcrun: error: invalid active developer path：
- 系統更新後 Command Line Tools 失效，重新執行：xcode-select --install，在跳出的視窗按「安裝」。
Homebrew 安裝 uv 失敗時的備用方式：
- 先執行 brew update 後重試。
- 仍失敗時，經使用者確認後才可改用 Astral 官方安裝指令：
  zsh
```
curl -LsSf https://astral.sh/uv/install.sh | sh
```
edge-tts 出現 403 錯誤（Invalid response status）：
- 微軟的語音服務更新了驗證方式，舊版 edge-tts 會被拒絕連線，產出的 mp3 是空檔。
- 執行 uv tool upgrade edge-tts 更新到最新版後再試。新版通常在服務改版後幾天內發布。
- 更新後仍失敗，表示新版還沒推出，暫時改用其他方式處理，不要反覆重試。

🧰 01 安裝環境

第 3 步：安裝軟體

🔁 05 AI 交叉審查

🧩 06 Agent Skills

💻 08 OpenCode 入門

macOS 開發環境極簡安裝指南

事前準備：Homebrew

模組一：核心開發工具

核心工具驗證

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

擴充工具驗證

擴充工具使用範例

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

LaTeX 驗證

LaTeX 使用範例

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

OpenCode 驗證

常見問題排除

第 3 步：安裝軟體

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

事前準備：Homebrew ​

模組一：核心開發工具 ​

核心工具驗證 ​

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

擴充工具驗證 ​

擴充工具使用範例 ​

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

LaTeX 驗證 ​

LaTeX 使用範例 ​

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

OpenCode 驗證 ​

常見問題排除 ​

macOS 開發環境極簡安裝指南

事前準備：Homebrew

模組一：核心開發工具

核心工具驗證

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

擴充工具驗證

擴充工具使用範例

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

LaTeX 驗證

LaTeX 使用範例

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

OpenCode 驗證

常見問題排除