外觀

語言

高效 AI 駕馭術

Claude Code 怎麼安裝?2026 macOS、Windows、Linux 安裝指令與常見錯誤

Claude Code 終端機版(CLI)的完整安裝教學:先分辨你的電腦是 Mac、Windows(PowerShell、CMD、WSL)還是 Linux,再照對應的官方指令安裝、登入、更新和解除安裝,最後整理 command not found、PATH、執行原則、公司代理伺服器等常見錯誤的解法。

Kelvin Wang · · 16 分鐘閱讀

重點整理

  1. 官方建議用原生安裝程式:macOS、Linux、WSL 跑 curl,Windows PowerShell 跑 irm,不需要先裝 Node.js,也不需要管理員權限。
  2. 原生安裝會在背景自動更新;Homebrew、WinGet、apt 這類套件管理器裝的要自己升級。
  3. 裝完先開新視窗跑 claude --version;出現 command not found 幾乎都是安裝資料夾不在 PATH 裡。
  4. 一台電腦只留一份 Claude Code,npm 版和原生版同時存在會造成版本錯亂。

終端機是只能打字的視窗:輸入一行指令、按 Enter,電腦執行完把結果印出來。Claude Code 的 CLI 就是在這個視窗裡跑的 AI 程式開發工具,安裝本身只要一行指令,新手卡住的地方通常在前面:不知道自己開的是哪一種終端機、該貼哪一行。文中的指令和說明都以 Anthropic 官方文件為準,2026 年 11 月 15 日查詢1。使用 Claude Code 需要付費的 Claude 方案(Pro、Max、Ultra、Team、Enterprise)或 Claude Console 帳號,免費方案不能用1。

不想碰終端機的話,Claude Code 也有桌面版,下載安裝檔就能用,差別在另一篇有比較。

想深入 Claude Code 桌面版、CLI、VS Code:新手怎麼選? 三種用法共用同一套引擎,差在操作方式和能用的指令。

先確認你的電腦是哪種情況?

找到自己那一列,照「安裝方式」那欄去對應的段落。

你的電腦建議的安裝方式在哪裡執行
Mac(Apple Silicon 或 Intel 都一樣)原生安裝程式(curl)「終端機」App
Mac,已經在用 Homebrew原生安裝程式;或 Homebrew(要自己升級)「終端機」App
Windows 10 1809 以上、Windows 11原生安裝程式(irm)PowerShell
Windows,只開得了 CMDCMD 版原生安裝程式命令提示字元(CMD)
Windows,習慣用 WinGetWinGet(要自己升級)PowerShell
Windows,專案和工具都在 WSL 裡在 WSL 裡跑 Linux 的原生安裝程式WSL 的 Linux 終端機
Ubuntu、Debian、Fedora、RHEL、Alpine原生安裝程式;或 apt、dnf、apkLinux 終端機
公司電腦,沒有管理員權限原生安裝程式(裝在自己的使用者資料夾)同上,依作業系統
以前用 npm 裝過改用原生安裝程式,再移除 npm 版同上,依作業系統

Mac 是 Apple Silicon 還是 Intel?

點左上角蘋果選單 →「關於這台 Mac」。看到「晶片」(Chip)是 Apple Silicon,看到「處理器」(Processor)是 Intel7。Claude Code 兩種都支援,安裝指令也一樣,安裝程式會自己挑對的版本1。要注意的是 macOS 版本:Claude Code 需要 macOS 13.0 以上。

Homebrew 是 Mac 上常用的套件管理器,用一行指令就能裝、升級、移除軟體。不確定有沒有裝,在終端機輸入 brew --version,印出版本號就是有。沒有也不必為了 Claude Code 特地裝:Homebrew 目前正式支援的是 macOS 15 以上和 Apple Silicon,Intel Mac 屬於支援度最低的一級8,舊一點的 Mac 直接用原生安裝程式比較單純。

Windows 開的是 PowerShell 還是 CMD?

