Claude Code 安裝教學：Windows（原生／WSL）、Mac、Homebrew、登入 Pro／Max 同常見錯誤

想在自己電腦用 Claude Code，最常卡住的通常不是指令本身，而是揀錯安裝方法、開錯終端機、用錯帳戶登入，或者根本不知道自己所在地是否受官方支援。本文按 Anthropic 現行官方文件整理 Mac 同 Windows 的安裝步驟，再講登入 Pro／Max、第一個 session、CLAUDE.md、更新和常見錯誤。

支援地區（2026 年 9 月 15 日核對）：Claude Code 官方系統要求把「Location：Anthropic supported countries」列為條件之一。截至 2026-09-15，香港並不在 Anthropic 官方支援國家／地區名單（涵蓋 Commercial API 及 Claude.ai）。名單會變，安裝或付款前請自行重查。本文只介紹官方安裝步驟，不提供 VPN、外地地址、借用電話或身份等任何規避方法；香港用家請先讀 Claude 香港訂閱指南。

一句答案：官方推薦「原生安裝」（Native Install）。Mac 在 Terminal 執行 curl -fsSL https://claude.ai/install.sh | bash；Windows 在 PowerShell 執行 irm https://claude.ai/install.ps1 | iex。原生安裝唔使先裝 Node.js，亦會在背景自動更新。裝好後在項目資料夾輸入 claude，用 Pro、Max、Team、Enterprise 或 Console 帳戶登入；Claude 免費方案不包括 Claude Code。

資料核對日期：2026 年 9 月 15 日。Claude Code 幾乎每日發佈新版本，指令、選單名稱和錯誤訊息都可能更新；本文每個步驟都附官方來源，遇到畫面不同時，以 Claude Code 官方安裝文件為準。

開始前：你需要乜帳戶同電腦？

帳戶：Pro、Max、Team、Enterprise 或 Console

官方安裝文件寫明，Claude Code 需要 Pro、Max、Team、Enterprise 或 Console 帳戶，Claude.ai 免費方案不包括 Claude Code。你亦可以透過 Amazon Bedrock、Google Cloud's Agent Platform 或 Microsoft Foundry 等第三方供應商使用，但本文只講個人最常用的 Pro／Max 訂閱登入。

以上是 Anthropic 官方美元標價，來源為 Claude 官方價格頁及 Max 方案說明（2026-09-15 核對），不包括適用稅項，Anthropic 可隨時調整價格和方案。5x、20x 是相對 Pro 的用量級別（官方說明為每個 session 的用量分別是 Pro 的 5 倍和 20 倍），不是固定訊息數；任何第三方或本站列出的港幣價，都不是 Anthropic 官方香港價格。應該揀 Pro、Max 5x 定 20x，請看 Claude Code 要用邊個 Claude 方案。

電腦同系統要求

• 作業系統：macOS 13.0 或以上；Windows 10 1809 或以上，或 Windows Server 2019 或以上；Ubuntu 20.04+、Debian 10+、Alpine Linux 3.19+。
• 硬件：4 GB 或以上 RAM，x64 或 ARM64 處理器。
• 網絡：必須連接互聯網。
• Shell：Bash、Zsh、PowerShell 或 CMD。
• 所在地：Anthropic 支援國家（見文首方格）。

留意官方系統要求沒有 Node.js。如果你見到要求「先安裝 Node.js 18」的舊教學，那是過時資料：原生安裝器根本不需要 Node.js；只有選用 npm 安裝才需要，而且由 v2.1.198 起要求 Node.js 22 或以上。

唔想用終端機？可以考慮 Desktop app

Claude Desktop app 已內置 Claude Code，毋須另外安裝 Node.js 或 CLI。官方提供 macOS（Intel 與 Apple Silicon 通用）、Windows x64、Windows ARM64 和 Linux（beta）版本。打開 app 後按頂部中間的「Code」分頁即可開始；如果一按就提示升級，代表帳戶需要先有 Pro、Max、Team 或 Enterprise 付費方案。

不過，Desktop app 不會順帶把 claude 指令裝進終端機。想在 Terminal、PowerShell 或 WSL 使用，仍然要按下文安裝 CLI。本文以下部分都以 CLI 為主。

揀安裝方法：原生、Homebrew、WinGet 定 npm？

官方現時提供幾種安裝途徑，分別主要在於「會否自動更新」和「是否需要額外工具」。先用下表揀定一種，同一部電腦最好只保留一種安裝，否則日後容易出現版本衝突。

