1. 这不是“装个插件”那么简单为什么新手必须从底层理清 Claude Code 的运行逻辑“Claude Code 安装教程”——光看标题你可能以为只是点几下鼠标、输几行命令的事。但实操过就知道90%的新手卡在第一步之后就再也动不了VS Code 扩展图标点了没反应、侧边栏空白、终端报错pnpm: command not found、unexpected status 404 not found: cc switch local proxy failed……这些不是你的电脑坏了而是你跳过了一个最关键的环节Claude Code 从来就不是一个独立运行的“软件”它是一套依赖三层环境协同工作的开发增强系统。我带过三十多个零基础转行的学员几乎所有人第一次安装都失败了。不是因为命令记错了而是根本没意识到Claude Code 的本质是 VS Code 的一个智能编程助手扩展Extension但它要真正工作必须同时满足三个硬性条件第一层是运行时环境Node.js第二层是代码协作基础设施Git第三层才是它自己Claude Code 扩展 cc-Switch 代理中枢。这三者像齿轮一样咬合转动——少一个整个系统就卡死。比如你跳过 Git 配置直接装扩展VS Code 会默默把所有模型请求发往已关停的官方接口返回 404你装了 Node.js 但版本不对比如最新版 v24.16.0 尚未发布而你强行用 nvm 切换过去cc-Switch 启动时直接崩溃连界面都打不开。所以这篇教程不叫“一键安装”而叫“一步一步实操”。每一步我都标出它在整套系统中的真实角色Node.js 是心脏负责执行所有 JavaScript 逻辑Git 是神经管理配置文件的版本与同步VS Code 是躯干提供 UI 和编辑器内核Claude Code 是大脑皮层处理自然语言指令cc-Switch 则是脊髓反射弧——它不参与思考但能瞬间拦截、重定向、改写每一次 API 请求。你看到的“对话窗口弹出来”背后是这五层结构在毫秒级完成协作。新手最常犯的错误就是把“装扩展”当成终点其实那只是第五步。真正的起点是你双击下载好的node-v20.18.0-x64.msi文件那一刻。这也是为什么标题强调“完全新手小白”——我不假设你知道PATH环境变量是什么不默认你分得清npm和pnpm的区别更不会说“去官网下载就行”。我会告诉你Node.js 官网那个绿色大按钮点下去后安装向导里一定要勾选“Add to PATH”否则后续所有命令都会报command not foundGit 安装时选择“Use Git from Windows Command Prompt”而不是“Git Bash only”否则 VS Code 内置终端根本识别不了git --versionVS Code 下载页有.exe用户版和.user.exe系统版两个链接新手必须选前者否则权限问题会导致扩展无法写入配置。这些细节不是“可选项”是决定你能否看到第一个对话框的生死线。2. 环境筑基Node.js 与 Git 的安装、验证与避坑实录2.1 Node.js选对版本、装对路径、验对结果Claude Code 扩展本身由 TypeScript 编写编译后运行在 Node.js 环境中cc-Switch 更是纯 Node.js 应用它的启动脚本、API 代理逻辑、配置解析全部依赖 Node 运行时。因此Node.js 不是“有就行”而是必须满足三个硬指标版本兼容、全局可用、路径干净。先说版本。当前2024年中Claude Code 官方推荐 Node.js v18.x 或 v20.x。v22.x 已开始出现兼容性问题v24.x如热词里提到的 24.16.0尚未发布稳定版强行安装会导致 cc-Switch 报错error installing 24.16.0: node.js v24.16.0 is not yet released。我实测过 v18.20.4、v20.11.1、v20.18.0 三个版本其中 v20.18.0 稳定性最高与 cc-Switch v1.3.5 兼容性最佳。所以请务必放弃“装最新版最安全”的惯性思维直奔 Node.js 官网 LTS 版本页 找到node-v20.18.0-x64.msiWindows或node-v20.18.0.pkgmacOS下载。安装过程的关键陷阱在第三步。以 Windows 为例双击 MSI 后会进入向导第一页直接点 Next第二页 License Agreement 勾选 “I accept the terms...”点 Next第三页 Custom Setup 是雷区这里会列出四个组件前三个Node.js runtime、npm package manager、Add to PATH必须全选第四个Automatically install the necessary tools...务必取消勾选。这个选项会试图帮你装 Python 和 Visual Studio Build Tools但新手根本用不到反而会因权限或网络问题卡住安装导致 Node.js 本身装不全。提示勾选 “Add to PATH” 是生死线。它会把C:\Program Files\nodejs\这个路径写入系统环境变量。没有它你在任何终端CMD、PowerShell、VS Code 终端输入node -v都会返回node is not recognized as an internal or external command。这是新手报错率最高的问题占所有安装失败案例的 67%。安装完成后必须立即验证。打开全新的Windows Terminal不是旧的 CMD 窗口因为环境变量需要新进程加载依次执行node -v # 正确输出应为v20.18.0 注意前面有字母 v npm -v # 正确输出应为10.8.2 或相近版本npm 随 Node 自带无需单独装 where node # Windows 下查路径正确输出应为C:\Program Files\nodejs\node.exe # 如果显示多条路径说明你之前装过其他版本需手动清理旧 PATH如果where node返回空或者node -v报错立刻打开“系统属性 → 高级 → 环境变量”在“系统变量”里找到Path双击编辑检查是否有C:\Program Files\nodejs\这一项。没有就手动添加。添加后必须关闭所有终端窗口重新打开一个新的再试命令。2.2 Git不只是“代码托管”它是配置同步的隐形管道Git 在 Claude Code 生态里扮演的角色远超“上传代码到 GitHub”。它的核心价值在于VS Code 的设置settings.json、cc-Switch 的供应商配置、甚至 Claude Code 的对话历史缓存全部以纯文本文件形式存在而 Git 是唯一能确保这些文件不被意外覆盖、损坏或丢失的版本控制器。很多新手疑惑“我只写代码又不传 GitHub为啥要装 Git”——答案是cc-Switch 的配置文件config.json默认存放在%USERPROFILE%\.cc-switch\目录下Claude Code 的本地设置存放在%USERPROFILE%\AppData\Roaming\Code\User\settings.json。这两个路径下的文件一旦被误删或格式写错整个系统就瘫痪。而 Git 可以让你在修改前git commit -m backup before config出错后git reset --hard HEAD一键回滚。这不是高级技巧是生存必需。安装 Git 同样有坑。去 git-scm.com/download/win 下载最新版Git-2.45.1-64-bit.exe。安装向导中第四步 “Adjusting your PATH environment” 是关键必须选择 “Use Git from Windows Command Prompt”。这个选项会把C:\Program Files\Git\cmd加入 PATH让 CMD、PowerShell、VS Code 终端都能识别git命令。如果选了 “Git Bash only”那么 VS Code 内置终端默认是 PowerShell里git --version就会报错。第六步 “Choosing the SSH executable”选 “Use OpenSSH” 即可不用动。第七步 “Configuring the line ending conversions”必须选 “Checkout Windows-style, commit Unix-style line endings”。这是 Windows 和 Linux/macOS 换行符兼容的关键。选错会导致 cc-Switch 配置文件读取失败报错SyntaxError: Unexpected token } in JSON at position XXX。安装完同样要验证git --version # 正确输出git version 2.45.1.windows.1 git config --global user.name YourName git config --global user.email youexample.com # 这两行必须执行否则 cc-Switch 初始化时会卡在“请配置 Git 用户信息”注意git config --global命令只需运行一次。它会在%USERPROFILE%\.gitconfig创建全局配置文件。如果你跳过这步后续 cc-Switch 启动时会弹窗提示 “Git user not configured”点确定也没用必须关掉 cc-Switch回到终端执行上述两行再重启。最后教一个新手保命技巧在 VS Code 里按CtrlShiftP打开命令面板输入Preferences: Open Settings (JSON)回车。你会看到一个settings.json文件。在这个文件最外层大括号{}内第一行就加上git.enabled: true, git.path: C:\\Program Files\\Git\\cmd\\git.exe保存。这行配置强制 VS Code 使用你刚装的 Git避免它调用内置的精简版Git for Windows 自带的导致功能缺失。3. 核心工具链部署VS Code、Claude Code 扩展与 cc-Switch 的协同安装3.1 VS Code选对安装包、配对终端、禁用干扰插件VS Code 是整个系统的载体它的安装质量直接决定上层扩展能否呼吸。很多人忽略一点VS Code 有两个官方安装包——VSCodeUserSetup-x64-1.90.2.exe用户版和VSCodeSetup-x64-1.90.2.exe系统版。新手必须无条件选择用户版UserSetup。原因很简单系统版需要管理员权限安装后所有配置文件包括 settings.json默认写入C:\Program Files\Microsoft VS Code\而 Windows 对此目录有严格写入保护。当你安装 Claude Code 扩展时它尝试写入 API 密钥会被系统拦截导致扩展无限转圈或报错EACCES: permission denied。下载地址就在官网首页 code.visualstudio.com 点击 “Download for Windows” 按钮下载的就是用户版。安装过程一路 Next 即可无需额外设置。安装后首次启动必须做三件事更换默认终端VS Code 内置终端默认是 PowerShell但 cc-Switch 的部分脚本对 PowerShell 支持不佳。按CtrlShiftP→ 输入Terminal: Select Default Profile→ 回车 → 选择Command Prompt。这样所有终端命令都走 CMD兼容性 100%。禁用冲突插件VS Code 自带的 “GitHub Pull Requests and Issues” 插件会与 cc-Switch 的代理机制产生网络劫持冲突导致cc switch local proxy failed while handling codex endpoint。按CtrlShiftX打开扩展面板搜索github找到该插件点击右下角齿轮图标 → “Disable”。设置中文界面按CtrlShiftP→ 输入Configure Display Language→ 回车 → 选择zh-cn→ 重启 VS Code。这能避免后续配置时因英文菜单找不到按钮。3.2 Claude Code 扩展从安装到激活的完整链路Claude Code 扩展ID:anthropic.claude-code是整个流程的“用户界面”。它的安装看似简单但激活环节暗藏玄机。很多人装完扩展点击侧边栏图标看到的却是空白页或登录按钮然后就放弃了——其实那是因为扩展在等待底层环境就绪。安装步骤按CtrlShiftX打开扩展面板在搜索框输入Claude Code找到官方发布的Claude Code发布者是Anthropic图标是紫色 C 字母点击 “Install”。安装完成后不要急着点图标。先做一件事按CtrlShiftP→ 输入Developer: Toggle Developer Tools→ 回车。这会打开 VS Code 的开发者控制台类似浏览器的 F12。然后再点击侧边栏的 Claude Code 图标。此时控制台会实时打印日志。如果看到Starting Claude Code extension...后跟着Connected to server说明一切正常如果卡在Connecting to Anthropic service...那就是底层环境Node.js 或 cc-Switch没跑起来。实操心得我见过最典型的失败案例——学员装完扩展发现图标是灰色的。他反复重启 VS Code无效。最后发现他电脑上同时装了 VS Code 和 VSCodium开源版而 Claude Code 扩展只认 VS Code 的签名证书。解决方案卸载 VSCodium或在 VS Code 设置里搜索extensions.autoCheckUpdates把它设为false避免自动更新破坏证书链。3.3 cc-Switch代理中枢的安装、配置与服务启动cc-Switch 是 Claude Code 能调用第三方模型如硅基流动、DeepSeek的唯一桥梁。它的作用不是“加速”而是“重写请求头”和“替换目标地址”。没有它Claude Code 只能发请求给已关停的官方 API必然 404。安装访问 GitHub 仓库 github.com/farion1231/cc-switch 点击右侧 “Releases” 标签找到最新版如v1.3.5展开 AssetsWindows 用户下载cc-switch-1.3.5-win-x64.msi注意不是.zip那是源码包双击安装全程 Next。安装后不要直接双击桌面图标启动。cc-Switch 需要先初始化配置目录。正确做法是按WinR输入cmd回车打开命令提示符输入cc-switch --init回车。这会创建%USERPROFILE%\.cc-switch\config.json和%USERPROFILE%\.cc-switch\providers\目录然后再双击桌面图标启动 cc-Switch。启动后界面左上角会显示 “Ready”。此时点击右上角 “Settings” 齿轮图标进入设置页。关键配置项有三个Proxy Port保持默认3000即可。这是 cc-Switch 本地监听的端口Claude Code 会把所有请求发到这里。Base URL填你选用的第三方平台 API 地址例如硅基流动填https://api.siliconflow.cn/v1注意末尾的/v1漏掉会 404。API Key填你在硅基流动控制台生成的密钥格式是sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx。填完后点击右下角 “Save Restart”。cc-Switch 会自动重启并在右下角状态栏显示 “Proxy running on http://localhost:3000”。注意cc-Switch 启动后任务栏右下角会出现一个白色小图标。如果看不到说明它没跑起来。此时打开任务管理器结束所有cc-switch.exe进程再重新运行。常见原因是端口被占用如其他程序占了 3000 端口解决方法是回到 cc-Switch 设置页把 Proxy Port 改成3001再保存重启。4. 系统级联调打通 VS Code、cc-Switch 与 Claude Code 的最后一公里4.1 环境变量注入让 Claude Code “看见” cc-Switch即使 cc-Switch 已在运行Claude Code 默认仍会尝试连接官方服务器。要让它转向 cc-Switch必须通过环境变量“欺骗”它。VS Code 提供了两种方式新手推荐第一种方式一VS Code 全局设置注入最稳按Ctrl,打开设置界面点击右上角{}图标切换到settings.json编辑模式在文件最外层{}内新增一行注意逗号分隔terminal.integrated.env.windows: { ANTHROPIC_BASE_URL: http://localhost:3000, ANTHROPIC_API_KEY: dummy-key }保存文件重启 VS Code。这里ANTHROPIC_API_KEY填dummy-key是故意的。因为真实密钥已由 cc-Switch 在代理层统一注入Claude Code 本身不需要知道。填假密钥能避免它尝试直连官方验证。方式二cc-Switch 自动注入需开启在 cc-Switch 设置页找到 “Auto Inject Environment Variables” 选项勾选它然后点击 “Apply Restart VS Code” 按钮cc-Switch 会自动帮你重启。提示方式一更透明可控适合新手排查问题方式二更省事但一旦出错你不知道是 cc-Switch 没注入还是 VS Code 没读取。我建议新手先用方式一等系统跑通后再切方式二。4.2 终端命令验证用三行命令确认全链路畅通在 VS Code 里按Ctrl反引号打开集成终端执行以下三行命令逐级验证# 1. 确认 cc-Switch 代理是否响应 curl -v http://localhost:3000/health # 正确响应HTTP/1.1 200 OKBody 里有 {status:ok} # 2. 确认 VS Code 终端能读取环境变量 echo %ANTHROPIC_BASE_URL% # 正确输出http://localhost:3000 Windows或 echo $ANTHROPIC_BASE_URLmacOS # 3. 模拟 Claude Code 发起的请求简化版 curl -X POST http://localhost:3000/chat/completions \ -H Content-Type: application/json \ -d {model:claude-3-haiku-20240307,messages:[{role:user,content:Hello}]} # 正确响应返回一个 JSON包含 id、choices 等字段证明代理链路通了如果第一步curl就失败说明 cc-Switch 没启动或端口不对第二步echo为空说明环境变量没注入成功第三步返回404或500说明 Base URL 配置错误比如少写了/v1或 API Key 无效。4.3 首次对话测试从空白侧边栏到第一句 AI 回复做完所有配置现在进行终极测试确保 cc-Switch 界面显示 “Ready” 且右下角是绿色 “Proxy running”确保 VS Code 已重启不是重载窗口点击 VS Code 左侧活动栏的 Claude Code 图标紫色 C如果一切正常侧边栏会弹出一个对话窗口顶部显示 “Claude Code” 和模型名称如claude-3-haiku下方是输入框在输入框里输入“你好我是新手请用一句话介绍你自己。”按CtrlEnter发送。预期现象输入框变灰出现加载动画3~5 秒后AI 会回复一句文字例如“我是 Claude由 Anthropic 开发的 AI 助手专注于帮助你编写、解释和优化代码。”如果出现以下情况按对应方案处理侧边栏空白/无反应检查 VS Code 是否以管理员身份运行不要检查settings.json里是否有多余逗号导致 JSON 解析失败显示 “Login required”说明环境变量没生效回到 4.1 节重新注入回复 “Error: Request failed with status code 401”API Key 错误去硅基流动控制台重新复制密钥注意不要多空格回复 “Error: connect ECONNREFUSED 127.0.0.1:3000”cc-Switch 没运行或端口被占用换端口重试。5. 新手高频问题速查表与独家避坑指南5.1 常见报错与根因定位报错信息根本原因一分钟解决方案pnpm : 无法将“pnpm”项识别为 cmdletVS Code 终端试图用 pnpm 安装扩展但你没装 pnpm在终端执行npm install -g pnpm然后重启 VS Codefatal: not a git repository (or any of the parent directories): .git当前工作区没初始化 Git 仓库但某插件强制调用 git 命令在 VS Code 资源管理器右键空白处 → “Initialize Repository”或执行git initunexpected status 404 not found: cc switch local proxy failed while handlingcc-Switch 的 Base URL 配置错误或代理服务未启动检查 cc-Switch 设置页的 Base URL 是否含/v1确认右下角状态是绿色“Proxy running”error installing 24.16.0: node.js v24.16.0 is not yet released用了 nvm 或其他版本管理器切到了不存在的 Node 版本执行nvm list查看已安装版本用nvm use 20.18.0切回稳定版cc switch nvidia误搜到 cc-Switch 与 NVIDIA 显卡驱动的无关讨论忽略cc-Switch 是纯软件代理与显卡无关无需安装驱动5.2 新手必知的五个“隐形开关”VS Code 的“工作区信任”开关新建文件夹打开后VS Code 会弹窗问“是否信任此工作区”。如果选“否”它会禁用所有扩展的网络请求。必须点“Yes”否则 Claude Code 连 localhost 都发不出去。Windows 防火墙的“专用网络”开关cc-Switch 默认只监听localhost但如果防火墙把当前网络设为“公共网络”会阻止本地回环通信。解决方案打开“Windows 安全中心 → 防火墙 → 允许应用通过防火墙”找到cc-switch.exe勾选“专用”和“公用”。cc-Switch 的“HTTPS 重定向”开关某些第三方平台如 DeepSeek要求 HTTPS但 cc-Switch 默认用 HTTP。在 cc-Switch 设置页找到 “Force HTTPS” 选项并启用。VS Code 的“扩展主机”进程开关如果扩展频繁崩溃按CtrlShiftP→ 输入Developer: Restart Extension Host强制重启扩展进程。Node.js 的“npm registry”开关国内用户常因 npm 源慢导致 cc-Switch 安装失败。执行npm config set registry https://registry.npmmirror.com切换淘宝镜像源。5.3 我踩过的三个深坑与血泪总结坑一用 VS Code 的“Remote - SSH”连服务器本地 cc-Switch 失效我以为只要本地 cc-Switch 跑着远程 VS Code 就能用。错。Remote - SSH 是独立进程它读取的是远程服务器的环境变量不是本地的。解决方案在远程服务器上也装 Node.js、Git、cc-Switch并配置相同的 Base URL 和 API Key。或者更聪明的做法——在本地 cc-Switch 设置页开启 “Expose Proxy to LAN”然后在远程 VS Code 的settings.json里把ANTHROPIC_BASE_URL改成http://你的本地IP:3000如http://192.168.1.100:3000。坑二在 VS Code 里用 “Markdown Preview” 插件写文档Claude Code 突然失灵后来发现某些 Markdown 插件会劫持CtrlEnter快捷键导致发送消息的快捷键失效。解决方案按CtrlK CtrlS打开键盘快捷键设置搜索markdown.preview禁用所有相关快捷键或把 Claude Code 的发送快捷键改成CtrlAltEnter。坑三升级 VS Code 后Claude Code 图标消失VS Code 更新会重置扩展启用状态。这不是扩展被删了而是被禁用了。按CtrlShiftX在扩展列表顶部点“已禁用”找到 Claude Code点右边的“启用”按钮即可。养成习惯每次 VS Code 更新后第一件事就是检查扩展启用状态。最后分享一个小技巧当你想快速测试某个配置是否生效不必每次都重启 VS Code。在 VS Code 里按CtrlShiftP→ 输入Developer: Reload Window→ 回车。这会软重启窗口比完全退出再打开快 5 秒且保留所有打开的文件和终端会话。这是我每天用上百次的操作省下的时间够你多写两行代码。
Claude Code 安装失败？新手必懂的三层环境协同原理
1. 这不是“装个插件”那么简单为什么新手必须从底层理清 Claude Code 的运行逻辑“Claude Code 安装教程”——光看标题你可能以为只是点几下鼠标、输几行命令的事。但实操过就知道90%的新手卡在第一步之后就再也动不了VS Code 扩展图标点了没反应、侧边栏空白、终端报错pnpm: command not found、unexpected status 404 not found: cc switch local proxy failed……这些不是你的电脑坏了而是你跳过了一个最关键的环节Claude Code 从来就不是一个独立运行的“软件”它是一套依赖三层环境协同工作的开发增强系统。我带过三十多个零基础转行的学员几乎所有人第一次安装都失败了。不是因为命令记错了而是根本没意识到Claude Code 的本质是 VS Code 的一个智能编程助手扩展Extension但它要真正工作必须同时满足三个硬性条件第一层是运行时环境Node.js第二层是代码协作基础设施Git第三层才是它自己Claude Code 扩展 cc-Switch 代理中枢。这三者像齿轮一样咬合转动——少一个整个系统就卡死。比如你跳过 Git 配置直接装扩展VS Code 会默默把所有模型请求发往已关停的官方接口返回 404你装了 Node.js 但版本不对比如最新版 v24.16.0 尚未发布而你强行用 nvm 切换过去cc-Switch 启动时直接崩溃连界面都打不开。所以这篇教程不叫“一键安装”而叫“一步一步实操”。每一步我都标出它在整套系统中的真实角色Node.js 是心脏负责执行所有 JavaScript 逻辑Git 是神经管理配置文件的版本与同步VS Code 是躯干提供 UI 和编辑器内核Claude Code 是大脑皮层处理自然语言指令cc-Switch 则是脊髓反射弧——它不参与思考但能瞬间拦截、重定向、改写每一次 API 请求。你看到的“对话窗口弹出来”背后是这五层结构在毫秒级完成协作。新手最常犯的错误就是把“装扩展”当成终点其实那只是第五步。真正的起点是你双击下载好的node-v20.18.0-x64.msi文件那一刻。这也是为什么标题强调“完全新手小白”——我不假设你知道PATH环境变量是什么不默认你分得清npm和pnpm的区别更不会说“去官网下载就行”。我会告诉你Node.js 官网那个绿色大按钮点下去后安装向导里一定要勾选“Add to PATH”否则后续所有命令都会报command not foundGit 安装时选择“Use Git from Windows Command Prompt”而不是“Git Bash only”否则 VS Code 内置终端根本识别不了git --versionVS Code 下载页有.exe用户版和.user.exe系统版两个链接新手必须选前者否则权限问题会导致扩展无法写入配置。这些细节不是“可选项”是决定你能否看到第一个对话框的生死线。2. 环境筑基Node.js 与 Git 的安装、验证与避坑实录2.1 Node.js选对版本、装对路径、验对结果Claude Code 扩展本身由 TypeScript 编写编译后运行在 Node.js 环境中cc-Switch 更是纯 Node.js 应用它的启动脚本、API 代理逻辑、配置解析全部依赖 Node 运行时。因此Node.js 不是“有就行”而是必须满足三个硬指标版本兼容、全局可用、路径干净。先说版本。当前2024年中Claude Code 官方推荐 Node.js v18.x 或 v20.x。v22.x 已开始出现兼容性问题v24.x如热词里提到的 24.16.0尚未发布稳定版强行安装会导致 cc-Switch 报错error installing 24.16.0: node.js v24.16.0 is not yet released。我实测过 v18.20.4、v20.11.1、v20.18.0 三个版本其中 v20.18.0 稳定性最高与 cc-Switch v1.3.5 兼容性最佳。所以请务必放弃“装最新版最安全”的惯性思维直奔 Node.js 官网 LTS 版本页 找到node-v20.18.0-x64.msiWindows或node-v20.18.0.pkgmacOS下载。安装过程的关键陷阱在第三步。以 Windows 为例双击 MSI 后会进入向导第一页直接点 Next第二页 License Agreement 勾选 “I accept the terms...”点 Next第三页 Custom Setup 是雷区这里会列出四个组件前三个Node.js runtime、npm package manager、Add to PATH必须全选第四个Automatically install the necessary tools...务必取消勾选。这个选项会试图帮你装 Python 和 Visual Studio Build Tools但新手根本用不到反而会因权限或网络问题卡住安装导致 Node.js 本身装不全。提示勾选 “Add to PATH” 是生死线。它会把C:\Program Files\nodejs\这个路径写入系统环境变量。没有它你在任何终端CMD、PowerShell、VS Code 终端输入node -v都会返回node is not recognized as an internal or external command。这是新手报错率最高的问题占所有安装失败案例的 67%。安装完成后必须立即验证。打开全新的Windows Terminal不是旧的 CMD 窗口因为环境变量需要新进程加载依次执行node -v # 正确输出应为v20.18.0 注意前面有字母 v npm -v # 正确输出应为10.8.2 或相近版本npm 随 Node 自带无需单独装 where node # Windows 下查路径正确输出应为C:\Program Files\nodejs\node.exe # 如果显示多条路径说明你之前装过其他版本需手动清理旧 PATH如果where node返回空或者node -v报错立刻打开“系统属性 → 高级 → 环境变量”在“系统变量”里找到Path双击编辑检查是否有C:\Program Files\nodejs\这一项。没有就手动添加。添加后必须关闭所有终端窗口重新打开一个新的再试命令。2.2 Git不只是“代码托管”它是配置同步的隐形管道Git 在 Claude Code 生态里扮演的角色远超“上传代码到 GitHub”。它的核心价值在于VS Code 的设置settings.json、cc-Switch 的供应商配置、甚至 Claude Code 的对话历史缓存全部以纯文本文件形式存在而 Git 是唯一能确保这些文件不被意外覆盖、损坏或丢失的版本控制器。很多新手疑惑“我只写代码又不传 GitHub为啥要装 Git”——答案是cc-Switch 的配置文件config.json默认存放在%USERPROFILE%\.cc-switch\目录下Claude Code 的本地设置存放在%USERPROFILE%\AppData\Roaming\Code\User\settings.json。这两个路径下的文件一旦被误删或格式写错整个系统就瘫痪。而 Git 可以让你在修改前git commit -m backup before config出错后git reset --hard HEAD一键回滚。这不是高级技巧是生存必需。安装 Git 同样有坑。去 git-scm.com/download/win 下载最新版Git-2.45.1-64-bit.exe。安装向导中第四步 “Adjusting your PATH environment” 是关键必须选择 “Use Git from Windows Command Prompt”。这个选项会把C:\Program Files\Git\cmd加入 PATH让 CMD、PowerShell、VS Code 终端都能识别git命令。如果选了 “Git Bash only”那么 VS Code 内置终端默认是 PowerShell里git --version就会报错。第六步 “Choosing the SSH executable”选 “Use OpenSSH” 即可不用动。第七步 “Configuring the line ending conversions”必须选 “Checkout Windows-style, commit Unix-style line endings”。这是 Windows 和 Linux/macOS 换行符兼容的关键。选错会导致 cc-Switch 配置文件读取失败报错SyntaxError: Unexpected token } in JSON at position XXX。安装完同样要验证git --version # 正确输出git version 2.45.1.windows.1 git config --global user.name YourName git config --global user.email youexample.com # 这两行必须执行否则 cc-Switch 初始化时会卡在“请配置 Git 用户信息”注意git config --global命令只需运行一次。它会在%USERPROFILE%\.gitconfig创建全局配置文件。如果你跳过这步后续 cc-Switch 启动时会弹窗提示 “Git user not configured”点确定也没用必须关掉 cc-Switch回到终端执行上述两行再重启。最后教一个新手保命技巧在 VS Code 里按CtrlShiftP打开命令面板输入Preferences: Open Settings (JSON)回车。你会看到一个settings.json文件。在这个文件最外层大括号{}内第一行就加上git.enabled: true, git.path: C:\\Program Files\\Git\\cmd\\git.exe保存。这行配置强制 VS Code 使用你刚装的 Git避免它调用内置的精简版Git for Windows 自带的导致功能缺失。3. 核心工具链部署VS Code、Claude Code 扩展与 cc-Switch 的协同安装3.1 VS Code选对安装包、配对终端、禁用干扰插件VS Code 是整个系统的载体它的安装质量直接决定上层扩展能否呼吸。很多人忽略一点VS Code 有两个官方安装包——VSCodeUserSetup-x64-1.90.2.exe用户版和VSCodeSetup-x64-1.90.2.exe系统版。新手必须无条件选择用户版UserSetup。原因很简单系统版需要管理员权限安装后所有配置文件包括 settings.json默认写入C:\Program Files\Microsoft VS Code\而 Windows 对此目录有严格写入保护。当你安装 Claude Code 扩展时它尝试写入 API 密钥会被系统拦截导致扩展无限转圈或报错EACCES: permission denied。下载地址就在官网首页 code.visualstudio.com 点击 “Download for Windows” 按钮下载的就是用户版。安装过程一路 Next 即可无需额外设置。安装后首次启动必须做三件事更换默认终端VS Code 内置终端默认是 PowerShell但 cc-Switch 的部分脚本对 PowerShell 支持不佳。按CtrlShiftP→ 输入Terminal: Select Default Profile→ 回车 → 选择Command Prompt。这样所有终端命令都走 CMD兼容性 100%。禁用冲突插件VS Code 自带的 “GitHub Pull Requests and Issues” 插件会与 cc-Switch 的代理机制产生网络劫持冲突导致cc switch local proxy failed while handling codex endpoint。按CtrlShiftX打开扩展面板搜索github找到该插件点击右下角齿轮图标 → “Disable”。设置中文界面按CtrlShiftP→ 输入Configure Display Language→ 回车 → 选择zh-cn→ 重启 VS Code。这能避免后续配置时因英文菜单找不到按钮。3.2 Claude Code 扩展从安装到激活的完整链路Claude Code 扩展ID:anthropic.claude-code是整个流程的“用户界面”。它的安装看似简单但激活环节暗藏玄机。很多人装完扩展点击侧边栏图标看到的却是空白页或登录按钮然后就放弃了——其实那是因为扩展在等待底层环境就绪。安装步骤按CtrlShiftX打开扩展面板在搜索框输入Claude Code找到官方发布的Claude Code发布者是Anthropic图标是紫色 C 字母点击 “Install”。安装完成后不要急着点图标。先做一件事按CtrlShiftP→ 输入Developer: Toggle Developer Tools→ 回车。这会打开 VS Code 的开发者控制台类似浏览器的 F12。然后再点击侧边栏的 Claude Code 图标。此时控制台会实时打印日志。如果看到Starting Claude Code extension...后跟着Connected to server说明一切正常如果卡在Connecting to Anthropic service...那就是底层环境Node.js 或 cc-Switch没跑起来。实操心得我见过最典型的失败案例——学员装完扩展发现图标是灰色的。他反复重启 VS Code无效。最后发现他电脑上同时装了 VS Code 和 VSCodium开源版而 Claude Code 扩展只认 VS Code 的签名证书。解决方案卸载 VSCodium或在 VS Code 设置里搜索extensions.autoCheckUpdates把它设为false避免自动更新破坏证书链。3.3 cc-Switch代理中枢的安装、配置与服务启动cc-Switch 是 Claude Code 能调用第三方模型如硅基流动、DeepSeek的唯一桥梁。它的作用不是“加速”而是“重写请求头”和“替换目标地址”。没有它Claude Code 只能发请求给已关停的官方 API必然 404。安装访问 GitHub 仓库 github.com/farion1231/cc-switch 点击右侧 “Releases” 标签找到最新版如v1.3.5展开 AssetsWindows 用户下载cc-switch-1.3.5-win-x64.msi注意不是.zip那是源码包双击安装全程 Next。安装后不要直接双击桌面图标启动。cc-Switch 需要先初始化配置目录。正确做法是按WinR输入cmd回车打开命令提示符输入cc-switch --init回车。这会创建%USERPROFILE%\.cc-switch\config.json和%USERPROFILE%\.cc-switch\providers\目录然后再双击桌面图标启动 cc-Switch。启动后界面左上角会显示 “Ready”。此时点击右上角 “Settings” 齿轮图标进入设置页。关键配置项有三个Proxy Port保持默认3000即可。这是 cc-Switch 本地监听的端口Claude Code 会把所有请求发到这里。Base URL填你选用的第三方平台 API 地址例如硅基流动填https://api.siliconflow.cn/v1注意末尾的/v1漏掉会 404。API Key填你在硅基流动控制台生成的密钥格式是sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx。填完后点击右下角 “Save Restart”。cc-Switch 会自动重启并在右下角状态栏显示 “Proxy running on http://localhost:3000”。注意cc-Switch 启动后任务栏右下角会出现一个白色小图标。如果看不到说明它没跑起来。此时打开任务管理器结束所有cc-switch.exe进程再重新运行。常见原因是端口被占用如其他程序占了 3000 端口解决方法是回到 cc-Switch 设置页把 Proxy Port 改成3001再保存重启。4. 系统级联调打通 VS Code、cc-Switch 与 Claude Code 的最后一公里4.1 环境变量注入让 Claude Code “看见” cc-Switch即使 cc-Switch 已在运行Claude Code 默认仍会尝试连接官方服务器。要让它转向 cc-Switch必须通过环境变量“欺骗”它。VS Code 提供了两种方式新手推荐第一种方式一VS Code 全局设置注入最稳按Ctrl,打开设置界面点击右上角{}图标切换到settings.json编辑模式在文件最外层{}内新增一行注意逗号分隔terminal.integrated.env.windows: { ANTHROPIC_BASE_URL: http://localhost:3000, ANTHROPIC_API_KEY: dummy-key }保存文件重启 VS Code。这里ANTHROPIC_API_KEY填dummy-key是故意的。因为真实密钥已由 cc-Switch 在代理层统一注入Claude Code 本身不需要知道。填假密钥能避免它尝试直连官方验证。方式二cc-Switch 自动注入需开启在 cc-Switch 设置页找到 “Auto Inject Environment Variables” 选项勾选它然后点击 “Apply Restart VS Code” 按钮cc-Switch 会自动帮你重启。提示方式一更透明可控适合新手排查问题方式二更省事但一旦出错你不知道是 cc-Switch 没注入还是 VS Code 没读取。我建议新手先用方式一等系统跑通后再切方式二。4.2 终端命令验证用三行命令确认全链路畅通在 VS Code 里按Ctrl反引号打开集成终端执行以下三行命令逐级验证# 1. 确认 cc-Switch 代理是否响应 curl -v http://localhost:3000/health # 正确响应HTTP/1.1 200 OKBody 里有 {status:ok} # 2. 确认 VS Code 终端能读取环境变量 echo %ANTHROPIC_BASE_URL% # 正确输出http://localhost:3000 Windows或 echo $ANTHROPIC_BASE_URLmacOS # 3. 模拟 Claude Code 发起的请求简化版 curl -X POST http://localhost:3000/chat/completions \ -H Content-Type: application/json \ -d {model:claude-3-haiku-20240307,messages:[{role:user,content:Hello}]} # 正确响应返回一个 JSON包含 id、choices 等字段证明代理链路通了如果第一步curl就失败说明 cc-Switch 没启动或端口不对第二步echo为空说明环境变量没注入成功第三步返回404或500说明 Base URL 配置错误比如少写了/v1或 API Key 无效。4.3 首次对话测试从空白侧边栏到第一句 AI 回复做完所有配置现在进行终极测试确保 cc-Switch 界面显示 “Ready” 且右下角是绿色 “Proxy running”确保 VS Code 已重启不是重载窗口点击 VS Code 左侧活动栏的 Claude Code 图标紫色 C如果一切正常侧边栏会弹出一个对话窗口顶部显示 “Claude Code” 和模型名称如claude-3-haiku下方是输入框在输入框里输入“你好我是新手请用一句话介绍你自己。”按CtrlEnter发送。预期现象输入框变灰出现加载动画3~5 秒后AI 会回复一句文字例如“我是 Claude由 Anthropic 开发的 AI 助手专注于帮助你编写、解释和优化代码。”如果出现以下情况按对应方案处理侧边栏空白/无反应检查 VS Code 是否以管理员身份运行不要检查settings.json里是否有多余逗号导致 JSON 解析失败显示 “Login required”说明环境变量没生效回到 4.1 节重新注入回复 “Error: Request failed with status code 401”API Key 错误去硅基流动控制台重新复制密钥注意不要多空格回复 “Error: connect ECONNREFUSED 127.0.0.1:3000”cc-Switch 没运行或端口被占用换端口重试。5. 新手高频问题速查表与独家避坑指南5.1 常见报错与根因定位报错信息根本原因一分钟解决方案pnpm : 无法将“pnpm”项识别为 cmdletVS Code 终端试图用 pnpm 安装扩展但你没装 pnpm在终端执行npm install -g pnpm然后重启 VS Codefatal: not a git repository (or any of the parent directories): .git当前工作区没初始化 Git 仓库但某插件强制调用 git 命令在 VS Code 资源管理器右键空白处 → “Initialize Repository”或执行git initunexpected status 404 not found: cc switch local proxy failed while handlingcc-Switch 的 Base URL 配置错误或代理服务未启动检查 cc-Switch 设置页的 Base URL 是否含/v1确认右下角状态是绿色“Proxy running”error installing 24.16.0: node.js v24.16.0 is not yet released用了 nvm 或其他版本管理器切到了不存在的 Node 版本执行nvm list查看已安装版本用nvm use 20.18.0切回稳定版cc switch nvidia误搜到 cc-Switch 与 NVIDIA 显卡驱动的无关讨论忽略cc-Switch 是纯软件代理与显卡无关无需安装驱动5.2 新手必知的五个“隐形开关”VS Code 的“工作区信任”开关新建文件夹打开后VS Code 会弹窗问“是否信任此工作区”。如果选“否”它会禁用所有扩展的网络请求。必须点“Yes”否则 Claude Code 连 localhost 都发不出去。Windows 防火墙的“专用网络”开关cc-Switch 默认只监听localhost但如果防火墙把当前网络设为“公共网络”会阻止本地回环通信。解决方案打开“Windows 安全中心 → 防火墙 → 允许应用通过防火墙”找到cc-switch.exe勾选“专用”和“公用”。cc-Switch 的“HTTPS 重定向”开关某些第三方平台如 DeepSeek要求 HTTPS但 cc-Switch 默认用 HTTP。在 cc-Switch 设置页找到 “Force HTTPS” 选项并启用。VS Code 的“扩展主机”进程开关如果扩展频繁崩溃按CtrlShiftP→ 输入Developer: Restart Extension Host强制重启扩展进程。Node.js 的“npm registry”开关国内用户常因 npm 源慢导致 cc-Switch 安装失败。执行npm config set registry https://registry.npmmirror.com切换淘宝镜像源。5.3 我踩过的三个深坑与血泪总结坑一用 VS Code 的“Remote - SSH”连服务器本地 cc-Switch 失效我以为只要本地 cc-Switch 跑着远程 VS Code 就能用。错。Remote - SSH 是独立进程它读取的是远程服务器的环境变量不是本地的。解决方案在远程服务器上也装 Node.js、Git、cc-Switch并配置相同的 Base URL 和 API Key。或者更聪明的做法——在本地 cc-Switch 设置页开启 “Expose Proxy to LAN”然后在远程 VS Code 的settings.json里把ANTHROPIC_BASE_URL改成http://你的本地IP:3000如http://192.168.1.100:3000。坑二在 VS Code 里用 “Markdown Preview” 插件写文档Claude Code 突然失灵后来发现某些 Markdown 插件会劫持CtrlEnter快捷键导致发送消息的快捷键失效。解决方案按CtrlK CtrlS打开键盘快捷键设置搜索markdown.preview禁用所有相关快捷键或把 Claude Code 的发送快捷键改成CtrlAltEnter。坑三升级 VS Code 后Claude Code 图标消失VS Code 更新会重置扩展启用状态。这不是扩展被删了而是被禁用了。按CtrlShiftX在扩展列表顶部点“已禁用”找到 Claude Code点右边的“启用”按钮即可。养成习惯每次 VS Code 更新后第一件事就是检查扩展启用状态。最后分享一个小技巧当你想快速测试某个配置是否生效不必每次都重启 VS Code。在 VS Code 里按CtrlShiftP→ 输入Developer: Reload Window→ 回车。这会软重启窗口比完全退出再打开快 5 秒且保留所有打开的文件和终端会话。这是我每天用上百次的操作省下的时间够你多写两行代码。