Windows 有兩種命令列,指令不能混用。看每一行開頭的提示字元:

  • PowerShell:顯示 PS C:\Users\你的名字>,開頭有 PS。按 Win + X 選「Windows PowerShell」或「終端機」就會打開它。
  • CMD(命令提示字元):顯示 C:\Users\你的名字>,沒有 PS。

開始功能表裡有一個「Windows PowerShell (x86)」,那是 32 位元版,用它安裝會出現「不支援 32 位元 Windows」的錯誤,要選沒有 x86 的那個3。

Git for Windows 是 Windows 版的 Git,裡面附了 Git Bash。官方建議原生 Windows 安裝它,Claude Code 有它才能用 Bash 工具執行指令;沒裝也能用,Claude Code 會改用 PowerShell1。檢查方法是在 PowerShell 輸入 git --version。安裝步驟在準備篇有寫。

想深入 AI 寫程式前的準備:終端機、Git、GitHub、Node.js 一次裝好(2026) 終端機怎麼開、Git for Windows 怎麼裝,每一步的驗證方法。

WSL 要不要用?

WSL(Windows Subsystem for Linux)是 Windows 內建、可以直接跑 Linux 的環境。官方給的選擇方式1:

  • 專案和工具都是 Windows 的:裝在原生 Windows(PowerShell 或 CMD)就好,不需要 WSL。
  • 要用 Linux 工具鏈,或要用沙盒(sandboxing)限制 Claude 執行的指令:用 WSL 2。原生 Windows 和 WSL 1 都不支援沙盒。
  • 只能用 WSL 1:可以裝,但有已知問題,見文末錯誤段落。

已經裝過 WSL 的人,在 PowerShell 跑 wsl -l -v,VERSION 欄會顯示每個 Linux 發行版是 1 還是 210。還沒裝的話,wsl --install 要用「以系統管理員身分執行」的 PowerShell 才能跑,裝完要重開機10。沒有管理員權限的公司電腦,直接用原生 Windows 版。

公司電腦沒有管理員權限怎麼辦?

原生安裝程式把檔案放在你自己的使用者資料夾:macOS、Linux 是 ~/.local/bin 和 ~/.local/share/claude,Windows 是 %USERPROFILE%\.local\bin。官方明寫 Windows 版不需要用系統管理員身分執行13。需要管理員權限的是另外幾種:裝 WSL、用 sudo apt 或 sudo dnf 從 Linux 套件庫安裝。

公司網路常見的兩個障礙是代理伺服器和會檢查加密連線的防火牆,解法在常見錯誤段落。如果公司的資安軟體擋掉 claude.exe 執行的指令,官方的建議是請 IT 把 claude.exe 和它啟動的 cmd.exe、bash.exe 加進允許清單3。

系統需求有哪些?

項目官方需求
作業系統macOS 13.0 以上;Windows 10 1809 以上或 Windows Server 2019 以上;Ubuntu 20.04 以上;Debian 10 以上;Alpine Linux 3.19 以上
記憶體4 GB 以上
處理器x64 或 ARM64(不支援 32 位元 Windows)
網路必須連網
ShellBash、Zsh、PowerShell 或 CMD
地區Anthropic 支援的國家和地區
Node.js原生安裝程式不需要;只有 npm 安裝需要 Node.js 22 以上
Git選用;Windows 建議裝 Git for Windows,WSL 不需要
硬碟空間官方文件沒有說明

資料來源:Claude Code 官方 Advanced setup 頁,2026-11-15 查詢。

macOS、Linux、WSL 怎麼安裝?

打開終端機(Mac 按 Cmd + Space 搜尋「終端機」或 Terminal;Linux 多數發行版按 Ctrl + Alt + T;WSL 從開始功能表打開 Ubuntu 這類發行版),貼上這一行,按 Enter:

# 在 macOS 終端機、Linux 終端機或 WSL 裡執行
curl -fsSL https://claude.ai/install.sh | bash

