跳到內容
開發容器

疑難排解

容器無法啟動

Section titled “容器無法啟動”

「Conflict. The container name is already in use」

Section titled “「Conflict. The container name is already in use」”
Terminal window
docker rm -f devcontainer
docker compose up -d

AI 工具無法運作

Section titled “AI 工具無法運作”

「claude: command not found」

Section titled “「claude: command not found」”

映像檔可能已過時。拉取最新版本並重新啟動：

Terminal window
docker compose pull
docker compose up -d

Claude 顯示「Not logged in」

Section titled “Claude 顯示「Not logged in」”

進入點會在 ~/.claude.json 中設定初始化旗標。如果該檔案遺失：

Terminal window
echo '{"hasCompletedOnboarding": true}' > ~/.claude.json

Claude 顯示「Invalid API key」

Section titled “Claude 顯示「Invalid API key」”

檢查實際設定的值：

Terminal window
echo "$ANTHROPIC_API_KEY"

常見原因：

  • LiteLLM 代理金鑰遺失或無效 — 如果您使用代理模式，請確認 .env 中的 LITELLM_API_KEY 包含正確的代理憑證，然後重新啟動容器，讓進入點能夠衍生 ANTHROPIC_API_KEY。
  • OAuth 權杖或代理模式不匹配 — 請僅使用一種驗證模式。如果設定了 CLAUDE_CODE_OAUTH_TOKEN，它會優先於 LiteLLM 代理模式。

API 請求回傳 401 錯誤

Section titled “API 請求回傳 401 錯誤”

檢查您的 API 金鑰是否正確設定：

Terminal window
echo "$ANTHROPIC_API_KEY"

透過直接呼叫您的提供者來驗證金鑰是否有效。

Claude 顯示「model not found」

Section titled “Claude 顯示「model not found」”

模型由您的提供者和 API 金鑰決定。請查閱您提供者的文件以了解可用的模型。

GitHub CLI

Section titled “GitHub CLI”

「gh: not authenticated」

Section titled “「gh: not authenticated」”

gh CLI 需要 GH_TOKEN 環境變數。將其新增至您的 .env 檔案：

GH_TOKEN=ghp_your-token-here

在 github.com/settings/tokens 建立權杖。細粒度權杖（建議）或具有 repo 範圍的傳統權杖皆可使用。更新 .env 後請重新啟動容器。

HTTPS git clone 因 401 失敗

Section titled “HTTPS git clone 因 401 失敗”

當設定了 GH_TOKEN 時，進入點會執行 gh auth setup-git 來設定 HTTPS 的 git 憑證助手。如果 HTTPS 操作失敗：

  1. 驗證權杖是否有效：gh auth status
  2. 檢查憑證助手是否已設定：git config --global credential.helper
  3. 重新啟動容器以重新執行進入點

SSH 與 HTTPS

Section titled “SSH 與 HTTPS”

容器中兩種驗證方法可以共存：

  • SSH（.env 中的 SSH_PRIVATE_KEY）— 使用 git@github.com: URL。如果您的組織強制要求 SSH 則為必要。
  • HTTPS（.env 中的 GH_TOKEN）— 使用 https://github.com/ URL。設定更簡單，無需管理金鑰。

如果兩者都已設定，git 會使用與遠端 URL 匹配的協定。要切換現有的 clone：

Terminal window
# SSH 轉 HTTPS
git remote set-url origin https://github.com/owner/repo.git


# HTTPS 轉 SSH
git remote set-url origin git@github.com:owner/repo.git

權限問題

Section titled “權限問題”

/workspace 或 /home 出現「Permission denied」

Section titled “/workspace 或 /home 出現「Permission denied」”
Terminal window
sudo chown -R $(id -u):$(id -g) /workspace ~

npm install 因 EACCES 失敗

Section titled “npm install 因 EACCES 失敗”

進入點會自動在 ~/.npm-global 設定使用者可寫的 npm 全域前綴，因此執行階段的 npm install -g 命令應無需 sudo 即可運作。如果仍然出現 EACCES 錯誤，請手動重新套用修正：

Terminal window
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
export PATH="$HOME/.npm-global/bin:$PATH"

建置問題

Section titled “建置問題”

建置耗時很長

Section titled “建置耗時很長”

