Claude Code 為什麼推薦 Docker？新手完整指南（2026版）

你剛裝好 Claude Code，翻官方文件，第一屏就可能看到 devcontainer、Docker、--dangerously-skip-permissions 這些詞。很多人第一反應是：「我只是想讓 AI 幫我寫點程式，為什麼要我學容器？」

這不是 Anthropic 故意為難新手。Claude Code 和一般程式碼補全最大的差別，是它會真的在你的機器上執行命令、改多個檔案、拉依賴、跑測試。 能力越強，誤操作和越權的風險就越大。Docker 在這裡扮演的角色，是給這套能力加一道可複製的「圍欄」——既保護你的本機，也讓團隊每個人跑在同一套環境裡。

這篇指南按新手能跟上的順序寫：先講清「為什麼推薦」→ 30 秒理解 Docker → 官方 devcontainer 怎麼接 → 手把手第一次跑通 → 什麼時候其實不用 Docker。 你不需要先成為維運專家。

一句話：Claude Code 為什麼總愛提 Docker？

核心原因可以收成三條：

• 隔離：容器裡跑的命令，預設碰不到你主機的 ~/.ssh、雲端憑證、私人照片目錄——除非你主動 mount 進去。
• 可重現：.devcontainer/devcontainer.json 寫清楚 Node 版本、要裝哪些 CLI，同事 clone 倉庫後重建容器，環境和你一致，少掉「我這邊能跑你那邊不行」。
• 安全基線：Anthropic 在 claude-code 倉庫 裡維護了參考 devcontainer，帶預設拒絕的出站防火牆（只允許 npm、GitHub、Anthropic API 等白名單網域）。這讓「無人值守跑 Agent」在文件裡有了可辯護的前提。

官方 Development containers 文件 寫得很直白：dev container 跑在 Docker 裡，編輯器（Cursor、VS Code、JetBrains 等）連到容器，終端機和建置工具在容器內執行，你編輯的檔案仍對應回本機倉庫。 Claude Code 安裝的命令也在容器裡跑——這就是「推薦 Docker」的完整含義，不是讓你把所有開發都搬進容器，而是給 AI 代理劃一塊工地。

給完全新手：Docker 到底是什麼？

先忘掉 Kubernetes、微服務那些大詞。對 Claude Code 新手，你只需要這一個比喻：

Docker 容器 = 一個輕量、可丟棄的「迷你電腦」，裡面預裝好作業系統切片、Node/Python、你要的工具；它和你的真電腦共享 CPU，但檔案系統和網路可以單獨設定。

和虛擬機比，容器啟動快、佔用小；和「直接在本機裝軟體」比，容器刪了不留垃圾——這對 AI 特別重要，因為 Claude 可能一天裡幫你試十種依賴組合。

你會遇到的三個名詞，記住就夠：

更通用的 Docker 概念可看 Docker 官方 Get started；本文聚焦 Claude Code 那條最短路徑。

Anthropic 官方 devcontainer 裡有什麼？

倉庫 anthropics/claude-code 的 .devcontainer/ 不是裝飾，而是一套可複製的安全開發範本，主要檔案分工如下：

• devcontainer.json：掛載卷、環境變數、VS Code/Cursor 擴充功能、用哪個 Feature 安裝 Claude Code；
• Dockerfile：基礎映像檔（如 Debian/Ubuntu）、開發工具、非 root 使用者；
• init-firewall.sh：預設拒絕出站，只放行白名單網域——這是很多人自己寫 Dockerfile 時最容易漏掉的一塊。

文件推薦透過 Claude Code Dev Container Feature 安裝，例如在 devcontainer.json 裡宣告：

{
                  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
                  "features": {
                    "ghcr.io/anthropics/devcontainer-features/claude-code:1.0": {}
                  },
                  "remoteUser": "node",
                  "mounts": [
                    "source=claude-code-config-${devcontainerId},target=/home/node/.claude,type=volume"
                  ],
                  "containerEnv": {
                    "DISABLE_AUTOUPDATER": "1"
                  }
                }