這行會從 claude.ai 下載安裝程式並執行。下載時畫面不會顯示進度,視窗開著等它跑完,看到「Claude Code successfully installed!」就是好了4。WSL 要在 WSL 的終端機裡安裝和啟動,不是在 PowerShell 裡1。

Alpine 這類 musl 系統預設沒有 bash 和 curl,上面的指令會報 not found,先裝這兩個1:

# Alpine Linux
apk add bash curl

Homebrew(macOS)

# 在 macOS 終端機執行
brew install --cask claude-code

Homebrew 有兩個版本可選:claude-code 跟穩定(stable)頻道,通常比最新版晚一週左右,會跳過有重大問題的版本;claude-code@latest 跟最新(latest)頻道,新版一出就收到。Homebrew 版不會自動更新1。

apt(Ubuntu、Debian)

官方提供有簽章的 apt 套件庫。先確認有 curl 和 gpg,沒有就先裝:

# 在 Ubuntu 或 Debian 的終端機執行
sudo apt install curl gnupg

下載簽章金鑰:

sudo install -d -m 0755 /etc/apt/keyrings
sudo curl -fsSL https://downloads.claude.ai/keys/claude-code.asc \
  -o /etc/apt/keyrings/claude-code.asc

檢查金鑰是 Anthropic 的:

gpg --show-keys /etc/apt/keyrings/claude-code.asc

印出的指紋只能是 31DDDE24DDFAB679F42D7BD2BAA929FF1A7ECACE。確認後登記 stable 頻道的套件庫並安裝:

echo "deb [signed-by=/etc/apt/keyrings/claude-code.asc] https://downloads.claude.ai/claude-code/apt/stable stable main" \
  | sudo tee /etc/apt/sources.list.d/claude-code.list
sudo apt update
sudo apt install claude-code

Fedora、RHEL 用 dnf,Alpine 用 apk,指令在官方 Advanced setup 頁1。套件管理器裝的版本不會由 Claude Code 自己更新,跟著系統的一般升級流程走。

Windows 怎麼安裝?

PowerShell

# 在 PowerShell 執行(開頭有 PS)
irm https://claude.ai/install.ps1 | iex

irm 負責下載,iex 負責執行,兩段要一起貼。只貼 irm 那半段,畫面會印出一整段腳本文字,什麼都沒裝3。

CMD

:: 在命令提示字元 CMD 執行(開頭沒有 PS)
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

WinGet

# 在 PowerShell 執行
winget install Anthropic.ClaudeCode

WinGet 是 Windows 的套件管理器,Windows 11 和較新的 Windows 10 透過「應用程式安裝程式」(App Installer)內建9。WinGet 版不會自動更新1。

PowerShell 和 CMD 只差在跑哪一行指令,裝好的東西一樣1。裝完可以在任何終端機輸入 claude 啟動。

裝了 Git for Windows、Claude Code 卻說找不到 Git Bash 時,在設定檔 settings.json 裡指定 bash.exe 的位置1:

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

使用者層級的設定檔在 %USERPROFILE%\.claude\settings.json。Git 不在預設位置的話,在 PowerShell 跑 where.exe git 找出安裝資料夾,改成那個資料夾裡的 bin\bash.exe3。

npm 安裝還能用嗎?

能用,但官方把它放在「進階安裝選項」,首頁推薦的是原生安裝程式1。npm 是 Node.js 附帶的套件管理器;npm 版需要 Node.js 22 以上,裝進來的是同一個原生執行檔,執行時不會用到你的 Node.js1。

# macOS、Linux、WSL 的終端機,或 Windows PowerShell
npm install -g @anthropic-ai/claude-code@latest
  • 不要加 sudo。官方明寫不要用 sudo npm install -g:會有權限問題和安全風險,而且 Claude Code 自動更新時不會用 sudo,需要 sudo 才裝得上的版本之後也更新不了1。
  • npm 12 要多一步。npm --version 印出 12 開頭時,npm 預設會跳過 Claude Code 的安裝後步驟,claude 會報 claude native binary not installed。官方建議直接改用原生安裝程式;要留在 npm,照官方的 npm 12 修法設定 allow-scripts3。
  • 升級用 npm install -g @anthropic-ai/claude-code@latest。官方提醒不要用 npm update -g,它可能不會升到最新版1。

