梦开始的地方：Claude Code 在 Windows & DeepseekV4Pro上的国内环境安装与调试指南

用户28717638795202026-05-02 18:18

Windows 10 · DeepSeek V4 Pro API · Node.js 22 LTS · Claude Code CLI v2.x · CC-Switch v3.14.1 · 2026-04-30

一、这篇教程解决什么问题

一句话定位：在 Windows 上从零搭建 Node.js 环境，配置国内镜像源加速 npm，安装 Claude Code 并借助 CC-Switch + 手动配置文件实现跳过 Anthropic 官方 OAuth 登录验证，使用 DeepSeek V4 Pro API 直接启动。

阅读前提：

  • 使用 Windows 10 或 Windows 11 操作系统
  • 拥有可用的 DeepSeek API Key（在 platform.deepseek.com 注册并创建）
  • DeepSeek 账户余额 ≥ ¥1.00（V4-Pro 单次最低计费约 ¥0.98）
  • 有基本的命令行操作经验（PowerShell 或 CMD）

读完能得到什么：一个在国内网络环境下可正常启动的 Claude Code Cli，底层由 DeepSeek V4 Pro 驱动，无需访问 claude.ai。

二、环境准备

2.1 依赖清单

组件 最低版本 说明
nvm-windows 1.1.12+ Node.js 版本管理器
Node.js 18.0+（推荐 22 LTS） Claude Code 运行时
npm 10.x+ 随 Node.js 自带
CC-Switch v3.14.1+ 多模型切换桌面工具

2.2 逐条验证

powershell 复制代码 
nvm version          # 应输出 1.1.12 或更高
node --version       # 应输出 v22.x.x 或 v20.x.x
npm --version        # 应输出 10.x.x 或更高

如果缺少某个组件：

  • nvm-windows 安装则如下：前往 nvm-windows Releases，下载 nvm-setup.exe，双击安装，全部默认选项即可。

三、安装步骤

3.1 安装 nvm-windows

nvm-windows 是 Windows 上管理多版本 Node.js 的标准方案，相当于Python的conda，用于Node.js的版本隔离，开发环境隔离。由于本人存在Openclaw和claude code两个Agent，Openclaw的更新非常拉跨，所以使用Nvm进行版本管理。 Nvm按照安装包方式装完即用，不需要手动配环境变量。

前往 nvm-windows Releases，下载最新 nvm-setup.exe（如 nvm-setup-1.1.12.exe），双击安装。安装路径建议保持默认 C:\Users\用户名\AppData\Roaming\nvm。

装完后 重新打开一个 PowerShell 窗口（让 PATH 生效），验证：

powershell 复制代码 
nvm version

预期输出：

复制代码 
1.1.12

3.2 安装 Node.js 22 LTS

powershell 复制代码 
# 查看可安装的 LTS 版本列表
nvm list available

# 安装 Node.js 22 LTS
nvm install 22

# 切换到 22
nvm use 22

# 验证
node --version
npm --version

预期输出：

复制代码 
v22.14.0
10.9.2

如果 nvm list available 报错 "Could not retrieve..."，说明 nvm 无法访问 Node.js 官方分发地址。可以手动下载 Node.js 安装包后通过 nvm install 22 <本地路径> 安装，或者先配代理。

3.3 配置 npm 国内镜像源

npm 默认从 https://registry.npmjs.org 拉包，国内直连速度慢且容易超时。切换到 npmmirror（原淘宝镜像）即可解决。

powershell 复制代码 
# 设置镜像源
npm config set registry https://registry.npmmirror.com

# 验证
npm config get registry

预期输出：

arduino 复制代码 
https://registry.npmmirror.com

https://registry.npm.taobao.org 已于 2024 年停止服务，请使用新域名 https://registry.npmmirror.com。

（可选）同时建议配置几个常用二进制镜像，避免安装 Electron、node-sass 等包时卡住：

powershell 复制代码 
npm config set electron_mirror https://npmmirror.com/mirrors/electron/
npm config set sass_binary_site https://npmmirror.com/mirrors/node-sass/
npm config set phantomjs_cdnurl https://npmmirror.com/mirrors/phantomjs/

3.4 安装 Claude Code

镜像源配好后，直接全局安装：

powershell 复制代码 
npm install -g @anthropic-ai/claude-code

验证安装：

powershell 复制代码 
claude --version

预期输出：

复制代码 
v2.0.xx

如果提示 claude : 无法将"claude"项识别为 cmdlet...，说明 npm 全局 bin 目录不在 PATH 中，见 Debug #1。

3.5 安装 CC-Switch（Windows .msi 方式）

