整合参考：

  • 阿里云开发者社区：Claude Code国内安装保姆教程
  • 知乎专栏：Claude Code 安装配置完整指南：Windows/Mac/Linux 全平台 + 国内 API 配置

适用场景：全平台安装、国内网络环境、第三方大模型接入、服务器无权限环境部署

一、概述

Claude Code 是 Anthropic 推出的命令行 AI 编程助手，可直接在终端中读取项目、修改代码、执行系统命令，支持自定义接入大模型 API。本教程覆盖 Windows/macOS/Linux 全平台安装方案，包含官方路径与国内网络适配方案，同时汇总常见报错与解决方案。

二、前置要求

2.1 系统要求

系统最低版本推荐配置
WindowsWindows 10Windows 11 + PowerShell 7 / WSL2
macOSmacOS 11.0macOS 12.0+ + Homebrew
LinuxUbuntu 20.04+Ubuntu 22.04+ / Debian 11+

2.2 软件依赖

  • Node.js：@anthropic-ai/claude-code@2.x 要求 Node.js ≥ 22.0.0，低版本会直接报 EBADENGINE 无法运行
  • npm：随 Node.js 一同安装
  • Git：可选，Windows 原生环境推荐安装

验证命令：

node --version
npm --version

三、分平台安装步骤

3.1 Windows 系统

方案A：WSL2 环境（强烈推荐）

与 Linux 体验一致，可规避 Windows 路径、权限与脚本执行限制。

  1. 管理员身份打开 PowerShell，执行安装：
wsl --install
  1. 重启电脑，打开 WSL 终端，后续步骤完全参照下方 Linux 章节。

方案B：原生 PowerShell 安装

  1. 安装 Node.js 22+：前往 Node.js 官网 下载 LTS 安装包，或使用 winget：
winget install OpenJS.NodeJS.LTS
  1. 全局安装 Claude Code：
npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com/
  1. 若遇到脚本执行权限报错，管理员运行 PowerShell 执行：
Set-ExecutionPolicy Unrestricted -Scope CurrentUser

3.2 macOS 系统

方案A：官方一键脚本（有海外网络）

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

安装完成后按提示将 ~/.local/bin 加入系统 PATH。

方案B：Homebrew 安装（国内网络推荐）

  1. 安装 Homebrew（已安装可跳过）：
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
  1. 安装 Node.js：
brew install node
  1. 安装 Claude Code：
npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com/

3.3 Linux / 远程服务器

重点适配共享集群、无 root 权限场景，使用 nvm 管理 Node 版本，规避系统目录权限报错。

Step 1：安装 nvm（用户级 Node 版本管理）

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

加载 nvm 到当前终端：

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

Step 2：安装 Node.js 22

nvm install 22
nvm use 22
nvm alias default 22

验证版本：

node -v
npm -v

Step 3：全局安装 Claude Code

# 国内网络可加镜像源
npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com/

Step 4：持久化配置

将 nvm 加载脚本写入 ~/.bashrc，避免 SSH 重连后 Node 版本回退：

cat >> ~/.bashrc <<'EOF'
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"
EOF
source ~/.bashrc

四、API 与模型配置

4.1 官方 Anthropic API 配置

方式1：环境变量配置

# 临时生效
export ANTHROPIC_API_KEY="sk-ant-你的API密钥"

# 永久生效，写入 ~/.bashrc
echo 'export ANTHROPIC_API_KEY="sk-ant-你的API密钥"' >> ~/.bashrc
source ~/.bashrc

方式2：配置文件方式

创建配置目录与文件：

mkdir -p ~/.claude

cat > ~/.claude/settings.json << 'EOF'
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-ant-你的API密钥",
    "ANTHROPIC_MODEL": "claude-3-7-sonnet-20250219"
  }
}
EOF

# 跳过官方登录引导，直接使用 API 密钥认证
cat > ~/.claude.json << 'EOF'
{
  "hasCompletedOnboarding": true
}
EOF

4.2 国内第三方 API 配置

支持接入阿里云百炼、硅基流动、智谱等兼容 Anthropic 格式的 API 服务，以阿里云百炼为例：

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "你的阿里云API密钥",
    "ANTHROPIC_BASE_URL": "https://coding.dashscope.aliyuncs.com/apps/anthropic",
    "ANTHROPIC_MODEL": "qwen3.5-plus"
  }
}