裝好之後怎麼確認?

  1. 關掉安裝用的視窗,開一個新的終端機視窗。舊視窗還留著安裝前的 PATH,可能找不到 claude3。
  2. 輸入下面這行,印出像 2.1.211 (Claude Code) 這樣的版本號就是裝好了1:
# 任何終端機都可以
claude --version
  1. 想做更完整的檢查,跑 claude doctor。它不會開始對話,只會印出安裝狀態、設定檔的錯誤、最近一次自動更新的結果,以及有問題時建議的修法1。
claude doctor

第一次啟動怎麼登入?

先用 cd 進到你的專案資料夾,再啟動:

# macOS、Linux、WSL 的終端機,或 Windows PowerShell
cd /path/to/your/project
claude

把 /path/to/your/project 換成你的專案路徑。第一次啟動會打開瀏覽器要你登入,完成後終端機顯示 Login successful,按 Enter 繼續5。登入資訊會存起來,之後不用每次登入2。

  • 瀏覽器沒有自動打開:在登入畫面按 c 複製登入網址,自己貼到瀏覽器5。
  • 瀏覽器登入後顯示一串代碼:把代碼貼回終端機的 Paste code here 提示5。
  • 想在開始對話前先登入:在終端機跑 claude auth login5。

可以登入的帳號有兩大類5:

  • Claude 訂閱(Pro、Max、Ultra、Team、Enterprise):用 claude.ai 帳號登入,費用包含在月費裡,有用量上限。官方把這種列為建議選項2。
  • Claude Console(API):用預先儲值的額度按用量計費。第一次登入時,Console 會自動建立一個叫「Claude Code」的工作區,方便集中看花費2。

如果電腦上設了 ANTHROPIC_API_KEY 這個環境變數,Claude Code 會問你要不要用它;同意的話就跳過登入,改按 API 計費5。只想用訂閱的話,不要設這個變數。兩種計費方式怎麼選、實際一個月花多少,另一篇有算。

想深入 Claude Code 費用怎麼算:訂閱方案和 API 計費,我實際一個月花多少 訂閱額度和 API 用量計費的差別。

進到對話後,輸入 /help 看可用的指令,/login 換帳號,/logout 登出,Esc 中斷 Claude 正在做的事,空白提示列連按兩次 Ctrl + D 離開24。第一次對話之後要做什麼(寫 CLAUDE.md、plan mode、skills),在完整教學那篇。

想深入 Claude Code 教學 2026:安裝、CLAUDE.md、skills,用它做出一個個人網站 裝好之後的下一步:CLAUDE.md、plan mode、skills、hooks、MCP。

怎麼更新、切換更新頻道?

安裝方式會不會自動更新手動更新指令
原生安裝程式會,在背景下載,下次啟動生效claude update
Homebrew不會brew upgrade claude-code 或 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不會apk update && apk upgrade claude-code
npm會(npm 全域資料夾要可寫入)npm install -g @anthropic-ai/claude-code@latest

資料來源:Claude Code 官方 Advanced setup 頁,2026-11-15 查詢。

Homebrew 和 WinGet 可以讓 Claude Code 代你跑升級指令:把環境變數 CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE 設成 1。WinGet 在 Claude Code 執行中可能升級失敗,因為 Windows 會鎖住正在執行的檔案,這時它會改成顯示手動指令1。Homebrew 升級後會留著舊版本,偶爾跑一次 brew cleanup 清掉。

更新頻道是什麼?

原生安裝有兩個頻道1:

  • latest(預設):新功能一發布就收到。
  • stable:通常是一週前左右的版本,跳過有重大問題的版本。

切換方式是在 Claude Code 裡輸入 /config,改「Auto-update channel」;或在 ~/.claude/settings.json 加上:

