快速入門｜Claude Code 教學

系統需求

在安裝 Claude Code 之前，請確認你的開發環境符合以下最低規格。Claude Code 是一個以 Node.js 為基底的 CLI 工具，因此對作業系統的相依性很低，但對 Node.js 版本有明確要求。

作業系統：macOS 12+、Ubuntu 20.04+、Windows 10/11（需搭配 WSL2）
Node.js：版本 18.0 或以上（建議使用 LTS 版本）
npm：版本 8.0 或以上（隨 Node.js 一同安裝）
Git：2.23 或以上（用於版本控制整合功能）
終端機：支援 ANSI 顏色碼的現代終端，如 iTerm2、Windows Terminal、GNOME Terminal
網路：能連線至 api.anthropic.com（部分企業環境需額外設定 proxy）

若尚未安裝 Node.js，建議使用 nvm（Node Version Manager） 進行管理，可方便切換版本。執行 node -v 與 npm -v 確認版本後再繼續。

詳細安裝步驟

Claude Code 以 npm 全域套件形式發佈，安裝方式與其他常見 CLI 工具相同。以下步驟適用於 macOS 與 Linux；Windows 使用者請在 WSL2 環境中執行。

步驟一：確認 Node.js 版本

node -v
# 輸出應為 v18.x.x 或更高版本
npm -v
# 輸出應為 8.x.x 或更高版本

步驟二：全域安裝 Claude Code

npm install -g @anthropic-ai/claude-code

安裝完成後，claude 指令會被加入系統 PATH。若出現權限錯誤（EACCES），不要使用 sudo npm install -g，而應改用 nvm 或修正 npm 全域目錄的擁有者設定。

步驟三：確認安裝成功

claude --version
# 輸出範例：claude-code/1.x.x

若終端機回報 command not found: claude，代表 npm 全域 bin 目錄不在 PATH 中。執行 npm bin -g 取得路徑，再將其加入 ~/.zshrc 或 ~/.bashrc 的 export PATH 行，重新開啟終端機即可。

登入與 API Key 設定

Claude Code 支援兩種認證方式：透過瀏覽器 OAuth 登入 Claude.ai 帳號，或直接設定 Anthropic API Key。

方式 A：互動式登入（推薦個人用戶）

claude login

執行後會自動開啟瀏覽器，引導你登入 Claude.ai 帳號並授權。授權完成後，憑證會以加密形式儲存在本機，無需每次重新登入。

方式 B：設定 API Key（推薦企業與 CI/CD 環境）

前往 console.anthropic.com 建立 API Key 後，透過環境變數設定：

# 加入 ~/.zshrc 或 ~/.bashrc（永久生效）
export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxxxxxx"

# 重新載入設定
source ~/.zshrc

API Key 請勿直接寫入程式碼或提交至 Git 版本庫。建議搭配 .env 檔案與 .gitignore 管理，或使用企業級的 secrets 管理工具（如 HashiCorp Vault、AWS Secrets Manager）。

確認登入狀態

claude --version
# 若已登入，會顯示版本號而非要求登入

/init 初始化專案

進入任何既有專案後，第一件事應該是執行 /init。此指令會讓 Claude Code 掃描專案結構，自動產生 CLAUDE.md 檔案，記錄專案的技術架構、常用指令與注意事項，作為 AI 的長期記憶基礎。

cd your-project
claude
# 進入互動介面後執行：
/init

/init 完成後，請務必人工審閱生成的 CLAUDE.md，補充以下資訊使 AI 更準確理解你的專案：

專案的主要用途與商業邏輯簡述
啟動、測試、建置的標準指令（如 npm run dev、pytest）
重要的命名慣例與架構決策
不應修改的關鍵檔案或目錄
團隊的程式碼風格偏好（如縮排、引號樣式）

首次任務建議

第一次使用 Claude Code 時，建議從「探索性任務」開始，讓 AI 先理解專案後再進行修改，避免破壞既有架構。以下是一個經典的首次對話腳本：

# 第一輪：讓 AI 理解專案
請掃描整個專案結構，說明主要模組之間的資料流，
並列出所有對外的 API 端點。

# 第二輪：確認可執行性
請執行測試指令，告訴我目前有幾個測試通過、幾個失敗。

# 第三輪：進行最小改動
請新增一個最簡單的功能：在 /health 路由回傳 {"status": "ok"}，
並新增對應的單元測試。

首次任務應遵循「讀→分析→最小改動→驗證」的四步驟流程。避免一開始就要求大規模重構，這樣做不僅容易超出 AI 的上下文視窗限制，也難以逐步驗收結果。

