---
title: "安裝和更新 Claude Code"
description: "Claude Code 安裝不要只複製一條命令。先選原生安裝器、Homebrew、WinGet 或 Linux 包管理器，再驗證 PATH、doctor 和更新策略。"
canonical: "https://xiangyugongzuoliu.com/tag/claude-code"
verifiedAt: "2026-05-08"
---

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

> [!NOTE]
> **這一章用 12 分鐘換什麼**：上一章先講 Claude Code 是什麼。這一章只解決一件事：怎麼把它正確裝到本機，並確認以後能更新、能被 PATH 找到、能跑健康檢查。

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

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

這會帶來兩個問題：

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

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

| 安裝通道 | 適合誰 | 自動更新 |
|------|------|------|
| 原生安裝器（Native installer） | 大多數個人使用者和新手 | 是 |
| Homebrew | macOS 使用者統一用 brew 管工具 | 預設否，可選擇啟用 |
| WinGet | Windows 使用者統一用 winget 管工具 | 預設否，可選擇啟用 |
| apt / dnf / apk | Linux 使用者統一用系統包管理器 | 否 |
| npm | 舊方式或特殊環境兜底 | 不推薦作為首選 |

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

> [!IMPORTANT]
> **一句話選擇**：不知道選什麼，就用原生安裝器；已經有嚴格包管理習慣，再用 Homebrew、WinGet 或 Linux 包管理器。

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

| 你的情況 | 推薦通道 |
|------|------|
| 不確定怎麼選，想省心自動更新 | 原生安裝器 |
| macOS 上所有開發工具都走 Homebrew | Homebrew |
| Windows 上統一用 WinGet 管軟體 | WinGet |
| Linux 機器要求走系統 repo | apt / dnf / apk |
| 舊環境、特殊約束、臨時兜底 | npm，但不作為新手首選 |

## 2. 先看系統要求

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

| 型別 | 要求 |
|------|------|
| macOS | macOS 13.0+ |
| Windows | Windows 10 1809+ 或 Windows Server 2019+ |
| Linux | Ubuntu 20.04+、Debian 10+、Alpine Linux 3.19+ |
| 架構 | x64 或 ARM64 |
| 記憶體 | 4 GB+ |
| Shell | Bash、Zsh、PowerShell 或 CMD |
| 網路 | 能訪問網際網路 |
| 地區 | 位於 Anthropic 支援的國家或地區 |

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

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