{
  "autoUpdatesChannel": "stable"
}

從 latest 切到 stable,原生安裝會降回 stable 的版本。不想降版的話,在 /config 切到 stable 時選「Stay on current version」,它會把目前版本設成最低版本(minimumVersion)1。新推出的模型有時需要比 stable 更新的版本,要馬上用就切回 latest。Homebrew 用哪個 cask 決定頻道,apt、dnf、apk 用哪個套件庫決定頻道,都不看這個設定。

安裝時也可以直接指定頻道或版本號:

# macOS、Linux、WSL:安裝 stable 頻道
curl -fsSL https://claude.ai/install.sh | bash -s stable
# Windows PowerShell:安裝 stable 頻道
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) stable
:: Windows CMD:安裝 stable 頻道
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd stable && del install.cmd

把 stable 換成版本號(例如 2.1.89)就會裝那個版本1。

要關掉背景自動更新,在 settings.json 的 env 裡加 "DISABLE_AUTOUPDATER": "1";這只停掉背景檢查,claude update 還是能用1。

怎麼解除安裝?

照你當初的安裝方式移除。移除後 claude 還能執行,代表電腦上還有第二份,見常見錯誤的「同時裝了兩份」1。

原生安裝

# macOS、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

# macOS 終端機;裝的是 latest 版就用第二行
brew uninstall --cask claude-code
brew uninstall --cask claude-code@latest

WinGet

# Windows PowerShell
winget uninstall Anthropic.ClaudeCode

apt/dnf

# Ubuntu、Debian
sudo apt remove claude-code
sudo rm /etc/apt/sources.list.d/claude-code.list /etc/apt/keyrings/claude-code.asc
# Fedora、RHEL
sudo dnf remove claude-code
sudo rm /etc/yum.repos.d/claude-code.repo

npm

# 任何終端機
npm uninstall -g @anthropic-ai/claude-code

設定檔要不要一起刪?

上面的指令只移除程式。設定、允許過的工具、MCP 設定和對話紀錄放在另外的地方1:

  • 使用者層級:~/.claude/ 資料夾和 ~/.claude.json 檔案(Windows 是 %USERPROFILE%\.claude 和 %USERPROFILE%\.claude.json)。
  • 專案層級:專案資料夾裡的 .claude/ 和 .mcp.json。

刪掉之後所有設定和對話紀錄都會消失,無法復原。VS Code 擴充、JetBrains 外掛和桌面版也會寫入 ~/.claude/,還裝著的話下次執行會再建一次,要全部清乾淨得先移除它們1。

# macOS、Linux、WSL:刪除使用者設定
rm -rf ~/.claude
rm ~/.claude.json
# Windows PowerShell:刪除使用者設定
Remove-Item -Path "$env:USERPROFILE\.claude" -Recurse -Force
Remove-Item -Path "$env:USERPROFILE\.claude.json" -Force

常見錯誤怎麼解決?

官方疑難排解頁有一張「錯誤訊息 → 解法」對照表3,新手最常遇到的是下面這幾種。

command not found: claude、無法辨識 claude

PATH 是終端機找程式的資料夾清單,你輸入 claude,終端機只會去 PATH 列的資料夾裡找。安裝程式把 claude 放在 ~/.local/bin(Windows 是 %USERPROFILE%\.local\bin),這個資料夾不在 PATH 裡,就會出現這個錯誤。安裝程式會在結尾的 Setup notes 印出修法,但不會自己改 PATH3。

  1. 先開一個新視窗再試一次。舊視窗和編輯器內建的終端機會留著舊的 PATH;在 VS Code 這類編輯器裡,要整個關掉編輯器再打開3。
  2. 還是不行,照你的 shell 把資料夾加進 PATH:
# macOS(預設的 zsh)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
# Linux(多數發行版預設的 bash)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
# Windows PowerShell,跑完要重開 PowerShell
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