升級方式

Claude Code 持續迭代更新，建議定期升級以取得最新功能與安全修補。

# 升級至最新版本
npm update -g @anthropic-ai/claude-code

# 確認升級後的版本
claude --version

若有版本鎖定需求（例如團隊統一使用特定版本），可在安裝時指定版本號：

npm install -g @anthropic-ai/claude-code@1.2.3

在 CI/CD 環境中，建議將版本號固定於 Dockerfile 或安裝腳本，避免因自動升級導致行為不一致。升級前可查閱官方 changelog 確認是否有破壞性變更。

企業 Proxy 設定

在企業網路環境中，出站 HTTPS 流量通常需要通過 proxy 伺服器。Claude Code 遵循標準的環境變數設定方式：

# 設定 HTTP/HTTPS proxy（永久生效，加入 shell 設定檔）
export HTTPS_PROXY="https://proxy.company.com:8080"
export HTTP_PROXY="http://proxy.company.com:8080"

# 若 proxy 需要身份驗證
export HTTPS_PROXY="https://username:password@proxy.company.com:8080"

# 設定不走 proxy 的位址（視企業網路規則調整）
export NO_PROXY="localhost,127.0.0.1,internal.company.com"

npm 本身也需要獨立設定 proxy，否則套件安裝可能失敗：

npm config set proxy http://proxy.company.com:8080
npm config set https-proxy https://proxy.company.com:8080

# 若企業使用自簽憑證，需關閉嚴格 SSL 驗證（僅限內部環境）
npm config set strict-ssl false

若企業使用 SSL 中間人檢查（SSL Inspection），需額外將企業根憑證加入 Node.js 的信任鏈。設定環境變數 NODE_EXTRA_CA_CERTS=/path/to/corporate-root-ca.pem，指向企業 CA 憑證的 PEM 檔案。

常見安裝問題

問題 1：npm 全域安裝時出現 EACCES 權限錯誤

npm warn saveError EACCES: permission denied
# 或
npm error code EACCES

原因：npm 全域目錄由 root 擁有，一般用戶無寫入權限。
解法：使用 nvm 管理 Node.js 安裝，或修改 npm 全域目錄的擁有者：

# 推薦做法：改用 nvm（避免 sudo）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install --lts
npm install -g @anthropic-ai/claude-code

問題 2：command not found: claude（安裝後找不到指令）

原因：npm 全域 bin 目錄不在 shell 的 PATH 環境變數中。
解法：

# 取得 npm 全域 bin 目錄路徑
npm bin -g
# 範例輸出：/home/user/.nvm/versions/node/v20.11.0/bin

# 將上述路徑加入 ~/.zshrc 或 ~/.bashrc
echo 'export PATH="$HOME/.nvm/versions/node/v20.11.0/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

問題 3：登入後 API 呼叫失敗（401 / 403 錯誤）

原因：API Key 無效、已過期，或帳號餘額不足。
解法：

前往 console.anthropic.com 確認 API Key 狀態與帳單餘額
確認環境變數 ANTHROPIC_API_KEY 已正確載入（執行 echo $ANTHROPIC_API_KEY）
若使用 OAuth 登入，嘗試執行 claude logout 後重新 claude login
確認使用的 Claude 方案支援 API 存取（部分免費方案限制 API 使用）

問題 4：在 Windows 上出現路徑或換行字元錯誤

原因：Windows 原生 CMD / PowerShell 環境對 Unix 路徑與換行字元（LF vs CRLF）的相容性不佳。
解法：強烈建議在 WSL2 環境中使用 Claude Code。

# 安裝 WSL2（在 Windows PowerShell 以系統管理員身份執行）
wsl --install

# 進入 WSL2 後，重新安裝 Node.js 與 Claude Code
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install --lts
npm install -g @anthropic-ai/claude-code

若必須在原生 Windows 環境使用，請確保 Git 的換行字元設定為 core.autocrlf=input，並使用 Windows Terminal 作為終端機，以確保 ANSI 顏色碼正確顯示。

問題 5：/init 執行後 CLAUDE.md 內容不完整或錯誤

原因：專案結構過於龐大，或缺乏標準的設定檔（如 package.json、pyproject.toml）供 AI 參考。
解法：手動補充 CLAUDE.md 的關鍵資訊，尤其是啟動指令、測試方式與重要目錄說明。可多次執行 /init，每次指定不同的子目錄範圍，逐步累積完整的專案描述。