注意 mounts 裡給 ~/.claude 單獨掛了命名卷：容器重建後，登入狀態和工作階段歷史可以保留，不必每次重新驗證。這是官方文件單獨開一節講的原因。

若你已經在用 ECC（Everything Claude Code） 那類設定合集，可以把 devcontainer 當成「硬體層」：ECC 管 skills 和 hooks，Docker 管 Claude 命令實際落在哪塊檔案系統上。

安全敘事：為什麼容器裡才能談「跳過權限確認」？

Claude Code 預設幾乎每次執行 bash、寫檔案都要你點確認。做 CI 流水線或長時間無人值守任務時，有人會加 --dangerously-skip-permissions。

官方立場很明確：這個旗標是為 hardened devcontainer 準備的，不是給本機桌面用的。 在本機跳過確認，等於讓 AI 無限制操作你的使用者目錄——能刪檔案、能讀鑰匙圈旁路、能往任意 URL 發包。容器方案至少做到：

• 檔案系統邊界：只 mount 專案目錄 + 必要的設定卷；
• 網路邊界：出站防火牆限制外聯目的地；
• 使用者邊界：非 root 執行，sudo 受限。

要強調：容器不是銀彈。 你若把 ~/.aws、正式環境資料庫 URL 寫進 .env 再 mount 進容器，AI 照樣能讀到。安全取決於你 mount 了什麼、倉庫是否可信。官方原文也寫：「Only use dev containers when developing with trusted repositories.」

手把手：第一次用 Docker 跑 Claude Code

下面是一條在 macOS／Windows（WSL2）上驗證過的路徑，不要求你先讀完 Docker 全書。

第 1 步：安裝 Docker 引擎

任選其一即可，團隊內統一更重要：

• macOS：Docker Desktop（最省心）；Apple Silicon 上 Colima、OrbStack 也常見，CLI 相容 docker 命令；
• Windows：Docker Desktop + WSL2 後端；
• Linux：直接裝 Docker Engine 或 rootless Podman（需確認 devcontainer CLI 支援）。

裝完後終端機執行 docker --version 和 docker run hello-world，看到 Hello from Docker 即過關。

第 2 步：準備專案與 devcontainer 設定

在你的倉庫根目錄新建 .devcontainer/。可以：

1. 從 anthropics/claude-code 複製參考設定再按專案改 Dockerfile；或
2. 在 Cursor／VS Code 裡執行命令 Dev Containers: Add Dev Container Configuration Files，再按官方文件加入 Claude Code Feature。

如果你完全不想手寫，打開 Claude Code（本機先裝一次 CLI 也行），用自然語言描述：「為這個 Node 20 專案產生 .devcontainer，要包含 Claude Code Feature 和 pnpm。」——AI 產生後你仍要人工檢查 mount 範圍和防火牆段是否合理。

第 3 步：在容器裡開啟專案

Cursor／VS Code 使用者：命令面板選 Dev Containers: Reopen in Container。首次會建置映像檔，可能要幾分鐘；之後增量啟動快很多。終端機提示字元變了、which node 指向容器內路徑，說明你已經「在盒子裡」了。

不用圖形編輯器也可以純終端機派：

# 在專案根目錄，已有 docker-compose.yml 時
                docker compose up -d
                docker compose exec dev bash
                claude

具體服務名稱以你的 compose 檔案為準；devcontainer 只是把這套流程標準化了。

第 4 步：驗證 Claude Code 在容器內工作

在容器終端機執行 claude，做一件小事：例如「列出 package.json 裡的 scripts 並解釋」。觀察：

• 檔案改動是否出現在宿主機 Git 狀態裡（應該出現，說明 bind mount 正常）；
• 執行 cat /etc/os-release 是否顯示容器 OS（而不是你本機版本）；
• 故意讓 Claude 存取一個你沒 mount 的路徑，是否被拒絕。

三項都符合預期，說明隔離層在工作。此後團隊文件可以寫死：「請 Reopen in Container 再跑 Claude Code」，新人不必單獨配 Node 版本。