macOS 如果改用 bash,要寫進 ~/.bash_profile,不是 ~/.bashrc3。echo 那行出現 permission denied,代表設定檔不是你能寫的,照官方的步驟改擁有者或權限3。Windows 若是剛自動更新完才找不到 claude,是更新時替換檔案失敗,官方有從備份 claude.exe.old.* 還原的指令3。

Windows 貼錯指令

錯誤訊息直接告訴你開錯了哪種終端機3:

  • 'irm' is not recognized:你在 CMD。改開 PowerShell 跑 irm 那行,或留在 CMD 改跑 install.cmd 那行。
  • The token '&&' is not a valid statement separator:你在 PowerShell,卻貼了 CMD 的指令。改跑 irm 那行。
  • A parameter cannot be found that matches parameter name 'fsSL' 或 'bash' is not recognized:你在 Windows 貼了 macOS/Linux 的 curl … | bash。改跑 irm 那行。

running scripts is disabled on this system

這是 PowerShell 的執行原則(execution policy)擋住了 npm 產生的 .ps1 啟動腳本,只會出現在用 npm 安裝或執行時;irm … | iex 的原生安裝不受影響3。三種解法擇一:

  • 允許自己這個使用者執行本機腳本:在 PowerShell 跑 Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser,再重試。
  • 改打 npm.cmd、claude.cmd:執行原則只管 .ps1,不管 .cmd。
  • 改用 PowerShell 的原生安裝程式:它裝的是執行檔,不是 .ps1 腳本。

Claude Code on Windows requires either Git for Windows (for bash) or PowerShell

意思是 Git Bash 和 PowerShell 都找不到,至少要有一個3:

  • PowerShell 不在 PATH:預設位置是 C:\Windows\System32\WindowsPowerShell\v1.0\,把它加回 PATH,或安裝 PowerShell 7。
  • 想用 Git Bash:安裝 Git for Windows,安裝時選「Add to PATH」,裝完重開終端機。
  • Git 已經裝了但找不到:照前面 Windows 段落,在 settings.json 設定 CLAUDE_CODE_GIT_BASH_PATH。路徑的檔名必須是 bash.exe、sh.exe、bash 或 sh,指到 git-bash.exe 會被忽略。

npm 權限錯誤(EACCES)

用 npm 裝出現 EACCES: permission denied,官方的建議是不要加 sudo 重跑,直接改用原生安裝程式,再移除 npm 版13。原生安裝本身遇到權限錯誤時,錯誤會寫出它寫不進去的資料夾;macOS、Linux 可以把 ~/.local 的擁有者改回自己3:

# macOS、Linux 終端機;需要輸入你的登入密碼
sudo mkdir -p ~/.local/bin
sudo chown -R $(whoami) ~/.local

公司網路:代理伺服器、憑證錯誤

先測試連不連得到下載伺服器,第一行出現 200 就是通的3:

# macOS、Linux、WSL
curl -sI https://downloads.claude.ai/claude-code-releases/latest
# Windows PowerShell(要打 curl.exe,PowerShell 的 curl 是別的指令)
curl.exe -sI https://downloads.claude.ai/claude-code-releases/latest

公司要走代理伺服器(proxy,所有對外連線都經過它)時,安裝前先設定代理的位置,網址向 IT 要,或看瀏覽器的代理設定3:

# macOS、Linux、WSL;把網址換成公司的代理伺服器
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
curl -fsSL https://claude.ai/install.sh | bash
# Windows PowerShell;把網址換成公司的代理伺服器
$env:HTTP_PROXY = 'http://proxy.example.com:8080'
$env:HTTPS_PROXY = 'http://proxy.example.com:8080'
irm https://claude.ai/install.ps1 | iex

出現 unable to get local issuer certificate、SELF_SIGNED_CERT_IN_CHAIN 這類憑證錯誤,通常是公司的代理會拆開檢查加密連線。macOS、Linux 要向 IT 拿公司根憑證的 PEM 檔,把 CURL_CA_BUNDLE 和 NODE_EXTRA_CA_CERTS 都指向它再安裝;Windows 的 PowerShell 安裝程式看的是 Windows 憑證存放區,請 IT 把憑證加進去3。舊版 Windows 10 出現 Could not create SSL/TLS secure channel,先在同一個 PowerShell 視窗啟用 TLS 1.2 再安裝4:

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

