【Bug已解决】Docker container cannot run claude / Docker environment issues — Claude Code Docker 环境问题解决方案

1. 问题描述

在 Docker 容器中运行 Claude Code 时出现各种环境问题：

# claude 命令找不到
$ docker run node:22 claude
docker: Error: exec: "claude": executable file not found in $PATH

# 安装后权限问题
$ docker run -it node:22 sh -c "npm install -g @anthropic-ai/claude-code && claude"
Error: EACCES: permission denied, access '/usr/local/lib/node_modules'

# API Key 未传入
$ docker run node:22 claude
Error: ANTHROPIC_API_KEY not set. Please set your API key.

# 文件权限问题
$ docker run -v $(pwd):/app node:22 claude
Error: EACCES: permission denied, open '/app/src/index.js'

这个问题在以下场景中特别常见：

• Dockerfile 中未安装 Claude Code
• API Key 未通过环境变量传入容器
• 容器内用户与宿主机文件权限不匹配
• Node.js 版本不够（需要 18+）
• 容器内缺少 bash/git 等依赖
• volume 挂载权限问题

2. 原因分析

核心原理拆解

Docker 容器 → 独立环境
        ↓
Claude Code 未安装 / API Key 未传入 / 权限不匹配
        ↓
各种环境错误

原因分类表

原因分类	具体表现	占比
未安装 Claude Code	claude 命令不存在	约 35%
API Key 未传入	环境变量未设置	约 25%
文件权限	UID 不匹配	约 20%
Node 版本	node:16 镜像	约 10%
缺少依赖	无 bash/git	约 5%
网络问题	容器网络限制	约 5%

3. 解决方案

方案一：使用正确的 Dockerfile（最推荐）

# Dockerfile
FROM node:22-slim

