Claude Code 安装配置指南（Windows + 国内第三方 API）

适用场景：Windows 系统，无法直接访问 Anthropic 官方服务，通过硅基流动（SiliconFlow）等国内兼容 API 接入 Claude Code。

版本参考：Claude Code v2.1.138 / Node.js v24.x / npm v11.x

---

目录

1. 前置环境准备
2. 修改 npm 全局安装目录（避免权限问题）
3. 安装 Claude Code
4. 修复 Git Bash 启动脚本
5. 配置 PATH 环境变量
6. 配置第三方 API（硅基流动）
7. 跳过官方登录验证
8. VS Code 插件配置
9. 验证安装是否成功
10. 常见问题排查

---

1. 前置环境准备

必须安装

工具	推荐版本	下载地址
Node.js	v18+ （推荐 v20 / v24）	https://nodejs.org
Git（含 Git Bash）	最新版	https://git-scm.com
VS Code	最新版	https://code.visualstudio.com

验证环境

打开 Git Bash 执行：

node --version    # 应输出 v18.x 或以上
npm --version     # 应输出 9.x 或以上
git --version     # 应输出 git version 2.x

---

2. 修改 npm 全局安装目录（避免权限问题）

Windows 下 npm 默认全局目录（C:\Users\用户名\AppData\Roaming\npm）有时会遇到权限问题，建议改到用户自定义目录。

步骤

# 创建新的全局目录（路径中不要有中文或空格）
mkdir -p "$HOME/AppData/Roaming/npm-global"

# 设置 npm 全局路径
npm config set prefix "$HOME/AppData/Roaming/npm-global"

# 验证设置是否生效
npm config get prefix
# 预期输出：C:\Users\你的用户名\AppData\Roaming\npm-global

---

3. 安装 Claude Code

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

# 安装完成后验证（此时可能还无法运行，需先配置 PATH，见下一节）
ls "$HOME/AppData/Roaming/npm-global/"
# 应能看到 claude 和 claude.cmd 文件

注意：安装时如提示 EACCES 权限错误，确认上一步 prefix 目录设置正确。

---

4. 修复 Git Bash 启动脚本

Windows 下 npm 生成的 shell 脚本有时无法在 Git Bash 中正确解析路径，需要手动修复。

找到脚本位置

ls "$HOME/AppData/Roaming/npm-global/claude"

查看脚本内容

cat "$HOME/AppData/Roaming/npm-global/claude"

如果内容类似这样（有问题的版本）：

#!/bin/sh
basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
# ... 复杂的路径查找逻辑 ...
exec node "$basedir/../..."

替换为硬编码绝对路径（可靠版本）：

cat > "$HOME/AppData/Roaming/npm-global/claude" << 'EOF'
#!/bin/sh
exec "C:/Users/你的用户名/AppData/Roaming/npm-global/node_modules/@anthropic-ai/claude-code/bin/claude.exe" "$@"
EOF

⚠️ 将 你的用户名 替换为你的实际 Windows 用户名（与 $HOME 对应的目录名）。

验证修复后脚本内容：

cat "$HOME/AppData/Roaming/npm-global/claude"
# 应输出一行 exec ... claude.exe "$@"

---

5. 配置 PATH 环境变量

需要在两处配置，分别让 Git Bash 和 CMD/PowerShell 都能识别 claude 命令。

5.1 Git Bash（写入 ~/.bashrc）

echo 'export PATH="$HOME/AppData/Roaming/npm-global:$PATH"' >> ~/.bashrc
source ~/.bashrc

5.2 Windows 系统环境变量（CMD / PowerShell）

方法一：通过 PowerShell（永久生效）

# 在 PowerShell 中执行（不是 Git Bash）
[System.Environment]::SetEnvironmentVariable(
    "PATH",
    $env:PATH + ";C:\Users\你的用户名\AppData\Roaming\npm-global",
    "User"
)

方法二：通过图形界面

1. 右键「此电脑」→「属性」→「高级系统设置」→「环境变量」
2. 在「用户变量」中找到 Path，点击编辑
3. 新增一行：C:\Users\你的用户名\AppData\Roaming\npm-global
4. 点击确定，重新开启终端窗口生效

---

6. 配置第三方 API（硅基流动）

Claude Code 支持通过 ANTHROPIC_BASE_URL 环境变量接入兼容 Anthropic API 的第三方服务。

6.1 获取 API Key

1. 访问 硅基流动官网
2. 注册账号 → 进入「API Keys」→ 创建新的 Key
3. 复制 Key（格式：sk-xxxxxxxxx）

6.2 创建 Claude Code 配置文件

配置文件路径：C:\Users\你的用户名\.claude\settings.json

mkdir -p ~/.claude

创建 ~/.claude/settings.json，内容如下：

{
    "env": {
        "ANTHROPIC_API_KEY": "sk-你的API密钥",
        "ANTHROPIC_BASE_URL": "https://api.siliconflow.cn",
        "ANTHROPIC_MODEL": "Qwen/Qwen3-30B-A3B"
    },
    "effortLevel": "low"
}

关键字段说明