> [!TIP]
> 系統要求基線會隨官方支援矩陣緩慢上調。本表是當前抓取的版本下限，**安裝前請對照官方 [Advanced setup § System requirements](https://code.claude.com/docs/en/setup#system-requirements) 當前頁**確認你的系統是否在支援範圍內。

> [!WARNING]
> **不要跨環境安裝**：專案在 WSL 檔案系統裡，就在 WSL 終端裡安裝和執行 `claude`；專案在 Windows 原生路徑裡，就用 Windows 原生入口。不要在 PowerShell 裡裝完後跨去操作 WSL 專案。

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

macOS、Linux、WSL 用這條：

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

Windows PowerShell 用這條：

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

Windows CMD 用這條：

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

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

| 你看到的提示符 | 該用哪條 |
|------|------|
| `$` 或 `%` | macOS / Linux / WSL 命令 |
| `PS C:\...>` | PowerShell 命令 |
| `C:\...>` | CMD 命令 |

常見報錯也能直接判斷：

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

> [!TIP]
> **安裝後先重開終端**：很多 PATH 問題不是安裝失敗，而是當前 shell 還沒載入新路徑。重開終端後再跑 `claude --version`。

## 4. Homebrew、WinGet 和 Linux 包管理器

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

macOS Homebrew：

```bash
brew install --cask claude-code
```

Windows WinGet：

```powershell
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`：最新通道，更快拿到新版本。

> [!IMPORTANT]
> **更新策略別記錯**：原生安裝器會自動更新；Homebrew 和 WinGet 預設不自動更新，但可以在 `settings.json` 裡設 `"env": { "CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE": "1" }` 讓 Claude Code 後臺跑升級命令（WinGet 在 Claude Code 執行時升級可能因執行檔被鎖失敗，會回退到提示手動命令）；apt、dnf、apk 仍要手動升級。用包管理器就要把升級命令納入你的維護習慣。

## 5. 不推薦新手從 npm 開始

早期很多教程會寫：

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

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

原因很現實：

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

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

排查時可以看：

```bash
which claude
claude --version
```

Windows PowerShell：

```powershell
where.exe claude
claude --version
```

> [!CAUTION]
> **不要混裝多個來源**：同一臺機器上同時有 npm、Homebrew、原生安裝，很容易出現“我升級了 A，但終端實際跑的是 B”的問題。

## 6. 安裝後怎麼驗證

安裝完成後按三步驗證。

<Steps>

<Step>

### 看命令是否能找到

```bash
claude --version
```

如果報 `command not found`，先重開終端再試一次（PATH 可能沒重新整理）；仍失敗查 § 9 排障順序。

</Step>

<Step>

### 跑健康檢查

```bash
claude doctor
```

`claude doctor` 會檢查安裝健康度、設定、MCP 配置、環境等問題。它比單純看版本更有價值——版本能跑不代表配置和依賴都對。

</Step>

<Step>

### 進入真實專案試執行

```bash
cd your-project
claude
```

進入後先不要大改程式碼，先問：

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

如果這一步能讀懂專案，說明安裝、登入和基礎檔案訪問基本可用。

</Step>

</Steps>

> [!TIP]
> **最小驗收**：`claude --version` 能輸出版本，`claude doctor` 無關鍵錯誤，真實專案裡能回答專案結構，才算安裝完成。

## 7. 更新通道怎麼選

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

例如選擇 stable：

```json
{
  "autoUpdatesChannel": "stable"
}
```

常見選擇：

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

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

```json
{
  "minimumVersion": "2.1.0"
}
```

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

```bash
claude update
```

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

```json
{
  "env": {
    "DISABLE_AUTOUPDATER": "1"
  }
}
```

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

> [!WARNING]
> **不要為了新功能犧牲主力環境**：如果 Claude Code 是你的日常生產工具，主力機用 stable，備用機或測試環境用 latest 更穩。

## 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 選擇時按專案位置判斷：

| 專案位置 / 需求 | 推薦入口 |
|------|------|
| 專案在 Windows 原生路徑，主要用 PowerShell 或 VS Code Windows | Native Windows |
| 專案在 WSL 檔案系統，依賴 Linux 工具鏈 | WSL 2 |
| 需要 sandboxed command execution（沙盒命令執行） | WSL 2 |
| 機器無法使用 WSL 2 | WSL 1 兜底，但不支援 sandboxing |

## 9. 常見問題先這樣排

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

> [!IMPORTANT]
> **排障順序**：先確認“終端實際執行的是哪個 `claude`”，再看登入、網路、許可權。路徑不清楚時，後面所有排查都會偏。

## 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。

> [!IMPORTANT]
> **過關標準**：你能為自己的系統選出一個安裝通道，並說清它怎麼更新、怎麼驗證、出了 PATH 問題先查哪裡。

<details id="glossary">
<summary><b>本篇術語速查表</b></summary>

- **Native installer**：原生安裝器，官方推薦的安裝方式，支援自動更新。
- **Homebrew**：macOS 包管理器，可以安裝 Claude Code；預設不自動更新，可選擇啟用 Claude Code 後臺升級。
- **WinGet**：Windows 包管理器，可以安裝 Claude Code；預設不自動更新，可選擇啟用 Claude Code 後臺升級。
- **PATH**：命令搜尋路徑，shell 用來查詢 `claude` 命令的位置列表。
- **`claude doctor`**：健康檢查命令，檢查安裝、配置、MCP、環境等問題。
- **Auto-update channel**：自動更新通道，原生安裝使用的 latest / stable 更新選擇。
- **`minimumVersion`**：最低版本要求，專案或團隊用來提醒更新到某個最低版本。
- **WSL**：Windows Subsystem for Linux，Windows 上執行 Linux 環境的機制。
- **Git Bash**：Git for Windows 附帶的 Bash，Windows 原生 Claude Code 使用 Bash tool 的常見依賴。
- **Sandboxing**：沙盒，限制命令程序檔案和網路訪問的安全機制。

</details>

## 官方來源

- [Advanced setup](https://code.claude.com/docs/en/setup)
- [Quickstart](https://code.claude.com/docs/en/quickstart)
- [Troubleshoot installation and login](https://code.claude.com/docs/en/troubleshoot-install)
- [Claude Code settings](https://code.claude.com/docs/en/settings)

## 接下來去哪

<Cards>
  <Card href="/zh-Hant/docs/claude-code/official/00-getting-started/authentication" title="登入與認證" description="安裝完成後，下一步是登入：訂閱、Console、企業雲供應商和憑據優先順序怎麼選。" />
  <Card href="/zh-Hant/docs/claude-code/official/00-getting-started/overview" title="Claude Code 是什麼（上一篇）" description="如果你還不確定為什麼要裝 Claude Code，先回到產品定位和 agentic loop。" />
  <Card href="/zh-Hant/docs/claude-code/official/00-getting-started/platforms" title="選擇平臺與整合" description="安裝後不一定只在終端用。看 CLI、Desktop、IDE、Web 和 Mobile 的入口差異。" />
</Cards>

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