建議：大部分人用原生安裝就夠——唔使 Node.js、會自動更新，亦是官方標明的推薦方法；電腦上出現多個安裝時，官方同樣建議只保留原生版。你本身已用 Homebrew 管理 Mac 軟件，或公司規定經 WinGet 安裝，才考慮套件管理器，並要記住自己定期升級。npm 在官方文件中已放在「Advanced installation options」，主要照顧已有 Node.js 工作流程的開發者；它安裝的其實是同一個原生程式，執行時亦不會調用 Node。

Mac 安裝教學

步驟 1：打開 Terminal

按 Cmd + Space 打開 Spotlight，輸入 Terminal，再按 Enter。

步驟 2A：原生安裝（推薦）

把以下一行貼到 Terminal，按 Enter：

curl -fsSL https://claude.ai/install.sh | bash

成功時會顯示 Claude Code successfully installed!。如果安裝器在「Setup notes」提示你修改 PATH，照住它列出的指令做即可。

步驟 2B：改用 Homebrew 安裝

brew install --cask claude-code

這個 cask 跟隨 stable channel；想新版本一推出就收到，可改為 brew install --cask claude-code@latest。現行官方文件列出的是以上 cask 指令，如在其他教學見到不同寫法，以官方頁面為準。如果 Homebrew 回應 Cask 'claude-code' is unavailable，代表本機索引太舊，先執行 brew update 再安裝。Homebrew 升級後會保留舊版本檔案，可定期執行 brew cleanup 釋放空間。

步驟 3：出現 command not found 點算？

如果輸入 claude 時出現 command not found: claude，通常是 ~/.local/bin 未加入 PATH。使用 zsh 時，執行：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

如果你用的是 Bash（例如 WSL 或 Linux 的預設 shell），改為寫入 ~/.bashrc：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

然後關閉並重開終端機，再試 claude --version。安裝器完成時在「Setup notes」列出的指令，亦是官方給你這部電腦的確切修正方法。

Windows 安裝教學：原生定 WSL？

先更正一個常見誤解：Windows 用 Claude Code 已經不一定要 WSL。官方文件現時提供三個選項：

簡單判斷：項目本身用 Windows 工具開發，就用原生；項目依賴 Linux 工具，或你想用 sandboxing 限制指令的執行範圍，就用 WSL 2。在 Windows 上，Sandboxing 只在 WSL 2 支援（原生 Windows 和 WSL 1 都不支援），這是原生和 WSL 之間最實際的分別。

方法 A：原生 Windows（PowerShell）

1. 按 Win + X，揀 Windows PowerShell（或 Terminal）。
2. 確認提示符號開頭有 PS，例如 PS C:\Users\YourName>；沒有 PS 即係 CMD。
3. 貼上以下指令，按 Enter。毋須以系統管理員身份執行。

irm https://claude.ai/install.ps1 | iex

如果你慣用 CMD，改用 CMD 版指令：

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

兩個指令貼錯地方會出現特定錯誤：看到 'irm' is not recognized as an internal or external command，代表你在 CMD 貼了 PowerShell 指令；看到 The token '&&' is not a valid statement separator，代表你在 PowerShell 貼了 CMD 指令。

Git for Windows 係咪一定要裝？

唔一定。沒有 Git for Windows 時，Claude Code 會用 PowerShell tool 執行 shell 指令；裝了 Git for Windows，Claude Code 會用 Git Bash 提供 Bash tool，官方文件亦建議在原生 Windows 安裝它。實際寫程式通常都要用 Git 做版本控制，所以對大部分開發者來說仍然值得安裝。

如果已安裝 Git，但 Claude Code 找不到 Git Bash，可以在 settings.json 指定路徑：

{
  "env": {
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
  }
}

WSL 環境不需要 Git for Windows。

方法 B：WSL 2

1. 先按 Microsoft 的指引啟用 WSL 2 並安裝一個 Linux 發行版（WSL 本身的安裝不在本文範圍）。
2. 打開 WSL 終端機，執行與 Mac 相同的 Linux 安裝指令：curl -fsSL https://claude.ai/install.sh | bash。
3. 之後都要在 WSL 終端機內啟動 claude，而不是在 PowerShell 或 CMD。
4. 登入時，如果瀏覽器顯示一段登入 code 而沒有自動跳回，把 code 貼到終端機的 Paste code here if prompted 提示處——這在 WSL2 很常見。

另外，Desktop app 在 Windows 亦可以把 session 放在 WSL 2 發行版內執行，適合想用圖形介面、但項目放在 WSL 的用家。

方法 C：WinGet

winget install Anthropic.ClaudeCode

