安裝和更新 Claude Code

安裝 Claude Code 最容易出錯的地方，不是命令本身，而是選錯了安裝通道。官方當前優先推薦原生安裝器（native installer）；Homebrew、WinGet、apt、dnf、apk 也能用，但更新策略不同。——翔宇

1. 先選安裝通道，不要先複製命令

新手看到安裝文件，通常第一反應是找一條命令複製。

這會帶來兩個問題：

• 在 PowerShell 裡複製了 CMD 命令。
• 用 Homebrew 裝完後，以為它會自動更新。

所以先問自己：你要的是官方推薦的自動更新，還是系統包管理器統一管理？

官方 Advanced setup 現在明確寫到：Homebrew、WinGet、apt、dnf、apk 安裝預設不會自動更新。要拿到新功能和安全修復，需要手動升級；Homebrew 和 WinGet 可以透過 CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1 選擇讓 Claude Code 後臺升級自身，Linux 包管理器仍需要手動升級。

把選擇壓成一張移動端也能讀的判斷表：

2. 先看系統要求

官方 setup 文件列出的基礎要求可以壓成這張表：

還有兩個新手容易忽略的點：

• Windows 原生環境推薦安裝 Git for Windows，這樣 Claude Code 可以使用 Bash tool；沒有 Git Bash 時會回退到 PowerShell。
• WSL 2 適合 Linux 工具鏈和 sandboxed command execution；Native Windows 不支援 sandboxing。

3. 原生安裝器：官方推薦首選

macOS、Linux、WSL 用這條：

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

Windows PowerShell 用這條：

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

Windows CMD 用這條：

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

如果你不熟終端，先看命令提示符：

常見報錯也能直接判斷：

• irm 不是內部或外部命令：在 CMD 裡跑了 PowerShell 命令。
• && 不是有效語句分隔符：在舊 PowerShell 裡跑了 CMD 命令。
• claude: command not found：PATH 沒重新整理或安裝目錄沒進 PATH。

4. Homebrew、WinGet 和 Linux 包管理器

如果你想讓系統包管理器統一管理 Claude Code，也可以。

macOS Homebrew：

brew install --cask claude-code

Windows WinGet：

winget install Anthropic.ClaudeCode

Linux apt / dnf / apk 官方也支援，但第一次配置會涉及新增 Anthropic package repository 和簽名 key。新手不需要背命令，按官方 setup 頁面複製當前命令即可。

重點不是怎麼裝，而是怎麼更新：

• Homebrew stable：brew upgrade claude-code。
• Homebrew latest：brew upgrade claude-code@latest。
• WinGet：winget upgrade Anthropic.ClaudeCode。
• apt：sudo apt update && sudo apt upgrade claude-code。
• dnf：sudo dnf upgrade claude-code。
• apk：sudo apk upgrade claude-code。

Homebrew 有兩個 cask：

• claude-code：穩定通道，通常比最新發布慢一些，避開明顯迴歸。
• claude-code@latest：最新通道，更快拿到新版本。

5. 不推薦新手從 npm 開始

早期很多教程會寫：

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

現在不建議把它作為新手首選。

原因很現實：

• Node / npm 版本和全域性目錄經常出許可權問題。
• sudo npm install -g 容易留下 root-owned 檔案。
• 多個安裝來源並存時，PATH 裡到底跑的是哪個 claude 很難判斷。

如果你已經裝過 npm 版，又遇到登入、更新、命令路徑混亂，官方 troubleshoot-install 文件建議遷移到原生安裝。

排查時可以看：

which claude
claude --version

Windows PowerShell：

where.exe claude
claude --version

6. 安裝後怎麼驗證

安裝完成後按三步驗證。

claude --version

claude doctor

cd your-project
claude

这个项目是做什么的？请先不要改代码，只解释项目结构和主要入口。

7. 更新通道怎麼選

原生安裝器會自動更新。你可以在 Claude Code 裡用 /config 調整 auto-update channel（自動更新通道），也可以寫入 settings（設定檔案）。

例如選擇 stable：

{
  "autoUpdatesChannel": "stable"
}

常見選擇：

• latest：想盡快拿到新功能，能接受偶發迴歸。
• stable：日常工作主力機，優先穩定。

團隊場景可以用 minimumVersion 提醒大家更新到某個最低版本：

{
  "minimumVersion": "2.1.0"
}

不想等後臺自動檢查、立刻拉一次更新：

claude update

需要徹底關閉後臺自動更新（例如自分發 Claude Code 給團隊、要鎖版本）：

{
  "env": {
    "DISABLE_AUTOUPDATER": "1"
  }
}

DISABLE_AUTOUPDATER 只關後臺檢查；claude update 和 claude install 仍能跑。要堵住所有更新路徑（包括手動），改用 DISABLE_UPDATES。

8. Windows 怎麼選：Native、WSL 2、WSL 1

Windows 使用者最容易糾結。

官方當前把 Windows 分成三種：

• Native Windows：適合 Windows 原生專案、PowerShell、VS Code Windows 環境；不支援 sandboxing。
• WSL 2：適合 Linux 工具鏈、Node/Python/Rust 等類 Unix 專案；支援 sandboxing。
• WSL 1：無法使用 WSL 2 時兜底；不支援 sandboxing。

簡單判斷：

• 專案平時就在 Windows 路徑裡開發，用 Native Windows。
• 專案平時就在 WSL 裡開發，用 WSL 2。
• 需要 sandboxed command execution，優先 WSL 2。
• 不要讓 Claude Code 跨 Windows/WSL 邊界操作同一個專案。

Windows 選擇時按專案位置判斷：

9. 常見問題先這樣排

• claude 找不到：重開終端、檢查 PATH、看 which claude / where.exe claude。
• 版本不是剛裝的：可能混裝，檢查多個安裝來源。
• 登入失敗：看認證章節，確認賬號、地區、網路和憑據。
• 搜尋檔案失敗：確認 ripgrep、檔案許可權和當前目錄。
• Windows 命令失敗：確認 PowerShell、CMD、Git Bash 沒混用。
• WSL 專案訪問慢：確認專案是否放在 WSL 檔案系統內。
• 更新後行為異常：看版本號，必要時切 stable 或按官方排障回退。

10. 本章自檢

試著用自己的話回答：

1. 為什麼新手優先推薦原生安裝器，而不是一上來用 Homebrew / WinGet？對應 §1-§4。
2. Homebrew、WinGet、apt、dnf、apk 安裝方式和原生安裝的最大差別是什麼？對應 §4。
3. 安裝後為什麼要跑 claude doctor，而不是隻看 claude --version？對應 §6。
4. Windows 專案和 WSL 專案為什麼不要跨環境操作？對應 §8。
5. 出現命令混亂時，為什麼先看 which claude / where.exe claude？對應 §9。

官方來源

• Advanced setup
• Quickstart
• Troubleshoot installation and login
• Claude Code settings

接下來去哪

如果只記一個判斷：安裝不是結束，而是建立可驗證、可更新、路徑清晰的本地入口；命令能跑、doctor 透過、真實專案能讀懂，才算裝好。