Claude Code 跨平台安装与配置指南（Windows/Linux/macOS）

配置完成后重启终端，切换到项目目录启动：

cd /mnt/d/workspace/project
claude

3. Docker 容器化安装

适合希望隔离环境的开发者。

安装 Docker Desktop

下载并安装 Docker Desktop，安装时勾选'Use WSL 2 based engine'。

配置镜像源

编辑 Docker Engine 配置，添加国内镜像加速：

{
  "builder": {"gc": {"defaultKeepStorage": "20GB", "enabled": true}},
  "dns": ["8.8.8.8", "8.8.4.4"],
  "registry-mirrors": ["https://docker.mirrors.ustc.edu.cn"]
}

集成 WSL

在 Docker Desktop 设置中，找到 Resources -> WSL integration，勾选启用默认 WSL 发行版集成。

构建开发镜像

创建目录并编写 Dockerfile：

FROM ubuntu:22.04
ENV DEBIAN_FRONTEND=noninteractive
RUN sed -i 's|http://.*.ubuntu.com|http://mirrors.aliyun.com|g' /etc/apt/sources.list && \
    sed -i 's|http://security.ubuntu.com|http://mirrors.aliyun.com|g' /etc/apt/sources.list
RUN apt-get update && apt-get install -y --no-install-recommends \
    ca-certificates build-essential git curl vim python3 python3-pip nodejs npm \
    --fix-missing -o Acquire::Retries=3 && rm -rf /var/lib/apt/lists/*
ARG USERNAME=dev
ARG UID=1000
RUN useradd -m -u ${UID} -s /bin/bash ${USERNAME} && \
    apt-get update && apt-get install -y sudo && \
    echo "${USERNAME} ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers && \
    rm -rf /var/lib/apt/lists/*
USER ${USERNAME}
WORKDIR /workspace
CMD ["bash"]

构建镜像：

docker pull ubuntu:22.04
docker build -t claude-env .

启动容器

挂载本地代码目录到容器内：

docker run -it --name claude-code \
-v D:/Tools/Docker/ClaudeCode/Code:/workspace/project \
claude-env

进入容器后重复上述 WSL 安装步骤即可。

Linux 环境安装

原生支持 Ubuntu 18.04+、CentOS 7+、Debian 10+ 等系统。

1. 执行环境检查脚本：

curl -fsSL https://download.aicodemirror.com/env_deploy/env-install.sh | bash

2. 安装官方包：

npm uninstall -g @anthropic-ai/claude-code
npm install -g @anthropic-ai/claude-code

3. 配置环境变量：

sudo apt-get install jq curl -fsSL https://download.aicodemirror.com/env_deploy/env-deploy.sh | bash -s -- "你的 API_KEY"

4. 切换项目目录启动：

cd workspace/project
claude

macOS 环境安装

支持 macOS 10.15+ 系统。

1. 执行环境检查脚本：

curl -fsSL https://download.aicodemirror.com/env_deploy/env-install.sh | bash

2. 安装官方包：

npm uninstall -g @anthropic-ai/claude-code
npm install -g @anthropic-ai/claude-code

3. 配置环境变量：

sudo apt-get install jq curl -fsSL https://download.aicodemirror.com/env_deploy/env-deploy.sh | bash -s -- "你的 API_KEY"

4. 切换项目目录启动：

cd workspace/project
claude

常见问题排查

1. 之前安装过其他版本

请先全局卸载，避免冲突：

npm uninstall -g @anthropic-ai/claude-code

Windows 下若失败，请使用管理员权限运行命令行。

2. 卸载残留导致 API Error

通常由环境变量未清理干净引起：

• Mac：检查根目录下隐藏文件 .zshrc，删除相关的镜像环境变量配置行。
• Windows：删除用户路径下的 .claude 文件夹。
• Linux：执行 rm ~/.claude 后重启终端。

3. claude -v 报错

如果运行版本检查出现 JS 报错，大概率是 Node 版本过低。虽然网传 18 版本可用，但实测建议升级至 20+ 版本：

nvm install 20
nvm use 20

再次运行 claude -v 确认版本号显示正常。

4. 其他问题

如遇特殊错误，建议查阅官方文档或社区最新解决方案，重点关注 Node 环境及网络代理配置。