代理伺服器和憑證的完整設定(包括安裝後 Claude Code 本身的連線)在官方的網路設定頁6。

安裝指令印出一堆 HTML,或出現 403

syntax error near unexpected token '<'、CMD 的 < was unexpected at this time、PowerShell 的 System.Xml.XmlDocument,都代表下載到的是網頁,不是安裝腳本。錯誤裡如果有「App unavailable in region」,是你所在的地區不能用 Claude Code。其他情況多半是暫時的網路問題,等幾分鐘再試;一直失敗就改用 Homebrew(Mac)或 WinGet(Windows)安裝3。沒有內容的 403 也可能是公司代理或防火牆擋掉,先做上一段的連線測試。

WSL 裡的問題

  • cannot execute binary file: Exec format error:你在 WSL 1,碰到已知的相容性問題。最乾淨的修法是在 PowerShell 把發行版轉成 WSL 2:wsl --set-version <DistroName> 23。
  • npm 版跑出 exec: node: not found:WSL 用到了 Windows 的 Node.js。跑 which node,路徑是 /mnt/c/ 開頭就是 Windows 的版本,要在 WSL 裡另外用發行版的套件管理器或 nvm 裝 Node.js3。改用原生安裝程式就不會碰到這個問題。
  • 登入時瀏覽器沒開,或開了之後顯示 localhost 連線錯誤:按 c 複製登入網址,在 Windows 的瀏覽器打開登入,再把頁面顯示的代碼貼回終端機3。

同時裝了兩份(npm 版和原生版)

裝了不只一份,會出現版本對不上、更新了卻還是舊版這類怪現象。官方建議只留一份,留原生安裝的那份3。先看有幾個 claude:

# macOS、Linux、WSL:列出 PATH 裡所有的 claude
which -a claude
ls -la ~/.local/bin/claude
npm -g ls @anthropic-ai/claude-code 2>/dev/null
# Windows PowerShell
where.exe claude

再把多的移除:npm 版跑 npm uninstall -g @anthropic-ai/claude-code;舊版 Claude Code 留下的本機 npm 安裝在 ~/.claude/local,用 rm -rf ~/.claude/local 刪掉;Homebrew、WinGet 版照解除安裝段落移除3。Windows 上若輸入 claude 打開的是桌面版,是舊版 Claude Desktop 搶走了 claude 這個名字,把桌面版更新到最新版就好3。

登入失敗

原因不明時,官方建議的重設步驟是3:

  1. 在 Claude Code 裡輸入 /logout。
  2. 關掉 Claude Code。
  3. 重新執行 claude,再登入一次。

常常被要求重新登入的話,檢查電腦的時間對不對,登入憑證的驗證依賴正確的時間3。

資料來源

  1. 1. Advanced setup · Claude Code Docs · 2026-11-15 查詢
  2. 2. Quickstart · Claude Code Docs · 2026-11-15 查詢
  3. 3. Troubleshoot installation and login · Claude Code Docs · 2026-11-15 查詢
  4. 4. Terminal guide for new users · Claude Code Docs · 2026-11-15 查詢
  5. 5. Authentication · Claude Code Docs · 2026-11-15 查詢
  6. 6. Enterprise network configuration · Claude Code Docs · 2026-11-15 查詢
  7. 7. Mac computers with Apple silicon · Apple Support · 2026-11-15 查詢
  8. 8. Installation · Homebrew Documentation · 2026-11-15 查詢
  9. 9. Use WinGet to install and manage applications · Microsoft Learn · 2026-11-15 查詢
  10. 10. Install WSL · Microsoft Learn · 2026-11-15 查詢

關於作者

Kelvin Wang

電機工程師,和 AI Agent 做工具,分享工程與投資的實作筆記。

更多關於我