安裝與更新 Claude Code CLI：Mac、Linux、Windows

安裝 Claude Code 在每個平台上都只要一道指令：macOS、Linux 與 WSL 執行 curl -fsSL https://claude.ai/install.sh | bash，Windows PowerShell 則是 irm https://claude.ai/install.ps1 | iex；更新不是自動完成（預設值），就是一句 claude update。多數文章略過的，正是第一道指令之後的事：有四種方式時該挑哪一種安裝方法、自動更新程式如何運作又該怎麼關掉、如何鎖定特定版本，以及每一種安裝方式該怎麼乾淨地移除。本頁就是這份參考資料，一項任務配一張表，內容更新至 v2.1.224（2026 年 8 月）。¹

TL;DR

• 請使用原生安裝程式。 它沒有 Node.js 相依性，為各平台提供經過測試的二進位檔，而且自 v2.1.113 起就是預設方式。npm 套件屬於舊有做法，自 v2.1.15 起已淘汰，現在還要求 Node.js 22 以上。¹
• 更新預設是自動的： Claude Code 會在啟動時以及工作階段進行中定期檢查，於背景下載，並在下次啟動時套用。claude update 則是立刻強制更新一次。²
• 關閉更新有兩個不同的開關： DISABLE_AUTOUPDATER=1 會停止背景更新；DISABLE_UPDATES=1（v2.1.118 以上）則封鎖所有更新途徑，連手動的 claude update 也一併擋下。²
• 鎖定版本只要把版本號傳給安裝程式：curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58。用 claude --version 確認目前執行的版本，用 /release-notes 瀏覽各版本的異動。¹²
• 只要行為不對勁，先跑 claude doctor——它會回報安裝類型、版本與偵測到的問題；自 v2.1.205 起，工作階段內的 /doctor 不只能診斷，還能直接修復設定問題。²

該如何安裝 Claude Code CLI？

依平台各一道指令：

# 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

偏好套件管理器？兩種都是一等公民：

brew install --cask claude-code          # macOS / Linux (stable channel)
winget install Anthropic.ClaudeCode      # Windows

接著在專案目錄中執行 claude，並以 Claude Pro/Max/Team 訂閱或 Anthropic API 帳號完成驗證。¹ 原生安裝程式不需要 Node.js、不需要 sudo，也不需要任何預先安裝的東西。若非得走舊有的 npm 途徑（npm install -g @anthropic-ai/claude-code），它需要 Node.js 22 或更新版本，而且絕對不要搭配 sudo 執行——root 擁有的全域模組會留下比安裝本身更難纏的權限問題。¹ 已經用 npm 裝好了？claude install 會就地把你移轉到原生二進位檔。

至於首次工作階段的設定——驗證方式的選擇、第一個提示詞、權限模式——快速上手教學涵蓋了從零到第一個成果的完整路徑。

Claude Code 支援哪些平台？

關於 Windows 反覆出現的那個問題，答案是：原生 Windows 可以用，而且不需要系統管理員權限；Anthropic 自己的建議是依專案所在位置與實際需求來選擇，想要 Linux 工具鏈或沙箱化的指令執行時就選 WSL 2，而同一支 Linux 安裝程式也能在其中執行。³ Claude Code 自動模式不是安全邊界一文主張，真正的邊界是作業系統層級的隔離，而不是自動模式。

該如何更新 Claude Code？

通常你什麼都不必做。Claude Code 預設會自動更新——它會在啟動時以及工作階段進行中定期檢查新版本，於背景下載，並在下次啟動時套用。² 若想立刻強制更新，或你已停用自動更新程式：

claude update

透過套件管理器安裝的版本，走各自的管道更新——brew upgrade --cask claude-code、winget upgrade Anthropic.ClaudeCode；自 v2.1.129 起，設定 CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1 可讓這類安裝在背景執行套件管理器升級，並提示重新啟動。²

控制更新靠的是兩個各自獨立的開關，在管制嚴格的環境裡，這個差別相當要緊：

兩者都可設為環境變數，或寫在 settings.json 的 "env" 底下。²

該如何安裝特定版本？

把版本號傳給安裝程式即可——想重現某個 bug、讓團隊停在已知可用的版本，或是要回退時，這招都很好用：

# Specific version
curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58

# Latest, explicitly
curl -fsSL https://claude.ai/install.sh | bash -s latest