CC-Switch 是一个 GitHub 上 50K+ Star 的开源跨平台桌面应用，用于图形化管理 Claude Code、Codex、Gemini CLI 等多个 AI CLI 工具的模型供应商配置，内建 50+ Provider 预设。

下载安装：

  1. 打开 CC-Switch Releases 页面
  2. 找到最新版本（当前 v3.14.1），下载 CC-Switch-v3.14.1-Windows-x64.msi
  3. 双击 .msi → 下一步 → 同意协议 → 保持默认路径 → 安装
  4. 如遇 Windows SmartScreen 警告，点击"更多信息" → "仍要运行"
  5. 完成后勾选"启动 CC-Switch" → 完成

桌面出现 CC-Switch 窗口即表示安装成功。

3.6 手动配置 Claude Code 免登录（关键前置步骤）

Claude Code v2.0.65+ 强制要求完成初次引导（Onboarding），即便配置了第三方 API 也会被卡住。需要手动修改两个 JSON 文件来跳过引导并指定 DeepSeek API。

文件一 ：C:\Users\<用户名>\.claude.json

作用：标记已完成初次引导，跳过 OAuth 登录弹窗。

如果文件不存在，手动创建，写入以下内容：

json 复制代码 
{
  "hasCompletedOnboarding": true
}

如果文件已存在，确保 JSON 中包含 "hasCompletedOnboarding": true（不要删除已有的其他字段）。

文件二 ：C:\Users\<用户名>\.claude\settings.json

作用：指定 Claude Code 使用 DeepSeek V4 Pro 的 Anthropic 兼容端点。

json 复制代码 
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "sk-你的DeepSeek-API-Key",
    "ANTHROPIC_MODEL": "deepseek-v4-pro",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "deepseek-v4-pro",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek-v4-pro",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "deepseek-v4-flash",
    "ANTHROPIC_SMALL_FAST_MODEL": "deepseek-v4-flash",
    "CLAUDE_CODE_SUBAGENT_MODEL": "deepseek-v4-pro",
    "CLAUDE_CODE_EFFORT_LEVEL": "max",
    "API_TIMEOUT_MS": "3000000"
  },
  "model": "deepseek-v4-pro"
}
关键字段 值 说明
ANTHROPIC_BASE_URL https://api.deepseek.com/anthropic DeepSeek 的 Anthropic 兼容端点，末尾不要加 /v1 或斜杠
ANTHROPIC_AUTH_TOKEN sk-xxxx DeepSeek API Key，注意字段名是 AUTH_TOKEN 不是 API_KEY
ANTHROPIC_MODEL deepseek-v4-pro V4 Pro 旗舰模型，1.6T 参数，1M 上下文
ANTHROPIC_SMALL_FAST_MODEL deepseek-v4-flash V4 Flash 轻量模型，284B 参数，用于快速任务

⚠️ ANTHROPIC_AUTH_TOKEN 不是 ANTHROPIC_API_KEY 。DeepSeek 的 Anthropic 兼容端点校验的是 x-api-key header，但 Claude Code 通过 ANTHROPIC_AUTH_TOKEN 传递；DeepSeek 服务端做了映射，写错字段名会导致 401，见 Debug #5。

⚠️ DeepSeek 旧模型名 deepseek-chat / deepseek-reasoner 将于 2026-07-24 停用，务必使用 deepseek-v4-pro / deepseek-v4-flash。

3.7 在 CC-Switch 中配置 DeepSeek Provider（可选，与手动配置二选一）

如果你更习惯用 GUI 管理，CC-Switch 的配置会覆盖 settings.json 中的对应字段。两种方式效果等价------CC-Switch 本质上就是图形化的 settings.json 编辑器，所有数据存储在本地 SQLite，不上传。

  1. 打开 CC-Switch 桌面应用
  2. 点击主界面右上角 "+"（Add Provider）
  3. 在预设列表中选择 DeepSeek （Base URL 自动填充为 https://api.deepseek.com/anthropic）
  4. 填入你的 DeepSeek API Key
  5. 模型选择 deepseek-v4-pro
  6. 点击 Save ，然后在模型列表中点击 Enable 启用
  7. Claude Code 一行在 CC-Switch 界面中显示为绿色对勾即表示生效

两种方式的关系：CC-Switch 修改的也是 C:\Users\<用户名>\.claude\settings.json。如果你已经按 3.6 手动编辑好了，CC-Switch 启动后会自动识别已有配置。如果你两边都做了，以最后写入的为准。

3.8 启动与验证

所有配置完成后，在任意项目目录下直接启动 Claude Code：

powershell 复制代码 
claude

预期终端出现：