WinGet 版不會自動更新，要定期執行 winget upgrade Anthropic.ClaudeCode。如果 Claude Code 正在執行，升級可能因 Windows 鎖住執行檔而失敗，先退出再升級。想由 Claude Code 代你執行 Homebrew 或 WinGet 升級，可以設定環境變數 CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1。

Windows 三個常見第一步錯誤

• 出現 Claude Code does not support 32-bit Windows：在 64-bit 電腦上，這代表你開咗「Windows PowerShell (x86)」這個 32-bit 版本。關閉它，從開始選單開啟名稱沒有 (x86) 的 Windows PowerShell，再重新安裝。
• 出現 Could not create SSL/TLS secure channel：多數發生在較舊的 Windows 10。先執行下面第一行設定 TLS 1.2，再重跑安裝；如果仍然失敗，按官方排解頁更新系統 CA 憑證，或向公司 IT 查詢會否有 proxy 攔截。
• 出現 'claude' is not recognized：代表 %USERPROFILE%\.local\bin 未加入使用者 PATH，用下面的 PowerShell 指令加入，然後重開終端機。

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
irm https://claude.ai/install.ps1 | iex

$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

驗證安裝：claude --version 同 claude doctor

claude --version

正常會顯示類似 2.1.211 (Claude Code) 的版本號（你看到的數字會不同）。截至 2026-09-15，官方 changelog 最新版本為 2.1.272；由於差不多每日都有新版，請以你電腦上 claude --version 的結果為準。

claude doctor

claude doctor 會列出唯讀的安裝和設定診斷，包括安裝健康狀況、設定檔驗證錯誤，以及附建議修正方法的警告，而且不會開始 session。遇到問題時，先跑一次 doctor 往往最快找到原因。

只從官方渠道安裝

官方程式檔都有代碼簽署：macOS 版由「Anthropic PBC」簽署並經 Apple 公證，Windows 版由「Anthropic, PBC」簽署，每個版本亦會發佈附 SHA256 checksum 的已簽署 manifest.json。只使用 claude.ai 的安裝指令、Homebrew 官方 cask、WinGet 的 Anthropic.ClaudeCode 或官方 npm 套件 @anthropic-ai/claude-code；不要下載來歷不明的「免安裝版」、修改版或第三方鏡像。Windows 用家可在 %USERPROFILE%\.local\bin 資料夾內執行 Get-AuthenticodeSignature .\claude.exe 檢查簽署。

登入 Pro／Max：瀏覽器授權同 API key 陷阱

第一次登入

1. 在終端機輸入 claude。首次啟動會打開瀏覽器視窗讓你登入。
2. 使用你平時登入 Claude 的同一個帳戶；Pro 和 Max 用家不需要另開帳戶。
3. 瀏覽器沒有自動打開：按 c 複製登入網址，自己貼到瀏覽器。
4. 瀏覽器顯示一段登入 code，而沒有跳回終端機：把 code 貼到 Paste code here if prompted 提示處。瀏覽器連不到 Claude Code 的本機回呼伺服器時就會這樣，WSL2、SSH 和 container 最常見。
5. 完成後，終端機會顯示 Login successful。

四個帳戶指令：/status、/usage、/login、/logout

• /status：查看版本、模型、帳戶和連線狀態，確認目前用哪種方式登入；如果同時設定了登入和 API key，它會標示沒有被使用的一個。
• /usage：查看方案用量上限和使用情況；Pro、Max、Team、Enterprise 方案會列出計入方案上限的分項。
• /login：切換帳戶或重新認證。如果之前用 Console（API）帳戶登入，可以用它轉回 Pro／Max 訂閱。
• /logout：登出，並重設首次啟動設定；下次執行 claude 會重新行一次登入和設定流程。

小心：ANTHROPIC_API_KEY 會令你改用 API 計費

如果你以前為其他項目或舊公司設定過 ANTHROPIC_API_KEY，官方指出這正是常見的出事原因。環境中有這個變數時，Claude Code 會在互動模式提示你一次是否批准使用這條 key，並記住你的選擇；一旦批准，就會用 API key 而不是訂閱——用量按 API 另行收費，而不是扣 Pro／Max 內含用量。用 claude -p 非互動模式時，只要設定了 key 就一定會用。之後想改變選擇，可在 /config 的「Use custom API key」開關調整（只在設定了這個變數時出現）。想改回用訂閱：

Mac、Linux、WSL：

unset ANTHROPIC_API_KEY
claude

Windows PowerShell：

Remove-Item Env:ANTHROPIC_API_KEY
claude