# Windows PowerShell, specific version
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 1.0.58

用 claude --version 確認，再透過工作階段內的 /release-notes 選擇器閱讀各版本的異動。² 若要鎖定版本，請一併加上 DISABLE_AUTOUPDATER=1——否則自動更新程式會在下次啟動時客客氣氣地幫你解除鎖定。（若連手動的 claude update 也要擋掉，請改用 DISABLE_UPDATES=1。）

該如何解除安裝 Claude Code？

解除安裝的方式要與安裝方式相符：

設定另外存放在 ~/.claude/，所以移除二進位檔並不會刪掉設定、技能或歷史紀錄——只有在你真的想從一張白紙重新開始時，才連同該目錄一起刪除。¹

一張表看完整個生命週期

而當事情不對勁時——回報的版本錯了、更新後找不到指令、安裝只套用了一半——在 shell 執行 claude doctor 會回報安裝類型、版本與偵測到的問題；工作階段內的 /doctor（v2.1.205 以上）則會做一次完整健檢，並能修好它所發現的問題。² 安裝之後的一切——設定、權限、hooks、MCP 與子代理——都收錄在 Claude Code 完整指南裡。

Windows 疑難排解：無法辨識 claude、用錯 Shell、指令碼遭封鎖

Windows 上的失敗，大多屬於以下九種之一，每一種都有可辨認的錯誤訊息。下列每一項修正都出自 Anthropic 的安裝疑難排解頁面與設定頁面，內容以 2026 年 9 月 7 日為準。³⁴

1. 'claude' is not recognized as an internal or external command（CMD）或 The term 'claude' is not recognized as the name of a cmdlet（PowerShell）。 安裝程式把 claude.exe 放在 %USERPROFILE%\.local\bin\claude.exe；問題要不是該目錄不在您的 PATH 上，就是您仍待在當初執行安裝的那個終端機裡，而它保留的是舊的 PATH。先檢查、再加入，然後開啟一個新的終端機：⁴

$env:PATH -split ';' | Select-String '\.local\\bin'      # no output = not on PATH
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

在 CMD 中，檢查指令是 echo %PATH% | findstr /i "local\bin"，修正方式則是在「環境變數」中把 %USERPROFILE%\.local\bin 加入使用者的 PATH。⁴

2. 'irm' is not recognized、The token '&&' is not a valid statement separator 或 A parameter cannot be found that matches parameter name 'fsSL'。 您執行的是另一種 shell 的安裝指令。找不到 irm，代表您身在 CMD（提示字元顯示 C:\）：請改用上方的 CMD 安裝指令，或開啟 PowerShell（PS C:\）。&& 遭拒，代表您在 PowerShell 中執行了 CMD 的指令：請改用 irm https://claude.ai/install.ps1 | iex。出現 fsSL 的錯誤，代表您把 macOS/Linux 的 curl -fsSL ... | bash 指令貼進了 PowerShell，而在 PowerShell 裡，curl 是 Invoke-WebRequest 的別名。若指令印出了指令碼的文字卻什麼也沒安裝，表示您只執行了下載的那一半，少了負責執行的那一段。⁴

3. running scripts is disabled on this system / PSSecurityException。 PowerShell 的執行原則封鎖了 npm 建立的 .ps1 啟動墊片（npm.ps1、claude.ps1）。這不影響原生安裝程式，因為它是透過 iex 執行下載下來的文字，而不是一個儲存下來的檔案；至於把 ClaudeInstall.ps1 存檔後再以 -ExecutionPolicy Bypass -File 執行，並不在 Anthropic 文件記載的安裝途徑之列（設定頁面只列出 irm 指令、CMD 安裝程式、WinGet 與 npm）。修正方式依序為：Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser；或改為呼叫 claude.cmd（該原則不涵蓋 .cmd）；或以原生安裝程式取代 npm 安裝。⁴

4. iex 的剖析錯誤中引用了 HTML 標籤或 CSS，或出現 curl: (22) The requested URL returned error: 403。 安裝網址傳回的是網頁，而不是指令碼。若頁面寫著「App unavailable in region」，表示 Claude Code 並未在您所在的國家或地區提供；否則就是有代理伺服器或過濾機制擋在中間。可用 curl.exe -sI https://downloads.claude.ai/claude-code-releases/latest 測試連線能力（請明確呼叫 curl.exe，因為 PowerShell 的 curl 別名不接受 -sI）：第一行若是 200，代表主機可以連上，先前的失敗只是暫時性的。文件記載的替代方案是 winget install Anthropic.ClaudeCode。⁴

