claude command not found 怎麼辦?Claude Code 安裝錯誤排解
裝好 Claude Code 卻出現 command not found?依錯誤訊息逐一排查 PATH 設定、VS Code 終端機、VPS 安裝被 Killed、WSL1 的 Exec format error,以及安裝指令回傳網頁時的地區限制。
一句話答案
裝好 Claude Code 之後出現 zsh: command not found: claude 或 bash: claude: command not found,最常見的原因是原生安裝程式已經把 claude 放進 ~/.local/bin,但這個資料夾不在你的 PATH 裡。把 export PATH="$HOME/.local/bin:$PATH" 寫進 shell 設定檔,再開一個新的終端機視窗,大部分情況就能解決。安裝時的 Killed、WSL 的 Exec format error、安裝指令的 syntax error near unexpected token '<' 則各有不同原因。下面每一節對應一種錯誤訊息,各給一個檢查指令和一個修法。
本文的事實依據是 Anthropic 官方的 安裝疑難排解文件 與 安裝說明頁,兩頁都在 2026 年 11 月 13 日查閱。如果你還不確定這個工具是做什麼的,可以先看 Claude Code 是什麼、能替你做哪些事。
先對照:你看到的是哪一行錯誤?
把終端機裡的錯誤訊息和下面這份清單比對,再跳到對應的段落。
zsh: command not found: claude(macOS)或bash: claude: command not found(Linux):看 PATH 那一節。'claude' is not recognized as an internal or external command(Windows CMD)或claude : The term 'claude' is not recognized as the name of a cmdlet(PowerShell):看 Windows 那一節。zsh: permission denied: /Users/you/.zshrc:shell 設定檔寫不進去,和claude本身無關。Killed:Linux 上安裝到一半被系統終止,常見於記憶體小的 VPS。cannot execute binary file: Exec format error(WSL):你用的是 WSL1。exec: node: not found(WSL):npm 安裝用到了 Windows 版的 Node.js。syntax error near unexpected token '<':下載回來的是網頁,不是安裝腳本。bad CPU type in executable、zsh: permission denied: claude、zsh: killed claude:官方文件沒有收錄,最後一節教你自己收集線索。
先確認你的機器符合官方系統需求。安裝說明頁列出的是:macOS 13.0 以上、Windows 10 1809 以上或 Windows Server 2019 以上、Ubuntu 20.04 以上、Debian 10 以上、Alpine Linux 3.19 以上;記憶體 4 GB 以上;處理器為 x64 或 ARM64;shell 為 Bash、Zsh、PowerShell 或 CMD。macOS、Linux 與 WSL 的原生安裝指令是:
curl -fsSL https://claude.ai/install.sh | bashWindows PowerShell 則是:
irm https://claude.ai/install.ps1 | iex下載期間安裝指令不會顯示進度,畫面停住不代表當機。安裝結束後,開一個新的終端機視窗執行 claude --version。安裝正常時,它會印出一個版本號碼。
為什麼裝完還是 claude: command not found?
PATH 是一串資料夾清單。你輸入 claude 時,shell 只會在這些資料夾裡找同名的程式,找不到就回報 command not found。原生安裝程式在 macOS 與 Linux 上把啟動程式放在 ~/.local/bin/claude,在 Windows 上放在 %USERPROFILE%\.local\bin\claude.exe。如果這個資料夾不在 PATH 裡,安裝程式會在輸出的 Setup notes: 底下寫出這一行:
Native installation exists but ~/.local/bin is not in your PATH.安裝程式會在這一行旁邊印出修正方法,但它不會自己修改 PATH。所以程式確實裝好了,shell 卻還是找不到它。
第一步:程式到底在不在?
ls -la ~/.local/bin/claude如果出現 No such file or directory,代表這台機器沒有原生安裝,請重新執行安裝指令。如果列出一個檔案,原生安裝的結果是一個符號連結(symlink),指向 ~/.local/share/claude/versions/ 裡的某個版本。程式在,問題就出在 PATH。
第二步:~/.local/bin 在不在 PATH 裡?
echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"這行指令把 PATH 拆成一行一個資料夾,再找出完全相同的那一行。印出 /Users/你的帳號/.local/bin 或 /home/你的帳號/.local/bin,代表資料夾已經在 PATH 裡。沒有任何輸出,代表不在,請做第三步。
第三步:把它寫進 shell 設定檔
錯誤訊息開頭是 zsh: 的話,你用的是 zsh,設定檔是 ~/.zshrc:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrcLinux 上的 Bash 用 ~/.bashrc,只要把上面兩行裡的 ~/.zshrc 換掉即可。macOS 上的 Bash 不同:macOS 的「終端機」會以登入 shell(login shell)啟動 Bash,而登入 shell 不讀 ~/.bashrc,只讀 ~/.bash_profile、~/.bash_login、~/.profile 中第一個存在的檔案。所以請寫進 ~/.bash_profile。如果你已經有 ~/.bash_login 或 ~/.profile,卻沒有 ~/.bash_profile,就寫進已經存在的那個檔案,不要另外建立 ~/.bash_profile。fish 或 Nushell 的使用者請改用該 shell 自己的語法設定 PATH。
最後執行 claude --version。印出版本號碼,就代表修好了。
已經加了 PATH,為什麼舊分頁和編輯器裡還是找不到?
最常見的原因是終端機比你的修改更早開啟。已經開著的視窗會保留舊的 PATH,而編輯器裡的內建終端機是從編輯器本身取得 PATH。請開一個新的終端機視窗。如果是編輯器裡的終端機,要把編輯器整個關掉再重開,只開新分頁不夠。
另外兩個原因也值得檢查:
- 那一行沒有存進去。執行
grep -n '.local/bin' ~/.zshrc(換成你的設定檔名稱),沒有輸出就代表檔案裡沒有這一行。 - 那一行寫進了別的 shell 的設定檔。執行
echo $0看看目前用的是哪個 shell。例如你用 zsh,卻把設定寫進~/.bashrc,zsh 不會讀它。
只裝了 VS Code 擴充功能,終端機裡為什麼沒有 claude?
因為擴充功能本來就不會把 claude 放進 PATH。官方的 VS Code 文件 說明,擴充功能內含一份私有的 CLI,只給它自己的聊天面板使用。所以只裝擴充功能時,~/.local/bin/claude 根本不存在,第一步的 ls -la 會回報 No such file or directory。
想在終端機裡輸入 claude,包括 VS Code 的內建終端機,都需要另外做一次獨立安裝,也就是執行前面的原生安裝指令。裝完之後照 PATH 那一節檢查,並記得重開 VS Code,讓內建終端機拿到新的 PATH。
Ubuntu 與 VPS 上的 bash: claude: command not found
官方文件沒有替 Ubuntu 另寫一節,Ubuntu 歸在 Linux 底下。大多數 Linux 發行版預設使用 Bash,所以設定檔是 ~/.bashrc:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
claude --version在 VPS 上透過 SSH 操作時,同樣的規則也適用:已經開著的 shell 保留舊的 PATH。如果你在 tmux 裡工作,每個已經開著的 tmux 視窗都是一個舊 shell,要在裡面各自執行 source ~/.bashrc,或者開新視窗。想把 Claude Code 長期掛在伺服器上,可以參考 在 VPS 上用 tmux 執行 Claude Code。桌面版 Linux 和純命令列的差別,則整理在 Linux 桌面與命令列上使用 Claude。
也請記得記憶體需求。官方的系統需求是 4 GB 以上記憶體,記憶體小的 VPS 連安裝都可能失敗,請看後面 Killed 那一節。
Windows 上的 'claude' is not recognized
CMD 的 'claude' is not recognized as an internal or external command,和 PowerShell 的 claude : The term 'claude' is not recognized as the name of a cmdlet,官方文件分成兩種情況處理。如果這個錯誤是在 Claude Code 剛更新之後才開始出現,文件指向另一節:從備份還原 claude.exe。Windows 上的更新會先把現有的 claude.exe 改名成備份,再把新版本移到原位;如果移動失敗,又無法把備份改回原名,%USERPROFILE%\.local\bin 裡就只剩備份,沒有 claude.exe。其他情況,文件的修法是檢查 PATH。Windows 的啟動程式位置是 %USERPROFILE%\.local\bin\claude.exe。PATH 缺少這個資料夾時,安裝程式會在 Setup notes: 底下印出:
Native installation exists but C:\Users\you\.local\bin is not in your PATH.修正方法就印在這一行旁邊。照著做完之後,關掉所有 PowerShell 或 CMD 視窗,再開一個新的,執行 claude --version 確認。
同一台機器裝了好幾份 claude,怎麼辦?
claude 可能來自三個地方。裝了不只一份時,你執行到的未必是你以為的那一份。先看 PATH 上找得到哪些:
which -a claudewhich -a 只會列出 PATH 上找得到的檔案。要知道三種來源各自有沒有安裝,請分別檢查:
ls -la ~/.local/bin/claude
ls -la ~/.claude/local/
npm -g ls @anthropic-ai/claude-code 2>/dev/null第一行是原生安裝。第二行是舊版 Claude Code 建立的本機 npm 安裝(legacy local install)。第三行是用 npm install -g 裝的全域套件。如果找到不只一份,只保留一份,官方建議保留原生安裝。移除其他版本的指令如下,只執行你確實要移除的那一行:
npm uninstall -g @anthropic-ai/claude-code
rm -rf ~/.claude/local
brew uninstall --cask claude-codezsh: permission denied: ~/.zshrc 是設定檔的問題,不是 claude 的問題
在執行 PATH 修正的 echo 時,如果看到 zsh: permission denied: /Users/you/.zshrc 或 bash: /home/you/.bashrc: Permission denied,意思是你的帳號沒有權限寫入這個設定檔,所以那一行根本沒有存進去。claude 本身完全沒有被碰到。
先查這個檔案的擁有者(owner):
ls -l ~/.zshrc輸出的第三欄就是擁有者。如果是 root 之類的其他帳號,把擁有權改回你自己:
sudo chown $(whoami) ~/.zshrc如果擁有者就是你,代表檔案缺少寫入權限,補上即可:
chmod u+w ~/.zshrc接著重新執行 PATH 那一節的兩行指令。使用 Bash 的話,把 ~/.zshrc 換成你的設定檔名稱。
另一個容易混在一起的情況,是安裝目錄本身寫不進去。官方文件用這行檢查:
test -w ~/.local/bin && echo "writable" || echo "not writable"印出 not writable 時,文件的修法是先執行 sudo mkdir -p ~/.local/bin,再用 sudo chown -R $(whoami) ~/.local 把整個 ~/.local 的擁有權交回給你。
小型 VPS 安裝時出現 Killed,是記憶體不夠嗎?
通常是。官方文件說,Linux 安裝過程中出現 Killed,通常代表系統的記憶體不足終止程式(OOM killer,out-of-memory killer)把 claude install 這一步結束掉了,因為可用記憶體用完了。這在小型 VPS 和雲端主機上很常見。文件的用詞是「通常」,所以請把它當成最可能的原因,而不是唯一的原因。
新版安裝腳本會說明原因,並以結束碼(exit code)137 離開,訊息開頭是:
Installation was killed before it could finish只有在 Linux 上、結束碼是 137 時,腳本才會附上記憶體不足的解釋。在 macOS 上,或者程式是被其他訊號終止的,腳本只印出這行訊息加上實際的結束碼,不提記憶體。WSL 裡的安裝也走同一支腳本。Windows 原生的安裝腳本則不會印出這段訊息。比較舊的版本只會留下 shell 自己印的一個 Killed。
依官方文件,安裝大約需要 512 MB 的可用記憶體,執行 Claude Code 需要更多,系統需求是至少 4 GB 記憶體。能換大一點的主機最好,其次是關掉其他佔記憶體的程式。如果兩者都做不到,文件的做法是加一個 2 GB 的 swap 檔(把磁碟空間當作備用記憶體):
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile然後重新執行安裝指令。注意,文件的這四行只負責現在啟用 swap,沒有包含開機自動啟用的設定。這個 swap 檔要長期留著的話,需要另外設定。
WSL 裡的 cannot execute binary file: Exec format error
在 WSL 裡執行 claude 出現 cannot execute binary file: Exec format error,官方文件的判斷很直接:你用的是 WSL1,碰到的是原生執行檔的已知問題,追蹤在 GitHub issue #38788。
最乾淨的修法,是在 Windows 的 PowerShell 裡把這個發行版轉成 WSL2:
wsl --set-version <DistroName> 2<DistroName> 換成你的發行版名稱。轉換完成後,回到 WSL 執行 claude --version。官方安裝說明頁也提到,WSL 2 支援沙箱(sandboxing),WSL 1 不支援。如果你因為其他原因必須留在 WSL1,文件另外提供一個只適用於 WSL1 的替代做法(在 ~/.bashrc 裡加一個 Bash 函式),請直接照官方文件的原文設定。
WSL 裡的 exec: node: not found(只有 npm 安裝會遇到)
這個錯誤寫在官方文件的「WSL 中的 npm 安裝錯誤」一節,而那一節的第一句就是:使用原生安裝程式的人可以跳過。所以它只和 npm install -g 的安裝方式有關。
文件的說法是,你的 WSL 環境「很可能」用到了 Windows 上安裝的 Node.js。用這兩行確認:
which npm
which node路徑以 /mnt/c/ 開頭的是 Windows 的程式。Linux 自己的程式路徑以 /usr/ 開頭。修法是在 WSL 裡用發行版的套件管理工具,或用 nvm,安裝 Linux 版的 Node.js。npm 套件需要 Node.js 22 以上。文件也特別提醒,不要為了這個去設定 appendWindowsPath = false。
安裝指令出現 syntax error near unexpected token '<'
執行 curl -fsSL https://claude.ai/install.sh | bash 時,如果看到這樣的輸出:
bash: line 1: syntax error near unexpected token `<'
bash: line 1: `<!DOCTYPE html>'意思是下載回來的內容是一個網頁(HTML),而不是安裝腳本。Bash 試著把網頁當成指令執行,讀到第一個 < 就出錯了。另一種相關的形式是 curl: (22) 加上 403 的錯誤,也就是伺服器拒絕了這次下載。
如果錯誤輸出裡出現 App unavailable in region 這段文字,原因就是地區限制:Claude Code 在你所在的國家或地區沒有提供服務。這不是腳本壞了,也不是你的 shell 有問題,換 shell 或重新下載都不會改變結果。Anthropic 的 支援地區頁面 寫明,包括 Claude.ai 與 Claude Code 在內的產品,只在頁面列出的國家和地區提供。依 2026 年 11 月 13 日查閱的版本,清單裡有台灣,沒有香港,也沒有澳門。各地區的完整情況,整理在 Claude 在哪些國家和地區可以使用。
如果輸出裡沒有這段文字,原因就未必是地區。官方文件說,沒有內容的 403 常常也是地區限制,但也可能來自公司的代理伺服器(proxy)或防火牆。其他可能還有網路問題、地區路由,或暫時性的服務中斷。用這行檢查下載伺服器連不連得上:
curl -sI https://downloads.claude.ai/claude-code-releases/latest回應開頭是 HTTP/2 200,代表連得上,可以等幾分鐘後再試一次安裝。回應是 403 時,文件的解釋是通常為代理伺服器或網路過濾擋住了這個主機,或者 Claude Code 在你的地區不提供。
文件也列出 macOS 的 Homebrew 和 Windows 的 WinGet 作為替代安裝方式。但它們連到的是同一批主機,下載的也是同一個執行檔,所以不能用來處理地區限制。另外,用 Homebrew 或 WinGet 安裝的版本預設不會自動更新,原生安裝則會在背景自動更新。
claude 找得到卻打不開:先跑 claude doctor
如果 shell 找得到 claude,但它完全無法啟動,官方文件的建議是在 shell 裡執行:
claude doctorclaude doctor 不會開啟對話,只會印出唯讀的診斷資訊,內容包括安裝狀態、設定檔的驗證錯誤,以及附帶修正建議的警告。它本身也是 claude 的一部分,所以 shell 還找不到 claude 時它也無法執行,請先把 PATH 修好。工作階段裡的 /doctor 是另一個指令,兩者不要混淆。
在 Linux 上,文件另外用這行找出缺少的共用函式庫(shared library),有輸出的每一行都是缺少的項目:
ldd "$(command -v claude)" | grep "not found"在 macOS 上,文件收錄的不相容錯誤是 dyld: Symbol not found、dyld: cannot load 或 Abort trap: 6,原因是 macOS 版本低於 13.0。文件也說明,Homebrew 等替代安裝方式下載的是同一個執行檔,無法解決這個錯誤。
順利啟動之後,下一步是登入。登入時遇到金鑰相關的錯誤,可以看 Claude Code 出現 Invalid API key 的原因與處理。還沒決定用訂閱還是 API 金鑰登入的話,先讀 Claude Code 用訂閱登入還是 API 金鑰。
官方文件沒寫的三種錯誤:怎麼自己收集線索?
bad CPU type in executable、zsh: permission denied: claude(指的是 claude 本身,不是 .zshrc)和 macOS 上的 zsh: killed claude,在 2026 年 11 月 13 日查閱的官方安裝疑難排解文件裡都找不到。下面不替它們猜原因,只教你收集事實。這些事實可以幫你判斷方向,也是回報問題時最有用的資料。
uname -m
file -L "$(command -v claude)"
ls -la "$(command -v claude)"uname -m印出這台機器的處理器架構名稱。官方文件在Illegal instruction那一節就是用它檢查架構。Windows PowerShell 的對應寫法是$env:PROCESSOR_ARCHITECTURE。file會檢查檔案內容,判斷它屬於哪一類,執行檔會被標示為 executable。-L不能省:file預設不跟隨符號連結,而原生安裝的claude是一個符號連結,不加-L只會看到「這是一個連結」。如果結果寫出架構名稱,就拿來和uname -m的結果比對。ls -la顯示這個檔案的權限位元、擁有者,以及符號連結指向哪裡。權限欄裡有沒有x,決定你能不能執行它。
bad CPU type in executable 是不是下載到別的架構?
官方文件沒有收錄這個訊息,所以不能直接下結論。請比對 uname -m 和 file -L 的結果。文件在 Illegal instruction 一節提到一種相近的情況:安裝程式下載了錯誤架構的執行檔,例如在 ARM 伺服器上拿到 x86 版本。文件對那種情況的建議是到 GitHub 開 issue。如果你的兩個結果對不上,把兩段輸出一起附上回報。
zsh: permission denied: claude 是不是權限沒設好?
這和前面 .zshrc 的訊息不同,被拒絕的是 claude 這個程式本身。文件沒有說明這種情況應該看到什麼輸出,所以請自己讀 ls -la 的結果:權限欄裡有沒有 x、擁有者是不是你、符號連結指到哪裡,以及那個目標檔案是否存在。也可以用前面 test -w ~/.local/bin 那一行確認安裝目錄的權限。
macOS 上的 zsh: killed claude 是不是記憶體不足?
官方文件談的記憶體不足,是 Linux 上安裝那一步被終止,沒有涵蓋 macOS 上執行 claude 時被終止的情況。所以不要直接套用 swap 的修法。先執行 claude doctor,再加上前面三行指令的輸出。如果每次都能重現,把這些資料附在 GitHub issue 裡,比任何猜測都更有用。
FAQ
裝完 Claude Code 後出現 zsh: command not found: claude,怎麼辦?
原生安裝程式把 claude 放在 ~/.local/bin,但不會自己修改 PATH。先用 ls -la ~/.local/bin/claude 確認檔案存在,再執行 echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc 和 source ~/.zshrc。Linux 的 Bash 改用 ~/.bashrc,macOS 的 Bash 改用 ~/.bash_profile。最後開一個新的終端機視窗,執行 claude --version,印出版本號碼就代表修好了。
為什麼 VS Code 裡能用 Claude,內建終端機卻找不到 claude?
VS Code 擴充功能內含一份私有的 CLI,只給它的聊天面板使用,不會把 claude 放進 PATH,也不會建立 ~/.local/bin/claude。要在終端機裡輸入 claude,必須另外執行原生安裝指令,把 ~/.local/bin 加進 PATH,再把 VS Code 整個關掉重開,因為內建終端機的 PATH 來自編輯器本身。
在 VPS 上安裝 Claude Code 只顯示 Killed,是什麼原因?
官方文件說,Linux 安裝時出現 Killed,通常是系統記憶體不足,OOM killer 把 claude install 那一步終止了,安裝腳本會以結束碼 137 離開。安裝大約需要 512 MB 可用記憶體,執行 Claude Code 則需要至少 4 GB 記憶體。換大一點的主機最好。做不到的話,用 fallocate、chmod 600、mkswap、swapon 加一個 2 GB 的 swap 檔,再重新安裝。
在香港執行安裝指令出現 syntax error near unexpected token '<',是腳本壞了嗎?
這個錯誤代表下載回來的是網頁,不是安裝腳本。如果輸出裡出現 App unavailable in region,原因是地區限制:依 2026 年 11 月 13 日的 Anthropic 支援地區頁面,清單包含台灣,但沒有香港和澳門,而 Claude Code 只在清單上的地區提供。這不是腳本或 shell 的問題。輸出裡沒有這段文字時,也可能是公司代理伺服器、防火牆或暫時的網路問題,可以用 curl -sI https://downloads.claude.ai/claude-code-releases/latest 檢查連線。