4.3 配置文件参数说明

配置项说明
ANTHROPIC_AUTH_TOKENAPI 访问密钥
ANTHROPIC_BASE_URLAPI 服务地址，官方可省略，第三方必须填写
ANTHROPIC_MODEL指定使用的模型名称
hasCompletedOnboarding跳过官方登录引导，直接使用密钥认证

4.4 图形化模型切换工具 cc-switch

适合需要频繁切换多个模型供应商的场景：

  1. macOS 安装：
brew tap farion1231/ccswitch
brew install --cask cc-switch
  1. Windows 直接从 GitHub Releases 下载安装包
  2. 打开工具后添加自定义供应商，填写 API URL 与密钥即可一键切换配置

五、验证与基础使用

5.1 验证安装

claude --version

5.2 启动交互会话

进入项目目录后启动：

cd /path/to/your/project
claude

首次启动会询问目录授权，输入 yes 确认即可进入对话界面。

5.3 常用启动参数

# 跳过目录权限确认（仅信任目录使用）
claude --dangerously-skip-permissions

# 指定模型启动
claude --model claude-3-7-sonnet-20250219

# 单次执行指令，不进入交互
claude -p "梳理当前项目的目录结构"

六、进阶优化配置

6.1 编写 CLAUDE.md 规则文件

CLAUDE.md 是 Claude Code 的行为规范文件，分为全局与项目级两种：

  • 全局规则：~/.claude/CLAUDE.md，所有项目生效
  • 项目规则：项目根目录 CLAUDE.md，仅当前项目生效

参考模板：

## 沟通规则
- 默认使用中文回复，代码、变量名使用英文
- 结论先行，再补充理由与实现细节
- 方案存在问题直接指出，不做无意义的附和

## 操作红线（必须先确认再执行）
- 删除文件、修改 git 历史
- 修改 .env、密钥等敏感配置
- 执行 git push、强制推送
- 安装全局依赖、修改系统配置

6.2 权限与安全配置

在交互界面内执行 /permissions 可配置命令白名单，将信任的命令（如 npm run lint、git commit）加入自动放行列表，减少重复确认。

6.3 适配第三方 API 常见报错修复

若遇到 thinking type should be enabled or disabled 报错，是因为新版 Claude Code 默认的自适应思考模式不被第三方 API 支持。

解决方式：在 settings.json 的 env 中添加：

"claude_code_disable_adaptive_thinking": "1"

保存后重启 Claude Code 即可。

七、常见问题汇总

Q1：npm 安装报 EBADENGINE Unsupported engine

原因：Node.js 版本低于 22.0.0，不满足最低依赖要求。

解决：使用 nvm 安装 Node 22+，切换版本后重新安装。

Q2：安装报 EACCES: permission denied

原因：使用系统 Node 时，全局安装需要写入系统目录，普通用户无权限。

解决：

  1. 优先使用 nvm 管理 Node，安装在用户家目录，无需 root 权限
  2. 不推荐使用 sudo npm install -g，易造成环境权限混乱

Q3：无法连接到 Anthropic 服务

排查方向：

  1. 确认 ~/.claude.json 中已配置 "hasCompletedOnboarding": true
  2. 国内网络确认已配置正确的 ANTHROPIC_BASE_URL 代理地址
  3. 检查网络连通性与 API 密钥有效性

Q4：API 返回 401 Invalid API key

解决：

  • 检查密钥是否完整复制，无多余空格或换行
  • 确认密钥对应平台与 API 地址匹配
  • 前往对应平台重新生成密钥

Q5：npm 下载速度慢、安装超时

解决：使用国内 npm 镜像源

# 全局设置淘宝镜像
npm config set registry https://registry.npmmirror.com/

# 单次安装指定镜像
npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com/

Q6：新开终端后 claude 命令不存在

原因：Node 或命令路径未加入系统 PATH。

解决：

  • nvm 环境：确认 ~/.bashrc 已写入 nvm 加载脚本
  • 手动安装：将 Node 的 bin 目录或 ~/.local/bin 加入 PATH 环境变量

八、更新与卸载

更新 Claude Code

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

完全卸载

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

# 如需清理配置文件
rm -rf ~/.claude
rm -f ~/.claude.json