rust 复制代码 
  Claude Code v2.0.xx
  Anthropic's official CLI for Claude
  ------------------------------------
  > 输入 /help 查看可用命令，或直接输入问题开始对话

在 Claude Code 内确认当前模型：

shell 复制代码 
> /model

预期输出：

sql 复制代码 
Current model: deepseek-v4-pro

输入一个简单问题验证全链路：

markdown 复制代码 
> 你好，请简单介绍一下你自己

如果正常返回回复且 /model 显示 deepseek-v4-pro，说明全链路通了------Node.js 环境 → npm 镜像 → Claude Code → DeepSeek V4 Pro API 全线跑通。

四、Debug #1 --- claude 命令不可用（npm 全局 bin 不在 PATH）

报错日志

powershell 复制代码 
PS C:\Users\<用户名>> claude --version
claude : 无法将"claude"项识别为 cmdlet、函数、脚本文件或可运行程序的名称。

根因

npm 全局安装的可执行文件放在 C:\Users\<用户名>\AppData\Roaming\npm\ 目录下。nvm 管理的 Node.js 在切换版本时，PATH 环境变量中的 npm 全局 bin 路径可能不会被自动添加。Windows 的 PATH 配置分散在"系统变量"和"用户变量"两处，nvm 安装脚本只会更新用户变量中的 NVM_HOME 和 NVM_SYMLINK，不会主动追加 npm 全局 bin 路径。

一览对比表

对比维度 修复前 修复后
PATH 含 npm 全局 bin ❌ %APPDATA%\npm 不在 PATH ✅ 已追加
claude --version 无法将 claude 识别为 cmdlet v2.0.xx
其他全局包（nrm 等） 全部不可用 全部可用

代码修复

步骤一：确认 npm 全局 bin 的实际路径。

powershell 复制代码 
npm config get prefix

预期输出：

makefile 复制代码 
C:\Users\<用户名>\AppData\Roaming\npm

步骤二：将该路径追加到用户 PATH 环境变量。

powershell 复制代码 
[Environment]::SetEnvironmentVariable("Path", $env:Path + ";C:\Users\<用户名>\AppData\Roaming\npm", "User")

步骤三：重新打开 PowerShell，验证：

powershell 复制代码 
claude --version

验证

复制代码 
v2.0.xx

五、Debug #2 --- npm install 超时或速度极慢

报错日志

vbscript 复制代码 
npm error code ETIMEDOUT
npm error errno ETIMEDOUT
npm error network request to https://registry.npmjs.org/@anthropic-ai/claude-code failed
npm error network This is a problem related to network connectivity.

根因

npm 默认向 https://registry.npmjs.org 发起请求。该域名托管在境外 CDN，国内直连延迟高、丢包率大，大包下载经常在中间断连。Claude Code 的包体积约几十 MB，网络抖动下几乎必超时。

一览对比表

对比维度 修复前 修复后
npm registry https://registry.npmjs.org（境外默认） https://registry.npmmirror.com（国内 CDN）
安装 50MB 包耗时 3~10 分钟（或直接超时） 10~30 秒
超时概率 高（大包几乎必超时） 极低

代码修复

powershell 复制代码 
# 检查当前源
npm config get registry

# 如果不是 npmmirror，切换
npm config set registry https://registry.npmmirror.com

# 再次确认
npm config get registry

验证

powershell 复制代码 
npm install -g @anthropic-ai/claude-code

预期：30 秒内安装完成，无任何 timeout 或 network 错误。

六、Debug #3 --- Claude Code 提示 "Login required"（Onboarding 未跳过）

报错日志

arduino 复制代码 
Claude Code requires authentication.
Please run `claude login` or press Enter to open the login page in your browser.

After logging in via claude.ai, your session will be saved.

或者：

vbnet 复制代码 
Unable to connect to Anthropic services.
Please check your network connection and try again.

根因

Claude Code v2.0.65 引入强制 Onboarding 检查。启动时读取 ~/.claude.json 中的 hasCompletedOnboarding 字段------如果该字段缺失或为 false，CLI 会进入登录引导流程，忽略 settings.json 中已配置的第三方 API 环境变量。这是一个已知 Bug（GitHub Issues #4714、#13827），社区反馈最后正常版本为 v2.0.64。

一览对比表

对比维度 修复前 修复后
C:\Users\<用户名>\.claude.json 文件不存在，或缺少 hasCompletedOnboarding "hasCompletedOnboarding": true
启动行为 弹出 Login required → 阻塞 跳过引导，直接进入对话
settings.json 是否被读取 ❌ 被引导流程覆盖忽略 ✅ 正常读取 env 配置

代码修复