5. Could not establish trust relationship for the SSL/TLS secure channel，或 CRYPT_E_NO_REVOCATION_CHECK (0x80092012)。 遇到前者，請在執行安裝程式之前強制使用 TLS 1.2：[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12。撤銷相關的錯誤代表您的網路封鎖了憑證撤銷查詢：請在 CMD 的 curl 指令中加上 --ssl-revoke-best-effort，或改用 PowerShell 安裝程式，它透過 .NET 下載，能容忍連不上的撤銷伺服器。⁴

6. The process cannot access the file ... because it is being used by another process。 先前的安裝程式仍在執行，或防毒軟體正在掃描 %USERPROFILE%\.claude\downloads 中下載到一半的檔案。請關閉其他 PowerShell 視窗，等掃描結束，然後執行：⁴

Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\downloads"
irm https://claude.ai/install.ps1 | iex

7. 執行的版本不對，或兩份安裝彼此打架。 where.exe claude 會列出您 PATH 上的每一個 claude；Test-Path "$env:USERPROFILE\.local\bin\claude.exe" 則能確認原生安裝程式是否放好了它的二進位檔。保留原生版本，移除其餘的（winget uninstall Anthropic.ClaudeCode、npm uninstall -g @anthropic-ai/claude-code，舊有的本機 npm 安裝則用 Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\local"）。claude doctor 會印出它實際執行的安裝類型與版本。⁴

8. Claude Code on Windows requires either Git for Windows (for bash) or PowerShell。 兩種 shell 都找不到。Git for Windows 是選用的：沒有它，Claude Code 會透過其 PowerShell 工具執行指令；裝了它，Bash 工具就會使用 Git Bash。若已安裝 Git Bash 卻偵測不到，請在 settings.json 中指定它的路徑：³

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

9. Claude Code does not support 32-bit Windows。 您在 64 位元的電腦上開啟了 x86 版的 PowerShell 項目。請開啟「Windows PowerShell」，而不是標有「(x86)」的那一個。⁴

若以上都不符合，claude doctor（唯讀，不會啟動工作階段）會回報安裝健康狀態、設定檔錯誤以及上一次更新嘗試的結果；Anthropic 的疑難排解頁面則保有完整的錯誤與修正對照表。³⁴

常見問題

該如何把 Claude Code CLI 更新到最新版本？

執行 claude update，或乾脆重新啟動——Claude Code 預設會在啟動時與工作階段中檢查更新，於背景下載並在下次啟動時套用。以 Homebrew 與 winget 安裝的版本，則改用 brew upgrade --cask claude-code 與 winget upgrade Anthropic.ClaudeCode 更新。

Claude Code 會自動更新嗎？

會，這是預設行為：它在啟動時以及執行過程中定期檢查，然後在下次啟動時套用已下載的更新。DISABLE_AUTOUPDATER=1 會關掉背景更新但保留手動的 claude update；DISABLE_UPDATES=1 則封鎖所有更新途徑。

該如何在 Windows 上安裝 Claude Code？

在 PowerShell 中執行 irm https://claude.ai/install.ps1 | iex（或 winget install Anthropic.ClaudeCode）。原生 Windows 10（1809 以上）在 x64 與 ARM64 上都受支援，而且不需系統管理員權限；需要 Linux 工具鏈或沙箱化的指令執行時，請選擇 WSL 2，並在其中執行 Linux 的安裝指令，即可與 Linux 完全一致。

安裝 Claude Code 需要 Node.js 嗎？

不需要——建議使用的原生安裝程式沒有 Node.js 相依性。只有舊有的 npm 套件（npm install -g @anthropic-ai/claude-code，自 v2.1.15 起淘汰）才需要 Node，而且要求 Node.js 22 或更新版本。若你目前是 npm 安裝，claude install 會把你移轉到原生二進位檔。

該如何確認自己用的是哪個版本的 Claude Code？

在 shell 執行 claude --version，或在工作階段內使用 /release-notes 開啟互動式的變更紀錄選擇器。claude doctor 還會額外回報安裝類型以及偵測到的設定問題。