SpyBara
Go Premium

devcontainer.md 2026-10-19 23:58 UTC to 2026-10-20 23:00 UTC

This page contains 58 additions and 78 deletions.

2026
Tue 20 23:00 Thu 22 22:58 Fri 23 22:59 Wed 28 23:57 Fri 30 23:01

開發容器

在開發容器中執行 Claude Code，為您的團隊提供一致、隔離的環境。

開發容器（或 dev container）讓您定義一個相同的隔離環境，您的團隊中的每位工程師都可以執行。安裝 Claude Code 在該容器中後，Claude 執行的命令會在容器內執行，而不是在主機上執行，同時對您的專案檔案的編輯會在您工作時出現在本地儲存庫中。

本頁涵蓋在開發容器中安裝 Claude Code，然後是一組獨立的配置主題：在重新構建時保持身份驗證、強制執行組織政策、限制網路出站流量，以及無需權限提示即可執行。請閱讀與您的設定相符的主題。

[!WARNING]

雖然開發容器提供了大量保護，但沒有任何系統完全免疫所有攻擊。 當使用 --dangerously-skip-permissions 執行時，開發容器不會阻止惡意專案從容器內可存取的任何內容（包括儲存在 ~/.claude 中的 Claude Code 認證）進行資料外洩。 僅在使用受信任的儲存庫進行開發時使用開發容器，並監控 Claude 的活動。 避免將主機祕密（例如 ~/.ssh 或雲端認證檔案）掛載到容器中；優先使用儲存庫範圍或短期有效的令牌。

開發容器如何與您的編輯器配合使用

顯示主機上的編輯器連接到 Docker 開發容器的圖表。Claude Code、終端和構建工具在容器內執行。主機儲存庫被綁定掛載到容器中作為工作區。

開發容器作為 Docker 容器執行，可以在您的機器上或雲端主機（例如 GitHub Codespaces）上執行。支援 Dev Containers 規範的編輯器（例如 VS Code、GitHub Codespaces、JetBrains IDE 或 Cursor）連接到該容器：您在編輯器中照常瀏覽和編輯檔案，但整合終端、語言伺服器和構建工具都在容器內執行，而不是在您的主機上。不支援開發容器的編輯器（例如純 Vim）不是此工作流程的一部分。

Claude Code 在容器內執行，因此它看到與您的專案工具鏈其餘部分相同的檔案、依賴項和工具。在 VS Code 中，您可以使用 Claude Code 擴充功能面板 或在整合終端中執行 claude；兩者都在容器內執行並共享相同的 ~/.claude 配置。

在開發容器中新增 Claude Code

Claude Code 透過 Claude Code Dev Container Feature 安裝到任何開發容器中。

這些設定適用於任何支援 Dev Containers 規範的工具，例如 VS Code、GitHub Codespaces 或 JetBrains IDE。下面的步驟以 VS Code 為例。

當您在 VS Code 或 Codespaces 中開啟容器時，該功能還會新增 Claude Code VS Code 擴充功能；其他編輯器會忽略該部分。

[!TIP]

初次接觸開發容器？VS Code Dev Containers 教程會逐步介紹安裝 Docker、擴充功能和開啟您的第一個容器。如需更完整的強化示例（包含防火牆和持久磁碟區），請參閱試用參考容器。

1. 建立或更新 devcontainer.json

將以下內容儲存為儲存庫中的 .devcontainer/devcontainer.json，或將 features 區塊新增到您現有的檔案中。

末尾的版本標籤（例如 :1.0）會固定功能的安裝指令碼，而不是 Claude Code 版本。該功能會安裝最新的 Claude Code，Claude Code 預設會在容器內自動更新。

若要固定 CLI 版本或停用自動更新，請參閱強制執行組織政策。

{
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
  "features": {
    "ghcr.io/anthropics/devcontainer-features/claude-code:1.0": {}
  }
}

將 image 行替換為您的專案的基礎映像，或如果您現有的檔案使用 Dockerfile，則將其移除。

Claude Code 功能會在基礎映像未提供 Node.js 時自行安裝。如果該安裝失敗且構建停止並顯示 Failed to install Node.js and npm，請將 "ghcr.io/devcontainers/features/node:1": {} 新增到上述 features 區塊中 Claude Code 功能的上方，然後重新構建。

2. 重新構建容器