确认 C:\Users\<用户名>\.claude.json 存在且内容正确：

powershell 复制代码 
# 检查文件是否存在
Test-Path C:\Users\<用户名>\.claude.json

# 查看内容
Get-Content C:\Users\<用户名>\.claude.json

预期内容至少包含：

json 复制代码 
{
  "hasCompletedOnboarding": true
}

如果文件不存在或内容不对：

powershell 复制代码 
# 创建并写入
@"
{
  "hasCompletedOnboarding": true
}
"@ | Out-File -FilePath C:\Users\<用户名>\.claude.json -Encoding utf8

如果文件已存在且包含其他字段，用文本编辑器打开手动添加 "hasCompletedOnboarding": true 即可，不要覆盖已有的其他配置。

验证

重新执行 claude，应直接进入对话界面，不再出现 Login required。

七、Debug #4 --- API 调用返回 401 Unauthorized

报错日志

css 复制代码 
[ERROR] API request failed: 401 Unauthorized
  {"error":{"type":"authentication_error","message":"invalid x-api-key"}}

根因

Claude Code 通过 ANTHROPIC_AUTH_TOKEN 环境变量向 ANTHROPIC_BASE_URL 发送 x-api-key header。401 意味着服务端不认可这个 Key。常见原因有三个：

  1. 字段名写错 ：settings.json 里写成了 ANTHROPIC_API_KEY 而非 ANTHROPIC_AUTH_TOKEN------DeepSeek 的 Anthropic 兼容端点只认 ANTHROPIC_AUTH_TOKEN 传递的值
  2. API Key 无效：Key 拼写错误、已被撤销、或未在 DeepSeek 控制台勾选开通 V4-Pro 权限
  3. 账户余额不足：V4-Pro 单次最低计费约 ¥0.98，余额需 ≥ ¥1.00

一览对比表

对比维度 修复前 修复后
环境变量名 ANTHROPIC_API_KEY（不被 DeepSeek 端点识别） ANTHROPIC_AUTH_TOKEN（正确）
账户余额 可能不足 ¥1.00 ≥ ¥1.00
服务端返回 401 Unauthorized 200 OK

代码修复

步骤一 ：确认 C:\Users\<用户名>\.claude\settings.json 中的字段名正确：

json 复制代码 
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-你的DeepSeek-API-Key",
    "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic"
  }
}

⚠️ 是 ANTHROPIC_AUTH_TOKEN，不是 ANTHROPIC_API_KEY。

步骤二 ：前往 DeepSeek Platform → API Keys 确认：

  • Key 存在于API keys列表中
  • 账户余额 ≥ ¥1.00

步骤三：用 curl 直接测试连通性：

powershell 复制代码 
$headers = @{
    "x-api-key" = "sk-你的DeepSeek-API-Key"
    "anthropic-version" = "2023-06-01"
}
$body = @{
    model = "deepseek-v4-pro"
    max_tokens = 100
    messages = @(@{role = "user"; content = "Hello"})
} | ConvertTo-Json -Depth 3

Invoke-RestMethod -Uri "https://api.deepseek.com/anthropic/v1/messages" `
    -Method Post -Headers $headers -Body $body `
    -ContentType "application/json"

验证

应正常返回 AI 回复，不再出现 401 错误。Claude Code 启动后 /model 显示 deepseek-v4-pro。

八、日常维护

8.1 启停命令

powershell 复制代码 
# 启动 Claude Code
claude

# 退出
# 在 Claude Code 交互界面中输入
/exit

# 或 Ctrl+C

CC-Switch 是桌面应用，不需要每次手动启停。开机后它在系统托盘运行，Claude Code 启动时自动读取其配置。

8.2 版本更新

更新 Claude Code：

powershell 复制代码 
npm update -g @anthropic-ai/claude-code
claude --version

更新 CC-Switch：

CC-Switch 内建自动更新------收到更新提示后点击更新即可。也可以去 Releases 页面 下载最新 .msi 覆盖安装。

升级 Node.js：

powershell 复制代码 
nvm install 22     # 22.x 内的最新补丁版本
nvm use 22

8.3 切换模型

CC-Switch 的热切换功能允许不重启 Claude Code 就换模型。在 CC-Switch 中切换 Provider 后，Claude Code 终端内 /model 即可看到更新。

也可以直接在 Claude Code 中临时指定模型：

bash 复制代码 
/model deepseek-v4-flash

8.4 日志位置

Claude Code 日志：

makefile 复制代码 
C:\Users\<用户名>\.claude\logs\

关键搜索词：

powershell 复制代码 
# 错误
findstr "ERROR" C:\Users\<用户名>\.claude\logs\*.log

