Claude Code 部署報錯：常見問題與 10 分鐘修復指南

「『裝好了，但跑不起來』——這是 Claude Code 使用者最集中的反饋，而且幾乎每一條報錯背後都是同一批原因。」本文把 5 類最高頻錯誤逐條拆開：先看報錯原文，再給出可直接複製的修復指令，最後附一張診斷流程圖，幫你在 10 分鐘內定位並解決問題。

高頻報錯類型

<10

分鐘修復時間（分鐘）

張診斷流程圖

錯誤 1：API 金鑰無效或未配置

這是新手最常見的第一道坎。Claude Code 依賴環境變數 ANTHROPIC_API_KEY 鑑權，金鑰缺失或格式錯誤會立刻報錯，但提示訊息因 shell 版本不同而略有差異。

典型報錯訊息：

終端輸出

# 常見的三種形式，遇到其中任一即屬此類
Error: ANTHROPIC_API_KEY is not set
AuthenticationError: 401 {"type":"error","error":{"type":"authentication_error","message":"invalid x-api-key"}}
Error: Your API key is invalid.

修復步驟：

bash / zsh

# 1. 檢查目前 shell 是否已有金鑰
echo $ANTHROPIC_API_KEY

# 2. 暫時設定（僅當前會話有效）
export ANTHROPIC_API_KEY="sk-ant-api03-xxxxxxxxxx"

# 3. 寫入設定檔，永久生效（zsh 用 ~/.zshrc，bash 用 ~/.bashrc）
echo 'export ANTHROPIC_API_KEY="sk-ant-api03-xxxxxxxxxx"' >> ~/.zshrc
source ~/.zshrc

# 4. 驗證金鑰格式：必須以 sk-ant-api 開頭
claude --version

金鑰來源

API Key 在 console.anthropic.com → API Keys 頁面生成。注意：Key 只在建立時顯示一次，請立即複製儲存；若已遺失需重新生成。

錯誤 2：Node.js 版本不相容

Claude Code 對 Node.js 版本有明確要求（≥ 18），低版本會在安裝或啟動時拋出語法錯誤，有時報錯指向內部檔案，讓人摸不著頭緒。

典型報錯訊息：

終端輸出

SyntaxError: Unexpected token '?'
engine "node" is incompatible with this module. Expected version ">=18". Got "16.x.x"
Error [ERR_REQUIRE_ESM]: require() of ES Module ... not supported.

修復步驟：

bash / zsh

# 1. 確認目前 Node 版本
node -v

# 2a. 使用 nvm 切換（推薦：隔離多版本，不破壞系統環境）
nvm install 22
nvm use 22
nvm alias default 22

# 2b. macOS 用 Homebrew 直接升級（若未用 nvm）
brew install node@22
brew link --overwrite node@22

# 3. 升級後重新安裝 Claude Code
npm uninstall -g @anthropic-ai/claude-code
npm install -g @anthropic-ai/claude-code

Linux 伺服器常見陷阱

許多 Ubuntu/Debian 系統的 apt 預設倉庫裡的 Node.js 仍是 v12 或 v16。建議透過 NodeSource 或 nvm 安裝，避免用 apt install nodejs 拿到舊版本後反覆排查。

錯誤 3：權限被拒絕（Permission Denied）

權限報錯分兩種：一種是 npm 全域安裝權限不足，另一種是 Claude Code 執行時請求執行 bash 指令被系統或使用者策略拒絕。

典型報錯訊息：

終端輸出

npm ERR! Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules'
Error: Permission denied (tool: bash)
EPERM: operation not permitted, unlink

修復步驟——npm 安裝權限：

bash / zsh（推薦方式：修改 npm prefix，無需 sudo）

# 把全域套件目錄改到使用者主目錄，徹底擺脫 sudo 依賴
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'

# 將新目錄加入 PATH（寫入對應設定檔後 source 生效）
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

# 重新安裝
npm install -g @anthropic-ai/claude-code

修復步驟——Tool 權限（bash/file system 被 Claude Code 策略攔截）：

bash / zsh

# 在專案根目錄啟動時，顯式允許工具
claude --allowedTools "bash,read,write,edit"

# 或在 CLAUDE.md 中設定（專案級持久化）
# CI 伺服器上加 --dangerously-skip-permissions 跳過互動確認
# 注意：僅限可信環境
claude --dangerously-skip-permissions -p "your prompt here"

錯誤 4：網路逾時或代理問題

Claude Code 需要存取 api.anthropic.com，在網路受限環境（公司內網、代理、部分雲主機區域）下會出現連線逾時或 TLS 握手失敗。

典型報錯訊息：

終端輸出

FetchError: request to https://api.anthropic.com/v1/messages failed, reason: connect ETIMEDOUT
Error: Network request failed: ENOTFOUND api.anthropic.com
ProxyError: tunneling socket could not be established, cause=connect ECONNREFUSED