什麼時候其實不用 Docker？

官方推薦不等於強制。以下場景本機直跑往往更省事：

判斷口訣：「我是否願意讓 AI 在我離開時自動執行命令？」 願意，且倉庫可信 → 上容器並收緊 mount；不願意 → 本機互動式就夠。

Mac 使用者補充：Docker 和 Apple 開發怎麼共存？

很多讀者用 Mac 同時做 Xcode 和 AI 輔助全端。實務上常見分工是：

• Xcode、模擬器、簽章留在本機 macOS；
• Node/Python 服務、Claude Code 長工作階段、實驗性腳本進 devcontainer；
• 需要統一團隊後端環境時，把 docker-compose.yml 放進倉庫，前後端 API 在容器裡聯調。

Apple Silicon 上容器跑 x86 映像檔會慢，優先選 arm64 基礎映像檔。記憶體建議給 Docker Desktop 至少 4～8GB，否則並行跑 dev server + Claude 容易 swap。

排障速查

• Rebuild 後 Claude 要重新登入：檢查 ~/.claude 是否掛進命名卷，而不是寫在容器可寫層裡。
• 容器裡存取不了 npm／GitHub：看 init-firewall.sh 白名單；公司代理還要額外設 HTTP_PROXY。
• 連接埠 3000 打不開：devcontainer 需在 forwardPorts 或 compose 裡宣告連接埠對應。
• 權限 denied：確認 remoteUser 對專案目錄有寫入權限；bind mount 的 UID 在 Linux 上常要對齊。
• Docker Desktop 啟動失敗：Windows 檢查 WSL2；Mac 檢查虛擬化是否被安全軟體攔截。

常見問題 FAQ

Claude Code 和 Cursor 內建的 Agent 都要 Docker 嗎？

不是。Cursor Agent 預設在你本機工作區跑；Claude Code 是獨立 CLI，官方為其提供了 devcontainer 一等公民支援。你可以 Cursor 編輯 + 容器終端機裡跑 claude，兩者可以並存。

devcontainer 一定要 VS Code 嗎？

不必。devcontainer 規範最初由 VS Code 推廣，但 Cursor、JetBrains、GitHub Codespaces 都支援。你也可以純 docker compose + shell，只是少了圖形化 Reopen in Container 的便利。

我已經會 docker compose 部署服務了，學這個重複嗎？

不重複。部署類 compose 關心「服務上線」；devcontainer 關心「開發時 Claude 在哪執行」。思維模式相通，但設定檔目的不同。部署經驗會讓你更快理解 mount 和網路。

容器裡的 Claude Code 怎麼更新？

官方 Feature 預設裝最新 CLI，且容器內常開自動更新。若你要鎖版本，在 Dockerfile 裡 pin 安裝腳本或在 containerEnv 設 DISABLE_AUTOUPDATER。

公司不讓裝 Docker Desktop 怎麼辦？

問 IT 是否提供遠端 devcontainer 主機、GitHub Codespaces 或內部 K8s 開發空間。Claude Code 需要的是「隔離的 Linux 環境」，不一定非在你筆電上跑 Docker。

收束：Docker 不是功課，是 Claude Code 的「安全帶」

回到標題：Claude Code 為什麼推薦 Docker？

• 因為 AI 程式助手已經能執行，而不只是建議；
• 因為團隊需要同一套可重建的環境，而不是截圖教新人裝 Node；
• 因為 Anthropic 想把無人值守模式關在防火牆後的容器裡，而不是散養在你的 ~/ 目錄。

新手不必被嚇到。今天只要完成一件事：在一個小專案裡 Reopen in Container，在容器終端機敲一次 claude，親眼看到命令發生在容器內、檔案改在宿主機上。 這一步跑通，你就比大多數只看文件的人領先一截。

之後無論是配 ECC、接 MCP，還是把 Agent 部署到 VPS，你都會發現：Docker 成了 AI 時代的「通用安裝程式」——而 Claude Code 官方只是比誰都更早、更明確地把這件事寫進了安全指南裡。