然後在 Claude Code 內輸入 /status 確認登入方式。記得同時從 shell 設定檔（例如 ~/.zshrc、~/.bashrc 或 ~/.profile）刪除 export ANTHROPIC_API_KEY=... 這一行，否則下次開終端機又會生效；Windows 用家要檢查 PowerShell 設定檔 $PROFILE 和使用者環境變數。

用量與 Claude 網頁版共用

Pro 和 Max 的用量限制由 Claude 和 Claude Code 共用：你在 claude.ai 聊天、在終端機跑 Claude Code，都計入同一組用量上限，VS Code、Cursor 等 VS Code 分支和 JetBrains IDE 亦一樣；可用 /usage 查看目前用量。五小時 session、為何大型 repo 消耗更快、點樣減少 context 浪費，請看 Claude Pro、Max 與 Claude Code 用量限制。

登入資料存在哪裏？不要與人共用

• macOS：加密的 macOS Keychain；如果 Keychain 拒絕寫入（例如在 SSH session 中被鎖住），會改存到 ~/.claude/.credentials.json（檔案權限 0600）。
• Linux：~/.claude/.credentials.json（檔案權限 0600）。
• Windows：%USERPROFILE%\.claude\.credentials.json，沿用使用者資料夾的存取權限，預設只限你的帳戶讀取。

這個檔案等同你的登入憑證：不要複製給別人、放入 Git repo、上載到雲端硬碟或貼到聊天群組，也不要借用或共用別人的登入。任何聲稱「共用帳戶或轉交憑證很安全」的說法都不可信。帳戶保安可以用 AI 帳戶安全檢查表逐項核對。

第一個 session：先在測試 repo 試

第一次請不要直接在公司正式項目試。原因很實際：官方快速入門寫明，Pro、Max 和 Team 方案的互動終端 session 預設以 Auto mode 開始——由分類器代你審核操作，Claude 會在不逐一詢問你的情況下編輯大部分檔案、執行大部分指令；其他方案則由 Manual mode 開始。先在一個可以隨時刪除、受 Git 管理的測試資料夾練習，出錯都可以還原。

有兩點要留意。第一，官方說明安裝或升級後的第一個 session，可能因功能設定尚未下載而以 Manual mode 開始，下一個 session 才轉為 Auto mode；你的設定或公司政策亦可以改變起始模式。第二，Auto mode 作為預設要求 Claude Code 2.1.228 或以上（macOS、Linux、WSL）或 2.1.233 或以上（原生 Windows）。實際用緊哪個模式，以終端機底部狀態列為準：⏵⏵ auto mode on 代表 Auto mode，⏸ manual mode on 代表 Manual mode。

mkdir claude-code-practice
cd claude-code-practice
git init
claude

Windows 原生環境要先安裝 Git for Windows 才有 git 指令。你亦可以用一個自己熟悉的小型公開範例項目，cd 進去再輸入 claude。

三個適合第一次試的提示

1. what does this project do?（官方快速入門的例子；用中文問「呢個項目做乜？」亦可以）
2. 「幫我建立一個簡單的 index.html，顯示今日日期。先列出計劃和會改動的檔案，等我確認先動手。」
3. 「列出你剛才改動了哪些檔案，逐一解釋原因。」

權限模式同必學快捷鍵

建議做法：練習時先按 Shift+Tab 轉為 Manual mode，觀察 Claude 每一步想做甚麼；熟悉之後才決定是否用回 Auto mode。每次讓 Claude 大改之前先 git commit，完成後用 git diff 檢查改動。如需截圖分享，先遮蓋電郵、帳戶名稱、所在地和 IP。

CLAUDE.md 入門：讓 Claude 記住項目規則

CLAUDE.md 是寫給 Claude Code 看的項目說明，例如技術棧、常用指令、寫法規範和不可觸碰的檔案。最快的做法是在項目內輸入 /init，Claude 會自動產生一份起始 CLAUDE.md；如果已經有，/init 會建議改善，而不會直接覆蓋。

• 官方建議每個 CLAUDE.md 盡量少於 200 行，只寫每次都要遵守的重點。
• Claude Code 讀取的是 CLAUDE.md，不是 AGENTS.md。如果 repo 已有 AGENTS.md 給其他 coding agent，可以建立一個 CLAUDE.md，在內容寫 @AGENTS.md 匯入，避免兩份規則分歧。
• 用 /memory 開啟和編輯這些檔案。

完整的 CLAUDE.md 寫法和第一個實際項目示範，會在本站另一篇 Claude Code 新手教學詳細介紹。

更新 Claude Code 同版本管理

原生安裝會在啟動時及執行期間定期檢查更新，於背景下載和安裝，下次啟動 Claude Code 時生效。想即時更新：

claude update