修復步驟：

bash / zsh

# 1. 先驗證網路直連是否可達
curl -v https://api.anthropic.com/v1/messages -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" -H "content-type: application/json" \
  -d '{"model":"claude-opus-4-5","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'

# 2. 若需要 HTTP 代理，設定標準環境變數
export HTTPS_PROXY="http://proxy.company.com:8080"
export HTTP_PROXY="http://proxy.company.com:8080"
export NO_PROXY="localhost,127.0.0.1,internal.company.com"

# 3. 若代理需要認證
export HTTPS_PROXY="http://username:password@proxy.company.com:8080"

# 4. 設定 Claude Code 的自訂 base URL（企業內網代理閘道場景）
export ANTHROPIC_BASE_URL="https://your-internal-gateway.company.com"

macOS 系統代理注意事項

macOS 系統偏好設定裡的代理不會自動被 Node.js 行程繼承。必須在啟動 Claude Code 的 shell 會話裡顯式設定 HTTPS_PROXY 環境變數，或者在 ~/.zshrc 裡永久寫入。

錯誤 5：記憶體不足導致行程崩潰（OOM）

處理大型程式碼庫或長對話時，Claude Code 和其他 Node.js 行程共用的堆積記憶體可能耗盡。這類錯誤在 8GB RAM 的機器或記憶體限制嚴格的 CI 容器裡最為常見。

典型報錯訊息：

終端輸出

FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed - JavaScript heap out of memory
Killed (signal 9)     ← Linux OOM Killer 直接終止行程
RangeError: Maximum call stack size exceeded

修復步驟：

bash / zsh

# 1. 提高 Node.js 堆積記憶體上限（單位 MB，根據機器 RAM 調整）
export NODE_OPTIONS="--max-old-space-size=4096"   # 4 GB
claude

# 2. 若機器 RAM 本身不足，先檢查目前佔用
free -h          # Linux
vm_stat          # macOS（關注 Pages free × 4096 / 1024²）

# 3. 處理超大程式碼庫時，使用 .claudeignore 排除不必要目錄
# 在專案根目錄建立 .claudeignore，語法與 .gitignore 相同：
# node_modules/
# dist/
# .next/
# *.lock

# 4. 長對話建議定期用 /clear 清空上下文，減少記憶體積壓

機器 RAM	建議 `--max-old-space-size`	備註
8 GB	2048	保留系統與其他行程約 6 GB
16 GB	4096	適合中等規模程式碼庫
24 GB（M4 Mac mini 標配）	8192	可處理大型 monorepo
32 GB+	16384	企業級專案 / 並行多實例

診斷流程圖：10 分鐘定位路徑

執行 claude或 npm install -g（或任何 Claude Code 指令）

出現報錯

看報錯關鍵詞api-key / Node / EACCES / timeout / OOM

對號入座

執行對應修復指令複製本文代碼塊，貼上執行

驗證

claude --version 無報錯進入正常對話界面即成功

快速關鍵詞對照

api-key / 401 → 錯誤 1
SyntaxError / ESM → 錯誤 2
EACCES / permission → 錯誤 3
ETIMEDOUT / ENOTFOUND → 錯誤 4
heap out of memory / Killed → 錯誤 5

仍未解決？檢查這幾點

Node 版本 ≥ 18（node -v）
金鑰以 sk-ant-api 開頭
curl 可直連 api.anthropic.com
確認未用 sudo npm install -g

按報錯關鍵詞對號入座，通常 3 步以內可定位根因並完成修復。

額外技巧：讓 Claude Code 在伺服器上更穩定執行

在 CI 伺服器或雲主機上長期執行 Claude Code，除了解決上面 5 類錯誤，還有幾個小細節值得關注：

使用 tmux 或 screen— SSH 斷線後行程繼續執行，避免長任務中途遺失
寫入 CLAUDE.md— 把專案約定、禁止操作的目錄、API 文件位置寫進去，減少 Claude Code 每次詢問帶來的 token 消耗
設定 --output-format json— 在自動化腳本中更容易解析回應，配合 -p 非互動模式使用
環境變數統一管理— 用 .env 檔案配合 direnv，進入專案目錄自動載入，不需要每次手動 export

在專用 macOS 伺服器上部署更穩定

記憶體充足（16–24 GB 統一記憶體）、網路直連、無需繞過代理——這是大多數 Claude Code OOM 和網路逾時問題消失的根本原因。ZavCloud 的 Mac mini M4 獨享實例預裝 Node.js 環境，開機即可部署。

ZavCloud Cloud Mac

在獨享 macOS 上執行 Claude Code

Mac mini M4 獨享實例：24 GB 統一記憶體、1Gbps 直連出口、真實 macOS 環境——告別 OOM 與網路逾時，專注寫程式碼。

立即開始配置