首次建置需要下載基礎映像檔（約 1 GB）。後續建置會使用快取。如果每次都很慢：

Terminal window
docker builder prune

「No space left on device」

Section titled “「No space left on device」”
Terminal window
docker system prune -a --volumes

警告： 這會移除所有未使用的容器、映像檔和磁碟區 — 不僅限於此專案的。

網路

Section titled “網路”

容器內無法連線至網際網路

Section titled “容器內無法連線至網際網路”
Terminal window
ping -c 1 8.8.8.8
nslookup google.com
curl -I https://github.com

如果 DNS 失敗，請在主機的 /etc/docker/daemon.json 中新增：

{
  "dns": ["8.8.8.8", "8.8.4.4"]
}

然後重新啟動 Docker。

遠端顯示（noVNC）

Section titled “遠端顯示（noVNC）”

noVNC 顯示黑畫面

Section titled “noVNC 顯示黑畫面”

Xvfb 可能尚未啟動。在容器內檢查：

Terminal window
ps aux | grep Xvfb

如果未在執行，請檢查 ENABLE_VNC 是否未設定為 false，然後重新啟動容器。

「Cannot open display」或「No display」錯誤

Section titled “「Cannot open display」或「No display」錯誤”

DISPLAY 環境變數可能未設定。驗證：

Terminal window
echo "$DISPLAY"

應為 :99。如果為空，請在您的 .env 或 devcontainer.json 中新增 DISPLAY=:99 並重新啟動。

連接埠 6080 連線被拒

Section titled “連接埠 6080 連線被拒”

noVNC 可能未在執行。在容器內檢查：

Terminal window
ps aux | grep -E 'novnc|websockify'

如果未在執行，請確認 ENABLE_VNC 為 true（預設值）並檢查容器日誌：

Terminal window
docker compose logs dev | grep -i vnc

連接埠 6080 已被佔用

Section titled “連接埠 6080 已被佔用”

在 docker-compose.yml 中變更主機連接埠：

ports:
  - "127.0.0.1:16080:6080"

Chrome DevTools MCP

Section titled “Chrome DevTools MCP”

Chrome 遠端除錯無回應

Section titled “Chrome 遠端除錯無回應”

共享的 Chrome 實例應在連接埠 9222 上執行。在容器內檢查：

Terminal window
# Chrome 是否在執行？
curl http://localhost:9222/json/version


# 檢查 Chrome 日誌
cat ~/.local/share/chrome-browser/chrome.log


# 驗證符號連結
ls -la /opt/google/chrome/chrome


# 手動重新啟動 Chrome
. /usr/local/lib/chrome-browser.sh
start_chrome_browser

如果符號連結遺失，請拉取最新映像檔並重新啟動容器。

瀏覽器設定檔鎖定錯誤

Section titled “瀏覽器設定檔鎖定錯誤”

使用共享瀏覽器架構時，設定檔鎖定錯誤不應發生。如果您遇到此問題，可能是殘留的 Chrome 程序持有鎖定：

Terminal window
# 終止任何殘留的 Chrome 程序
pkill -f 'chrome.*remote-debugging-port' || true


# 移除鎖定檔案
rm -f ~/.cache/chrome-devtools-mcp/chrome-profile/SingletonLock


# 重新啟動 Chrome
. /usr/local/lib/chrome-browser.sh
start_chrome_browser

重複的 chrome-devtools-mcp 工具

Section titled “重複的 chrome-devtools-mcp 工具”

chrome-devtools-mcp 伺服器現已在 ~/.claude/settings.json 中全域註冊。如果您有個別儲存庫的 .mcp.json 也註冊了它，您將會看到重複的工具。請從個別儲存庫的 .mcp.json 檔案中移除 chrome-devtools-mcp 條目：

Terminal window
# 檢查個別儲存庫的設定
cat .mcp.json

從任何個別儲存庫的 .mcp.json 中移除 chrome-devtools-mcp 鍵以使用全域註冊。

重設所有設定

Section titled “重設所有設定”
Terminal window
docker compose down -v
docker rm -f devcontainer 2>/dev/null
docker compose pull
docker compose up -d

這會銷毀磁碟區中的所有資料。您需要重新 clone 儲存庫並重新設定工具。