更新成功會顯示 Successfully updated from <舊版本> to version <新版本>；已是最新則顯示 Claude Code is up to date (<版本>)。

latest 定 stable？

在 Claude Code 內輸入 /config，揀 Auto-update channel：預設是 latest，新功能一推出就收到；stable 通常是約一星期前的版本，並會跳過有重大問題的版本。公司電腦或重視穩定的用家可以揀 stable。你亦可以在 settings.json 寫入：

{
  "autoUpdatesChannel": "stable"
}

Homebrew 則以 cask 名稱決定 channel：claude-code 跟 stable，claude-code@latest 跟 latest。

套件管理器要自己升級

• Homebrew：brew upgrade claude-code 或 brew upgrade claude-code@latest，視乎你裝了哪個 cask。
• WinGet：winget upgrade Anthropic.ClaudeCode。
• npm：npm install -g @anthropic-ai/claude-code@latest；避免 npm update -g，它可能不會升到最新版本。
• apt／dnf／apk：跟你平時的系統升級流程。

如果公司需要統一管理版本、停止背景自動更新，可以在 settings.json 的 env 把 DISABLE_AUTOUPDATER 設為 "1"；這只會停止背景檢查，claude update 仍可手動使用。

點解要保持更新？

新模型往往有最低版本要求。Anthropic 說明，在 Claude Code 使用 Fable 5 需要 2.1.170 或以上；Fable 5.1 的最低版本，Claude Code 模型設定文件寫 2.1.257；Help Center 寫 2.1.255，但公開 CHANGELOG 沒有 2.1.255 的版本條目，公開發布亦沒有這個版本，所以更新到 2.1.257 或以後就可以；版本未達要求，就算方案有資格亦用不到相應模型。上文提到的 Auto mode 預設，同樣有最低版本要求。可以用 /model 查看和切換目前可用的模型。至於 Fable 在各方案如何計費，屬方案選擇問題，請看 Claude Code 方案指南。

常見錯誤一覽：錯誤、原因、解決方法

解除安裝

• 原生安裝（Mac、Linux、WSL）：rm -f ~/.local/bin/claude，再 rm -rf ~/.local/share/claude。
• 原生安裝（Windows PowerShell）：Remove-Item -Path "$env:USERPROFILE\.local\bin\claude.exe" -Force，再 Remove-Item -Path "$env:USERPROFILE\.local\share\claude" -Recurse -Force。
• Homebrew：brew uninstall --cask claude-code（裝了 latest 版就改為 claude-code@latest）。
• WinGet：winget uninstall Anthropic.ClaudeCode。
• npm：npm uninstall -g @anthropic-ai/claude-code。

刪除 ~/.claude 會一併刪除所有設定、已允許的工具、MCP 伺服器設定和 session 歷史；在 Linux 和 Windows（以及 macOS Keychain 無法寫入時），這個資料夾亦存放登入憑證檔。除非確定要完全清除，否則只移除程式本身即可。VS Code 擴充、JetBrains 插件和 Desktop app 亦會寫入 ~/.claude/，要完全移除便要先解除安裝它們。

下一步

• 未決定用哪個方案：看 Claude Code 要用邊個 Claude 方案：Free、Pro、Max 5x 定 20x。
• 經常撞到用量上限：看 Claude 用量限制與 Claude Code 共用用量。
• 香港資格和訂閱前檢查：看 Claude 香港訂閱指南。
• 其他介面：Claude Code 亦可以在網頁、Desktop app、VS Code 與 JetBrains IDE、Slack，以及 GitHub Actions 和 GitLab 的 CI/CD 使用；IDE 設定和 CLAUDE.md 實戰項目會另文介紹。

如果你正在做購買前研究，可到本站 Claude 方案服務頁了解服務內容（Claude Code 包含在 Pro 及以上方案）。頁面上的港幣價錢是本站獨立服務總價，不是 Anthropic 官方香港價格；下單前請閱讀服務條款，並先了解代充與成品號涉及的憑證、條款和停權風險。任何方式都不會改變文首所述的官方支援地區狀態。

結論

裝 Claude Code 其實只需一行指令：Mac 用 install.sh，Windows 用 install.ps1，唔使 Node.js，Windows 亦唔一定要 WSL。真正要花心機的是其餘幾步——用正確帳戶登入並以 /status 確認沒有被 API key 蓋過、第一次在受 Git 管理的測試資料夾練習並學識 Shift+Tab 和 Esc、選好 latest 或 stable 更新方式，以及出錯時先跑 claude doctor。至於所在地是否受支援，請以官方名單為準，不要依賴任何繞過方法。