在 Mac 上使用 Cmd+Shift+P 或在 Windows 和 Linux 上使用 Ctrl+Shift+P 開啟 VS Code 命令面板，並執行 Dev Containers: Rebuild Container。

對於其他工具，請遵循該工具的重新構建操作：請參閱 GitHub Codespaces 中的重新構建、Dev Containers CLI 或您的 IDE 的開發容器文件。

3. 登入 Claude Code

在重新構建的容器中開啟終端並執行 claude，然後按照身份驗證提示進行操作。

您在身份驗證提示中看到的內容取決於您的提供者：

對於雲端提供者，透過 containerEnv、Codespaces 祕密或您的雲端的工作負載身份（而不是從主機掛載認證檔案）將認證傳遞到容器中。請參閱 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 以了解 Claude Code 讀取的認證鏈。

請參閱選擇您的 API 提供者以決定哪條路徑適合您的組織。

[!NOTE]

如果瀏覽器登入完成但回調從未到達容器，請複製瀏覽器中顯示的代碼，並將其貼上到終端中的 Paste code here if prompted 提示處。當編輯器的連接埠轉發不會路由 localhost 回調時，可能會發生這種情況。

在重新構建時保持身份驗證和設定

預設情況下，容器的主目錄在重新構建時會被丟棄，因此工程師必須每次都重新登入。Claude Code 將其身份驗證令牌、使用者設定和工作階段歷史記錄儲存在 ~/.claude 目錄下。它將您的 OAuth 帳戶、個人 MCP 伺服器和每個專案的信任設定儲存在 ~/.claude.json 中，這是位於該目錄外的單獨檔案，因此僅在 ~/.claude 掛載一個磁碟區不足以讓您保持登入狀態。在 ~/.claude 掛載一個命名磁碟區，並將 CLAUDE_CONFIG_DIR 設定為相同路徑，以便 Claude Code 在磁碟區內寫入 .claude.json。

以下示例為 remoteUser 為 node 的容器掛載磁碟區並設定 CLAUDE_CONFIG_DIR：

"mounts": [
  "source=claude-code-config,target=/home/node/.claude,type=volume"
],
"containerEnv": {
  "CLAUDE_CONFIG_DIR": "/home/node/.claude"
}

將 /home/node 替換為您的容器的 remoteUser 的主目錄。如果您已經設定了 containerEnv，例如在強制執行組織政策中，請將 CLAUDE_CONFIG_DIR 新增到該物件，而不是新增第二個物件。

若要隔離每個專案的狀態，而不是在所有儲存庫中共享一個磁碟區，請在來源名稱中包含 ${devcontainerId} 變數。參考配置為此目的使用 source=claude-code-config-${devcontainerId}。

在 GitHub Codespaces 中，~/.claude 在停止和啟動 codespace 時會保持，但在重新構建容器時仍會被清除，因此上面的配置也適用於此。

若要在 codespace 之間進行身份驗證，請將 ANTHROPIC_API_KEY 或來自 claude setup-token 的 CLAUDE_CODE_OAUTH_TOKEN 儲存為 Codespaces 祕密。Codespaces 會自動將祕密作為環境變數提供給容器內。

強制執行組織政策

開發容器是應用組織政策的便利場所，因為相同的映像和配置在每位工程師的機器上執行。

Claude Code 在 Linux 上讀取 /etc/claude-code/managed-settings.json 並在設定層級結構中以最高優先級應用它，因此那裡的值會覆蓋工程師在 ~/.claude 或專案的 .claude/ 目錄中設定的任何內容。從您的 Dockerfile 複製檔案到位置：

RUN mkdir -p /etc/claude-code
COPY managed-settings.json /etc/claude-code/managed-settings.json

因為 Dockerfile 存在於儲存庫中，任何具有寫入存取權限的人都可以更改或移除此步驟。對於工程師無法透過編輯儲存庫檔案來繞過的政策，請透過伺服器管理的設定或您的 MDM 提供託管設定。請參閱託管設定檔案以了解可用的鍵和其他傳遞路徑。

若要設定適用於容器中每個 Claude Code 工作階段的環境變數，請將它們新增到您的 devcontainer.json 中的 containerEnv。以下示例選擇退出遙測和錯誤報告，並防止 Claude Code 在安裝後自動更新：

"containerEnv": {
  "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
  "DISABLE_AUTOUPDATER": "1"
}

CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC 也會停用遠端控制和其他需要功能旗標擷取的功能所依賴的功能旗標評估，因此容器中的工作階段無法使用它們。

Dev Container Feature 始終安裝最新的 Claude Code 版本。若要為可重現的構建固定特定的 Claude Code 版本，請從您的 Dockerfile 使用 npm install -g @anthropic-ai/claude-code@X.Y.Z 安裝它，而不是使用該功能，並在 containerEnv 中設定 DISABLE_AUTOUPDATER 為 1。

如需完整的政策控制清單（包括權限規則、工具限制和 MCP 伺服器允許清單），請參閱為您的組織設定 Claude Code。

若要在容器內提供 MCP 伺服器，請在儲存庫根目錄的 .mcp.json 檔案中以專案範圍定義它們，以便它們與您的開發容器配置一起簽入。在您的 Dockerfile 中安裝本地 stdio 伺服器所依賴的任何二進位檔案，並將遠端伺服器網域新增到您的網路允許清單。

限制網路出站流量

您可以將容器的出站流量限制為僅 Claude Code 需要的網域。請參閱網路存取要求以了解推理和身份驗證網域，以及遙測服務以了解可選的遙測和錯誤報告連接以及如何停用它們。

參考容器包含一個 init-firewall.sh 指令碼，該指令碼會限制出站流量僅限於指令碼允許的目的地。在容器內執行防火牆需要額外的權限，因此參考透過 runArgs 新增 NET_ADMIN 和 NET_RAW 功能。防火牆指令碼和這些功能對 Claude Code 本身不是必需的：您可以將它們省略並改為依賴您自己的網路控制。

無需權限提示即可執行

因為容器以非 root 使用者身份執行 Claude Code 並將命令執行限制在容器內，您可以傳遞 --dangerously-skip-permissions 以進行無人值守操作。當以 root 身份啟動時，CLI 會拒絕此標誌，因此請確認 remoteUser 設定為非 root 帳戶。

跳過權限提示會移除您在工具呼叫執行前進行審查的機會。Claude 仍然可以修改綁定掛載工作區中的任何檔案（該檔案直接出現在您的主機上），並到達容器的網路政策允許的任何內容。將此標誌與上面的網路出站流量限制配對，以限制繞過的工作階段可以到達的內容。

如果您想要更少的提示而不停用安全檢查，請考慮改為自動模式，該模式具有在執行前審查操作的分類器。若要完全防止工程師使用 --dangerously-skip-permissions，請在託管設定中將 permissions.disableBypassPermissionsMode 設定為 "disable"。

試用參考容器

anthropics/claude-code 儲存庫包含一個示例開發容器，該容器結合了 CLI、出站防火牆、持久磁碟區和基於 Zsh 的 shell。它作為工作示例而不是維護的基礎映像提供；在將它們應用到您自己的配置之前，使用它來查看這些部分如何組合在一起。

1. 安裝先決條件

安裝 VS Code 和 Dev Containers 擴充功能。

2. 複製參考

複製 Claude Code 儲存庫並在 VS Code 中開啟它。

3. 在容器中重新開啟

出現提示時，點擊 Reopen in Container，或從命令面板執行 Dev Containers: Reopen in Container。

4. 啟動 Claude Code

容器完成構建後，使用 Ctrl+` 開啟終端並執行 claude 以登入並啟動您的第一個工作階段。

若要將此配置用於您自己的專案，請將 .devcontainer/ 目錄複製到您的儲存庫中並根據您的工具鏈調整 Dockerfile，或返回在開發容器中新增 Claude Code 以僅將功能新增到您已有的設定中。

參考配置由三個檔案組成。當您透過功能將 Claude Code 新增到您自己的開發容器時，這些都不是必需的，但它們展示了一種組合這些部分的方式。

檔案 目的
devcontainer.json 磁碟區掛載、runArgs 功能、VS Code 擴充功能和 containerEnv
Dockerfile 基礎映像、開發工具和 Claude Code 安裝
init-firewall.sh 阻止除允許的網域外的所有出站網路流量

後續步驟

Claude Code 在您的開發容器中執行後，下面的頁面涵蓋組織推出的其餘部分：選擇身份驗證路徑、在儲存庫外提供託管政策、監控使用情況以及了解 Claude Code 儲存和傳送的內容。