# 安装必要依赖
RUN apt-get update && apt-get install -y git bash && rm -rf /var/lib/apt/lists/*

# 安装 Claude Code
RUN npm install -g @anthropic-ai/claude-code

# 创建非 root 用户
RUN useradd -m -u 1000 claude-user
USER claude-user
WORKDIR /app

# 验证安装
RUN claude --version

# 入口
ENTRYPOINT ["claude"]

# 构建
docker build -t claude-env .

# 运行
docker run -it --rm \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  -v $(pwd):/app \
  claude-env

方案二：使用 docker run 直接运行

# 步骤 1：直接在 node:22 镜像中运行
docker run -it --rm \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  -v $(pwd):/app \
  -w /app \
  node:22 \
  sh -c "npm install -g @anthropic-ai/claude-code && claude"

# 步骤 2：解决权限问题（使用宿主机 UID）
docker run -it --rm \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  -v $(pwd):/app \
  -w /app \
  --user $(id -u):$(id -g) \
  node:22 \
  sh -c "npm install -g @anthropic-ai/claude-code 2>/dev/null; claude"

方案三：解决文件权限问题

# 步骤 1：使用宿主机 UID 运行容器
docker run -it --rm \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  -v $(pwd):/app \
  -w /app \
  --user $(id -u):$(id -g) \
  node:22 \
  claude

# 步骤 2：或在 Dockerfile 中设置 UID
FROM node:22-slim
RUN useradd -m -u $(id -u) appuser
# 但 UID 在构建时是固定的，运行时传入更好

# 步骤 3：或修改文件权限
chmod -R 777 .
# 不推荐，但快速解决

方案四：传入所有必要环境变量

# 步骤 1：传入所有 Claude Code 需要的变量
docker run -it --rm \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  -e ANTHROPIC_MODEL=$ANTHROPIC_MODEL \
  -e CLAUDE_CODE_MAX_OUTPUT_TOKENS=16000 \
  -e NODE_OPTIONS="--max-old-space-size=4096" \
  -v $(pwd):/app \
  -w /app \
  claude-env

# 步骤 2：或使用 --env-file
cat > .env.docker << 'EOF'
ANTHROPIC_API_KEY=sk-ant-api03-xxx
ANTHROPIC_MODEL=claude-sonnet-4-20250514
NODE_OPTIONS=--max-old-space-size=4096
EOF

docker run -it --rm --env-file .env.docker -v $(pwd):/app claude-env

方案五：安装缺失的系统依赖

# 步骤 1：某些 MCP 工具需要额外依赖
# 如 Playwright 需要 chromium
FROM node:22-slim

# 安装 Playwright 依赖
RUN apt-get update && apt-get install -y \
    git bash \
    libnss3 libatk1.0-0 libatk-bridge2.0-0 \
    libcups2 libdrm2 libxkbcommon0 libxcomposite1 \
    libxdamage1 libxfixes3 libxrandr2 libgbm1 \
    libpango-1.0-0 libcairo2 libasound2 \
    && rm -rf /var/lib/apt/lists/*

# 安装 Claude Code 和 Playwright
RUN npm install -g @anthropic-ai/claude-code
RUN npx playwright install chromium --with-deps

# 步骤 2：验证
RUN claude --version

方案六：使用 Docker Compose

# docker-compose.yml
version: '3.8'
services:
  claude:
    build: .
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - ANTHROPIC_MODEL=claude-sonnet-4-20250514
      - NODE_OPTIONS=--max-old-space-size=4096
    volumes:
      - ./:/app
      - claude-data:/home/claude-user/.claude
    working_dir: /app
    stdin_open: true
    tty: true

volumes:
  claude-data:

# 运行
docker compose run --rm claude

4. 各方案对比总结

方案	适用场景	推荐指数	难度
方案一：Dockerfile	长期使用	⭐⭐⭐⭐⭐	中
方案二：docker run	临时使用	⭐⭐⭐⭐	低
方案三：权限修复	UID 不匹配	⭐⭐⭐⭐⭐	低
方案四：环境变量	配置传入	⭐⭐⭐⭐⭐	低
方案五：系统依赖	MCP 工具	⭐⭐⭐⭐	中
方案六：Docker Compose	复杂配置	⭐⭐⭐⭐⭐	中

5. 常见问题 FAQ

5.1 为什么容器中找不到 claude

Docker 镜像中未安装 Claude Code。需要在 Dockerfile 中 RUN npm install -g @anthropic-ai/claude-code 或运行时安装。

5.2 容器内文件权限不匹配

容器内默认 root 用户（UID 0），宿主机文件可能是其他 UID。使用 --user $(id -u):$(id -g) 运行容器。

5.3 如何持久化 Claude Code 配置

挂载 volume 持久化 ~/.claude/ 目录：

docker run -v claude-config:/home/user/.claude claude-env

5.4 容器中如何解决 DNS 解析失败

容器默认使用 Docker 内置 DNS，可能与企业内网 DNS 不兼容。在 docker run 时指定 DNS：

docker run --dns 10.0.0.1 --dns 8.8.8.8 \
           -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
           claude-env

或在 Docker Compose 中配置：

services:
  claude:
    dns:
      - 10.0.0.1
      - 8.8.8.8

也可以在 Dockerfile 中写入自定义 /etc/resolv.conf：

RUN echo "nameserver 10.0.0.1" > /etc/resolv.conf

5.5 node:alpine 可以用吗

可以，但可能缺少依赖。推荐 node:22-slim（基于 Debian），兼容性更好。

5.6 Docker 中 Claude Code 能交互吗

可以。使用 -it 参数：

docker run -it claude-env

5.7 CI/CD 中使用 Docker 运行 Claude Code

- run: |
    docker run --rm \
      -e ANTHROPIC_API_KEY=${{ secrets.ANTHROPIC_API_KEY }} \
      -v $(pwd):/app -w /app \
      claude-env \
      claude --print "修复测试" --auto --max-turns 10

5.8 容器中 Claude Code 版本如何更新

重建 Docker 镜像：

docker build --no-cache -t claude-env .

5.9 多容器共享 Claude Code 配置

使用 named volume 共享配置：

docker volume create claude-config
# 多个容器挂载同一 volume
docker run -v claude-config:/root/.claude claude-env

5.10 排查清单速查表

□ 1. Dockerfile: FROM node:22-slim
□ 2. RUN npm install -g @anthropic-ai/claude-code
□ 3. -e ANTHROPIC_API_KEY 传入 Key
□ 4. --user $(id -u):$(id -g) 修复权限
□ 5. -v $(pwd):/app 挂载项目
□ 6. -it 交互模式运行
□ 7. 安装必要系统依赖（git/bash）
□ 8. Playwright: npx playwright install --with-deps
□ 9. --env-file 管理多个环境变量
□ 10. Docker Compose 管理复杂配置

6. 总结

1. 根本原因：Docker 环境问题最常见原因是未在镜像中安装 Claude Code（35%）和 API Key 未传入容器（25%）
2. 最佳实践：创建专用 Dockerfile（FROM node:22-slim + npm install -g @anthropic-ai/claude-code），确保环境一致
3. 权限修复：使用 --user $(id -u):$(id -g) 运行容器，匹配宿主机文件权限
4. 环境变量：通过 -e 或 --env-file 传入 ANTHROPIC_API_KEY、ANTHROPIC_MODEL、NODE_OPTIONS 等
5. 最佳实践建议：使用 Docker Compose 管理 Claude Code 容器——通过 volume 持久化 ~/.claude/ 配置，通过 .env 文件管理 API Key，简化运行命令

故障排查流程图

flowchart TD
    A[Docker 中 claude 失败] --> B{claude 命令存在?}
    B -->|否| C[npm install -g 安装]
    B -->|是| D{API Key 设置?}
    C --> E[创建 Dockerfile]
    E --> F[docker build]
    F --> G[docker run -e API_KEY]
    D -->|否| H[-e ANTHROPIC_API_KEY 传入]
    D -->|是| I{文件权限正确?}
    H --> I
    G --> I
    I -->|否| J[--user UID:GID]
    I -->|是| K{Node >= 18?}
    J --> K
    K -->|否| L[使用 node:22-slim]
    K -->|是| M{缺少依赖?}
    L --> N[重建镜像]
    N --> O[docker run -it claude-env]
    M -->|是| P[apt-get install git bash]
    M -->|否| O
    P --> O
    O --> Q{运行成功?}
    Q -->|是| R[✅ 问题解决]
    Q -->|否| S[检查网络/DNS 设置]
    S --> T[--dns 指定 DNS 服务器]
    T --> O