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

Claude Code 跨平台安装与配置指南

Claude Code 是一款强大的 AI 编码助手，支持在主流操作系统上本地运行。本文将详细介绍如何在 Windows、Linux 和 macOS 环境下完成部署，涵盖原生安装、WSL 子系统以及 Docker 容器化方案。

环境准备

在开始之前，请确保满足以下基础条件：

1. Node.js 环境：推荐 Node.js 20+ 版本。旧版本（如 18）可能存在兼容性问题。
2. 包管理器：系统需已安装 npm。
3. 账号权限：需要获取有效的 API 密钥以调用服务。

检查环境是否就绪：

node -v
npm -v

如果未安装 Node.js，建议通过 nvm 进行版本管理。

Windows 环境安装

方案一：原生终端安装

直接在 PowerShell 或 CMD 中操作即可。

1. 全局安装

   若已存在旧版本，先卸载：

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

   安装官方包：

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

2. 配置环境变量

   在系统环境变量中添加以下配置：

   • ANTHROPIC_BASE_URL：API 地址
   • ANTHROPIC_API_KEY：你的 API 密钥
   • ANTHROPIC_AUTH_TOKEN：认证令牌

3. 验证安装

   重启终端后运行：

   claude -v
   

   若显示版本号，说明安装成功。

方案二：WSL 子系统安装

对于习惯 Linux 环境的开发者，使用 WSL 2 是更稳定的选择。

1. 启用 WSL

   管理员模式下执行：

   dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
   dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
   

   重启电脑后，设置默认版本为 WSL 2：

   wsl --set-default-version 2
   

   若未安装发行版，可直接运行 wsl --install。

2. 安装与配置

   进入 WSL 终端，执行环境初始化脚本：

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

   随后安装核心包并配置密钥：

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

方案三：Docker 容器化安装

隔离环境可避免依赖冲突，适合生产或复杂项目。

1. 构建镜像

   创建 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}
   USER ${USERNAME}
   WORKDIR /workspace
   CMD ["bash"]
   

   构建镜像：

   docker build -t claude-env .
   

2. 启动容器

   挂载本地目录以便共享代码：

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

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

Linux 环境安装

Linux 原生支持良好，主要基于 Ubuntu 18.04+、CentOS 7+ 等发行版。

1. 一键安装

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

2. 安装核心包

   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"
   

macOS 环境安装

macOS 10.15+ 系统同样支持直接安装。

1. 安装命令

   curl -fsSL https://download.aicodemirror.com/env_deploy/env-install.sh | bash
   npm install -g @anthropic-ai/claude-code
   

2. 环境变量配置 参考 Linux 部分，将 API Key 写入环境变量脚本。

常见问题排查

1. 版本冲突 如果之前安装过其他版本，务必先全局卸载：

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

Windows 用户请尝试以管理员身份运行命令行。

2. API Error 通常由残留的环境变量引起。

• Mac：检查 ~/.zshrc 中是否有旧的镜像配置，删除相关行。
• Windows：清理用户路径下的 .claude 文件。
• Linux：执行 rm ~/.claude 后重启终端。

3. 命令报错 运行 claude -v 出现 JS 报错时，大概率是 Node 版本过低。请升级至 Node.js 20+ 版本。

4. 无法连接 若遇到网络问题，请检查代理设置或访问官方文档获取最新安装指引。

结语

完成上述步骤后，即可在项目目录下启动 Claude Code 进行辅助开发。输入指令回车，AI 将自动编排任务并执行操作。如果遇到特定环境问题，建议查阅官方社区的最新动态。