# API 请求
findstr "api.deepseek.com" C:\Users\<用户名>\.claude\logs\*.log

CC-Switch 日志：

CC-Switch 作为桌面应用，日志在应用内 Help → View Logs 查看。

九、速查卡

9.1 文件路径汇总

文件 绝对路径
nvm 安装根目录 C:\Users\<用户名>\AppData\Roaming\nvm\
Node.js（nvm 管理） C:\Users\<用户名>\AppData\Roaming\nvm\v22.x.x\
npm 全局 bin 目录 C:\Users\<用户名>\AppData\Roaming\npm\
npm 全局 node_modules C:\Users\<用户名>\AppData\Roaming\npm\node_modules\
npm 配置文件 C:\Users\<用户名>\.npmrc
Claude Code 可执行文件 C:\Users\<用户名>\AppData\Roaming\npm\claude.ps1
Claude Code 安装目录 C:\Users\<用户名>\AppData\Roaming\npm\node_modules\@anthropic-ai\claude-code\
Claude Code 登录跳过 C:\Users\<用户名>\.claude.json
Claude Code API 配置 C:\Users\<用户名>\.claude\settings.json
Claude Code 日志目录 C:\Users\<用户名>\.claude\logs\
CC-Switch 安装目录 C:\Program Files\CC-Switch\
CC-Switch 数据存储 C:\Users\<用户名>\AppData\Roaming\CC-Switch\

9.2 关键配置字段速查

配置项 所属文件 说明
hasCompletedOnboarding: true .claude.json 跳过 OAuth 登录引导
ANTHROPIC_BASE_URL .claude/settings.json → env DeepSeek 端点 https://api.deepseek.com/anthropic
ANTHROPIC_AUTH_TOKEN .claude/settings.json → env DeepSeek API Key（注意不是 API_KEY）
ANTHROPIC_MODEL .claude/settings.json → env 默认模型 deepseek-v4-pro

9.3 常见报错 → 解决方案

报错 解决
claude 无法识别为 cmdlet Debug #1：追加 npm 全局 bin 到 PATH
npm install ETIMEDOUT Debug #2：切到 npmmirror 镜像源
Login required 弹窗 Debug #3：.claude.json 添加 hasCompletedOnboarding: true
API 401 Unauthorized Debug #4：检查字段名是 ANTHROPIC_AUTH_TOKEN、Key 有效、余额充足
node --version 输出旧版本 nvm use 22 切换到安装的版本
CC-Switch 切换模型后不生效 Claude Code 支持热切换，/model 确认；若不生效，重启终端
deepseek-v4-pro 模型不可用 在 DeepSeek Platform 控制台勾选开通 V4-Pro 权限
相关推荐
用户28717638795202 小时前
新手上路（三）：Claude Code Skills 装了一堆没用？20+ 个 Skill 横向对比 + 三套组合方案，按需抄
claude
雨中飘荡的记忆4 小时前
玩转Claude Code：这个开源项目让我生产力翻倍的秘诀
claude
Joseph Cooper5 小时前
AI Agent 落地入门：从模型、工具到 Skills 与 MCP 的分工
人工智能·ai·agent·claude·skill·mcp
javaTodo10 小时前
Codex CLI 深度指南：安装配置、安全模型与 20+ 高手技巧
claude
小蠢驴打代码10 小时前
我做了一个工具：一键同步 Claude Code、Cursor、Codex 的 MCP 和 Skills 配置
openai·claude·cursor
javaTodo10 小时前
国内使用Claude Code集成VS Codo小白一站式教程
claude
NikoAI编程10 小时前
用AI不等于AI First：国内企业 AI 编程落地的第一站，是混乱
aigc·ai编程·claude
一条小鲤鱼10 小时前
Claude Code 使用指南（一）
claude
Resistance丶未来12 小时前
Kimi K2.6 智能应用场景与落地指南
人工智能·gpt·大模型·api·claude·kimi·kimi k2.6
热门推荐
01要裂开了！ChatGPT要手机号验证了？注册Codex要求验证电话号码怎么办？2026年登陆Codex要手机号验证的解决办法02GitHub 镜像站点03裂开！ChatGPT 居然开始要手机号验证，附详细解决方法04【AI】2026 年具身智能模型和世界模型总结05Codex 接入 DeepSeek API 完整配置文档06零基础教你claude code 接入 deepseek V4072026年4月AI大事件深度解读：大模型竞争进入“深水区“08实测可用｜小米 MiMo 百万亿 Token 免费领，开发者速冲09在Windows 11上安装Docker的踩坑记录102026年AI前瞻：量子AI、具身智能与科学发现的新纪元