字段	说明
ANTHROPIC_API_KEY	硅基流动的 API Key（以 sk- 开头）
ANTHROPIC_BASE_URL	API 地址，末尾不要加斜杠 /
ANTHROPIC_MODEL	主模型名称，见下方模型参考
effortLevel	思考深度，low 节省 token，high 更准确

推荐模型配置（硅基流动可用）

用途	模型名称
主力模型（日常使用）	Qwen/Qwen3-30B-A3B
轻量快速（Haiku 替代）	Qwen/Qwen3-8B
高性能（Opus 替代）	Qwen/Qwen3-235B-A22B

也可以使用 DeepSeek 等其他支持 OpenAI 兼容格式的模型服务，将 ANTHROPIC_BASE_URL 替换为对应接口地址即可。

---

7. 跳过官方登录验证

Claude Code 首次启动时会要求登录 Anthropic 账号，使用第三方 API 时不需要此步骤，通过写入配置文件可跳过。

# 创建或编辑 ~/.claude.json
cat > ~/.claude.json << 'EOF'
{
  "hasCompletedOnboarding": true,
  "numStartups": 1
}
EOF

原理：Claude Code 通过 hasCompletedOnboarding: true 判断是否已完成引导，设置后不再弹出登录界面。

---

8. VS Code 插件配置

8.1 安装插件

1. 打开 VS Code
2. 按 Ctrl+Shift+X 打开插件市场
3. 搜索 Claude Code
4. 安装 Anthropic 官方发布的插件

8.2 禁用登录弹窗

打开 VS Code 设置文件：C:\Users\你的用户名\AppData\Roaming\Code\User\settings.json

添加以下配置：

{
    "claudeCode.disableLoginPrompt": true,
    "claudeCode.preferredLocation": "panel"
}

配置项	说明
claudeCode.disableLoginPrompt	禁止弹出 Anthropic 登录提示
claudeCode.preferredLocation	界面位置，panel 显示在底部面板，sidebar 显示在侧边栏

8.3 开启 PowerShell 执行策略（如需要）

如果 VS Code 终端报 PowerShell 脚本执行被禁止，需要修改执行策略：

# 在 PowerShell 中执行
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

---

9. 验证安装是否成功

命令行验证

# 重新加载 PATH（Git Bash）
source ~/.bashrc

# 查看版本号
claude --version
# 预期输出：2.1.x (Claude Code)

# 启动 Claude Code（交互模式）
claude

首次启动预期行为

• 不应该弹出 Anthropic 登录界面
• 应该直接进入命令行交互模式
• 输入一个简单问题（如 你好）验证 API 是否正常响应

VS Code 验证

1. 打开 VS Code，按 Ctrl+Shift+P 搜索 Claude Code
2. 点击「Open Claude Code」
3. 面板底部出现 Claude Code 界面，不再弹出登录提示

---

10. 常见问题排查

❌ claude: command not found

原因：PATH 未包含 npm 全局目录，或 .bashrc 未生效。

# 检查 npm 全局路径
npm config get prefix

# 手动添加到当前会话 PATH
export PATH="$HOME/AppData/Roaming/npm-global:$PATH"

# 验证
which claude
claude --version

---

❌ 安装时报 EACCES 权限错误

原因：npm 默认全局路径需要管理员权限。

解决：按照第 2 节，将 npm prefix 改到用户目录再重新安装。

---

❌ Claude Code 启动报 API key not found

原因：~/.claude/settings.json 中 API Key 配置有误，或文件路径不对。

# 检查配置文件
cat ~/.claude/settings.json

# 确认路径正确（Windows 用户名目录）
ls ~/.claude/

---

❌ 报错 Invalid URL 或 404

原因：ANTHROPIC_BASE_URL 末尾多了斜杠，或 URL 格式不正确。

正确格式：

"ANTHROPIC_BASE_URL": "https://api.siliconflow.cn"

错误格式（注意末尾斜杠）：

"ANTHROPIC_BASE_URL": "https://api.siliconflow.cn/"   ← 错误

---

❌ VS Code 持续弹出登录提示

原因：VS Code settings.json 缺少 claudeCode.disableLoginPrompt 配置。

解决：按照第 8.2 节添加该配置，重启 VS Code 生效。

---

❌ Git Bash 中 claude 能用，但 CMD/PowerShell 不行

原因：Windows 系统环境变量 PATH 未包含 npm 全局目录。

解决：按照第 5.2 节，通过 PowerShell 或图形界面将目录加入系统 PATH，然后重新开启终端窗口。

---

附录：完整配置文件示例

~/.claude/settings.json

{
    "env": {
        "ANTHROPIC_API_KEY": "sk-你的API密钥请替换这里",
        "ANTHROPIC_BASE_URL": "https://api.siliconflow.cn",
        "ANTHROPIC_MODEL": "Qwen/Qwen3-30B-A3B"
    },
    "effortLevel": "low"
}

~/.claude.json（跳过登录）

{
  "hasCompletedOnboarding": true,
  "numStartups": 1
}

VS Code settings.json 相关部分

{
    "claudeCode.disableLoginPrompt": true,
    "claudeCode.preferredLocation": "panel"
}

~/.bashrc 相关部分

export PATH="$HOME/AppData/Roaming/npm-global:$PATH"

---

文档生成日期：2026-05-11 | 适用版本：Claude Code v2.1.138