更推荐在 Dev Container 里使用 Claude Code：它运行在 Docker 容器中，Claude 执行的命令也在容器里跑，但你挂载进去的项目文件仍会同步显示在宿主机仓库中。官方也提供了 Dev Container Feature 方式安装 Claude Code。([Claude][1])

---

方案一：纯 Dockerfile 安装 Claude Code

1. 创建 Dockerfile

在你的项目根目录创建 Dockerfile.claude：

FROM ubuntu:20.04

ENV DEBIAN_FRONTEND=noninteractive

RUN apt-get update && apt-get install -y \
    curl \
    ca-certificates \
    git \
    bash \
    zsh \
    ripgrep \
    build-essential \
    sudo \
    && rm -rf /var/lib/apt/lists/*

# 创建非 root 用户，避免 Claude Code 在某些权限模式下拒绝运行
RUN useradd -m -s /bin/bash claude \
    && echo "claude ALL=(ALL) NOPASSWD:ALL" > /etc/sudoers.d/claude \
    && chmod 0440 /etc/sudoers.d/claude

USER claude
WORKDIR /workspace

# 安装 Claude Code
RUN curl -fsSL https://claude.ai/install.sh | bash

ENV PATH="/home/claude/.local/bin:${PATH}"

CMD ["/bin/bash"]

Claude 官方快速开始文档给出的 Linux/macOS/WSL 安装命令就是：

curl -fsSL https://claude.ai/install.sh | bash

并说明 native install 会自动后台更新。([Claude][2])

---

2. 构建镜像

在项目根目录执行：

docker build -f Dockerfile.claude -t claude-code:ubuntu20.04 .

---

3. 运行容器

推荐把当前项目挂载到 /workspace，再用一个 Docker volume 持久化 Claude 登录状态：

docker run --rm -it \
  -v "$PWD:/workspace" \
  -v claude-code-config:/home/claude/.claude \
  -w /workspace \
  claude-code:ubuntu20.04

进入容器后检查：

claude --version
claude doctor

然后启动：

claude

首次使用会要求登录。Claude Code 需要 Claude Pro、Max、Teams、Enterprise、Claude Console 账户，或企业云提供商访问权限。([Claude][2])

---

4. 登录方式

方式 A：浏览器 OAuth 登录

容器里执行：

claude

如果它给你登录链接，把链接复制到宿主机浏览器打开。登录完成后，如果回调没有自动进入容器，把浏览器显示的 code 复制回终端即可。Claude 官方 Dev Container 文档也说明了这种“复制 code 粘回终端”的情况。([Claude][1])

方式 B：用 API Key

不要把 key 写进 Dockerfile。推荐运行容器时传环境变量：

docker run --rm -it \
  -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
  -v "$PWD:/workspace" \
  -v claude-code-config:/home/claude/.claude \
  -w /workspace \
  claude-code:ubuntu20.04

先在宿主机设置：

export ANTHROPIC_API_KEY="你的_api_key"

Docker 官方 Claude Code sandbox 文档也说明 Claude Code 需要 Anthropic API key 或 Claude 订阅；也可以通过环境变量传入 ANTHROPIC_API_KEY。([Docker Documentation][3])

---

5. 基本使用

进入容器后，在 /workspace 下运行：

claude

常用提问：

这个项目做什么？先阅读代码，不要修改文件。

解释项目目录结构，告诉我主入口在哪里。

找出如何运行测试、如何启动开发环境。

让它改代码：

为用户列表接口增加分页参数 page 和 pageSize。
要求：
1. 保持向后兼容
2. 补充测试
3. 运行测试
4. 修改前先展示计划

Claude Code 会按需读取项目文件；你不需要手动把代码贴给它。官方 quickstart 也建议先让 Claude 分析项目、解释技术栈和目录结构。([Claude][2])

---

6. 推荐 Docker Compose 写法

如果你经常用，可以创建 docker-compose.claude.yml：

services:
  claude:
    build:
      context: .
      dockerfile: Dockerfile.claude
    working_dir: /workspace
    volumes:
      - .:/workspace
      - claude-code-config:/home/claude/.claude
    environment:
      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY:-}
    tty: true
    stdin_open: true

volumes:
  claude-code-config:

启动：

docker compose -f docker-compose.claude.yml run --rm claude

进入后：

claude

---

7. 持久化 Claude Code 配置

Claude Code 的登录凭证、用户设置、会话历史默认存储在：

~/.claude

容器里对应：

/home/claude/.claude

所以建议挂载：

-v claude-code-config:/home/claude/.claude

否则容器重建后可能需要重新登录。官方文档也说明，容器主目录重建后会被丢弃，而 Claude Code 的 auth token、设置和历史存储在 ~/.claude，可通过命名卷持久化。([Claude][1])

---

8. 为项目添加 CLAUDE.md

在项目根目录创建：

cat > CLAUDE.md <<'EOF'
# Claude Code Project Guide

## Tech stack
- Ubuntu 20.04 container
- Fill in your language/framework here

## Common commands
- Install dependencies: TODO
- Run tests: TODO
- Run lint: TODO
- Start dev server: TODO

## Rules
- Do not modify production secrets.
- Do not edit migrations unless explicitly requested.
- Before changing code, explain the plan.
- After changing code, run relevant tests.
EOF

然后在 Claude Code 里说：

请先阅读 CLAUDE.md，再分析这个项目。

---

9. 更官方的 Dev Container 方式

如果你用 VS Code、Cursor、JetBrains 或 GitHub Codespaces，更推荐用 .devcontainer/devcontainer.json。

创建：

mkdir -p .devcontainer

写入 .devcontainer/devcontainer.json：

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

官方文档给出的 Claude Code Dev Container Feature 配置就是：

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

它会把 Claude Code 安装到开发容器里；在 VS Code 或 Codespaces 中打开容器后，也会添加 Claude Code VS Code 扩展。([Claude][1])

---

10. 固定 Claude Code 版本

如果你想让团队构建结果可复现，不希望总是安装最新版，可以改用 npm 安装指定版本。

示例：

FROM node:20-bookworm

RUN apt-get update && apt-get install -y \
    git \
    ripgrep \
    build-essential \
    sudo \
    && rm -rf /var/lib/apt/lists/*

RUN useradd -m -s /bin/bash claude \
    && echo "claude ALL=(ALL) NOPASSWD:ALL" > /etc/sudoers.d/claude \
    && chmod 0440 /etc/sudoers.d/claude

USER claude
WORKDIR /workspace

ENV DISABLE_AUTOUPDATER=1

RUN npm install -g @anthropic-ai/claude-code@X.Y.Z

CMD ["/bin/bash"]

把 X.Y.Z 换成你要固定的版本。Claude 官方 Dev Container 文档说明，如果要固定特定 Claude Code 版本，可以在 Dockerfile 中使用 npm install -g @anthropic-ai/claude-code@X.Y.Z，并设置 DISABLE_AUTOUPDATER。([Claude][1])

---

11. 安全建议

不要这样写：

ENV ANTHROPIC_API_KEY=sk-ant-xxx

也不要轻易挂载这些目录：

-v ~/.ssh:/home/claude/.ssh
-v ~/.aws:/home/claude/.aws
-v ~/.config/gcloud:/home/claude/.config/gcloud

原因很简单：Claude Code 在容器里能访问你挂载进去的文件。官方 Dev Container 文档也提醒，避免挂载宿主机密钥，例如 ~/.ssh 或云凭证文件，优先使用仓库范围或短期 token。([Claude][1])

---

12. 常见问题

claude: command not found

进入容器后检查：

echo $PATH
ls -la /home/claude/.local/bin

临时修复：

export PATH="/home/claude/.local/bin:$PATH"

永久修复可在 Dockerfile 里保留：

ENV PATH="/home/claude/.local/bin:${PATH}"

每次都要重新登录

确认你运行容器时挂载了：

-v claude-code-config:/home/claude/.claude

容器里改代码，宿主机没变化

确认挂载了当前目录：

-v "$PWD:/workspace"
-w /workspace

Claude Code 修改的是容器里的 /workspace，这个目录需要和宿主机项目目录绑定。

可以用 --dangerously-skip-permissions 吗？

可以，但谨慎。官方说明，在容器以非 root 用户运行、命令执行限制在容器内时，可以传这个参数用于无人值守操作；但它会移除工具调用前的人工审查，Claude 仍可修改绑定挂载工作区中的文件。([Claude][1])

示例：

claude --dangerously-skip-permissions

更稳妥的日常用法是先让它计划：

先分析并给出修改计划，不要直接改代码。

---

推荐最终目录结构

your-project/
├── Dockerfile.claude
├── docker-compose.claude.yml
├── CLAUDE.md
├── src/
├── tests/
└── ...

日常启动：

docker compose -f docker-compose.claude.yml run --rm claude

进入容器后：

claude

然后先问：

请阅读 CLAUDE.md 和项目结构，总结这个项目如何启动、测试和构建。不要修改代码。

---

参考链接：
[1]: https://code.claude.com/docs/zh-CN/devcontainer “开发容器 - Claude Code Docs”
[2]: https://code.claude.com/docs/zh-CN/quickstart “快速开始 - Claude Code Docs”
[3]: https://docs.docker.com/ai/sandboxes/agents/claude-code/ “Claude Code | Docker Docs”