1. 为什么 NodeJS 版本混乱会让 Claude Code 装不上Claude Code 是一个跑在终端里的编码 Agent它本身是 Node 包靠npm install -g装到全局。问题就出在这个「全局」上如果你的机器里同时存在官网安装包版 Node、nvm 管理的 Node、甚至某些 IDE 自带的 Nodenpm到底往哪个目录写、claude命令最终落在哪个 PATH 里就变成了一笔糊涂账。我见过最常见的现象是终端里node -v显示 20.x但npm root -g指向的却是另一个 18.x 的目录装完 Claude Code 后敲claude直接提示 command not found。所以这篇教程的核心思路不是「教你点下一步」而是先把 NodeJS 这条地基用 nvm 管干净再让 CC-Switch 去接管模型配置最后用 git 把项目目录初始化好让 Claude Code 一启动就有上下文可读。适合谁看第一次在本地跑 Claude Code、之前 Node 环境装得比较随意、或者切换 Node 版本时踩过坑的开发者。整条链路是这样的nvm 负责 Node 版本 → npm 全局装 Claude Code → CC-Switch 负责把模型供应商和 API Key 写进配置 → git 负责给项目建仓库。顺序错了后面每一步都会报奇怪的错。下面按可复制的命令一步步来每条命令我都标了预期输出你对着敲就行。2. 用 nvm 管好 NodeJS 并锁定 Claude Code 所需版本2.1 先清掉旧的 NodeJS 安装如果你之前用官网安装包装过 Node装 nvm 前必须先卸掉否则两个 Node 会抢 PATH。Windows 上先查一下where node只要这条命令有输出就说明系统里存在一个「非 nvm 管理」的 Node。去「设置 → 应用 → 已安装的应用」里找到 Node.js 卸载掉。macOS / Linux 用户如果是用 brew 装的执行brew uninstall node即可。卸完再敲一次where nodemacOS 用which node确认没有输出。这一步别偷懒。我试过在没卸载的情况下直接装 nvm结果nvm use切换成功但新开终端又变回旧版本排查了半小时才发现是旧 Node 的 PATH 优先级更高。2.2 安装 nvm 并配置镜像加速Windows 用户去 nvm-windows 的 Releases 页面下载nvm-setup.exe双击安装安装目录建议用默认的C:\Users\你的用户名\AppData\Roaming\nvmNode 软链接目录用C:\Program Files\nodejs。macOS / Linux 用户用官方脚本curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash装完新开一个终端验证nvm -v预期输出类似1.1.12或0.40.1。有版本号就说明 nvm 本身可用了。接着配国内镜像否则nvm install会慢到怀疑人生nvm node_mirror https://npmmirror.com/mirrors/node/ nvm npm_mirror https://npmmirror.com/mirrors/npm/这两条命令把 Node 和 npm 的下载源都指向了 npmmirror后面装 Node 基本几十秒搞定。2.3 安装并锁定 Node 版本先看有哪些版本可装nvm list available输出是一张表格LTS列是长期支持版。Claude Code 对 Node 版本有要求建议直接用当前 LTS比如 22 或 24。安装并切换nvm install 22 nvm use 22nvm use成功后验证三件事node -v npm -v npm root -gnode -v应该输出v22.x.xnpm -v输出对应版本npm root -g输出的路径里应该包含nvm字样Windows 上是AppData\Roaming\nvmmacOS 上是~/.nvm。如果npm root -g指向的还是旧目录说明旧 Node 没卸干净回到 2.1 重来。nvm 常用命令我整理成一张表方便你后面切换命令作用nvm list available查看可安装的 Node 版本nvm install 22安装 22.x 最新版nvm list查看本机已安装的版本nvm use 22切换到 22nvm uninstall 22卸载 22锁定版本的意义在于Claude Code 全局装在某个 Node 版本下如果你后面随手nvm use切到别的版本claude命令可能就找不到了。所以建议在项目里放一个.nvmrc文件内容写22每次进项目先nvm use让版本和 Claude Code 的安装环境保持一致。3. 安装 Claude Code 并用 CC-Switch 配置模型3.1 全局安装 Claude CodeNode 环境干净之后装 Claude Code 就一条命令npm install -g anthropic-ai/claude-code --registryhttps://registry.npmmirror.com--registry参数临时指定淘宝源避免官方源超时。装完验证claude --version有版本号输出就说明命令已经进 PATH 了。如果提示 command not found先执行npm root -g看全局目录再把这个目录下的bin加进 PATH或者干脆重开终端。3.2 CC-Switch 是什么为什么需要它Claude Code 默认读的是 Anthropic 官方配置但很多开发者会用兼容接口来跑其他模型。CC-Switch 是一个桌面应用专门管理 Claude Code、Codex、Gemini CLI 这类 CLI 工具的供应商配置内置了 50 多个供应商预设点一下就能把 Base URL、API Key、模型 ID 写进对应配置文件不用手动去改 JSON。去 CC-Switch 的 Releases 页面下载CC-Switch-v{版本号}-Windows.msi或绿色版 zip双击安装后打开主界面。左侧分组选到「Claude」点「添加供应商」。3.3 可复制的配置片段假设你要接入 TaoToken 的兼容接口在 CC-Switch 里手动添加供应商时填这三项{ name: taotoken, baseUrl: https://taotoken.net/api, apiKey: sk-你的密钥, models: { primary: claude-sonnet-4-5, reasoning: claude-opus-4-1 } }如果你不想用 CC-Switch 的图形界面也可以直接编辑 Claude Code 的配置文件。Windows 路径是C:\Users\你的用户名\.claude\settings.jsonmacOS / Linux 是~/.claude/settings.json。内容格式{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的密钥, ANTHROPIC_MODEL: claude-sonnet-4-5 } }这里三件套必须齐全Base URL 指向https://taotoken.net/apiAPI Key 从控制台生成Model ID 填你要用的模型。少任何一个Claude Code 启动时都会报认证或模型找不到的错。API Key 的获取入口在 TaoToken 控制台的 API Keys 页面生成后复制粘贴即可注意别把 Key 提交到 git 仓库里。CC-Switch 的好处是它帮你把这份 JSON 写对还能一键在多个供应商之间切换。如果你同时用 Claude Code 和 Codex它也能统一管理省得每个工具都去翻配置文件。4. 初始化 git 仓库并验证 claude 命令能正常拉起4.1 安装 git 并初始化项目git 是 Claude Code 读代码上下文的基础没有 git 仓库它对项目的理解会大打折扣。先确认 git 装好了git -v没装的话去 git 官网下载安装包一路 next 即可。装完进你的项目目录cd /path/to/your-project git init git add . git commit -m init: 项目初始提交git init会创建.git目录git commit给当前代码打一个基线。为什么要先 commit因为 Claude Code 在修改文件前会参考 git 状态有基线它才知道哪些是你原有的、哪些是它改的。如果项目是空的至少建一个 READMEecho # my-project README.md git add README.md git commit -m init: 添加 README4.2 验证 claude 命令拉起在项目目录下直接敲claude预期会进入一个交互式界面顶部显示当前模型和项目路径。第一次启动可能会让你确认一些权限按提示走即可。如果卡在认证环节说明 3.3 的配置没生效检查~/.claude/settings.json里的ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY是否写对。想快速验证模型能不能通不进交互界面直接用一次性提问claude -p 用一句话说明这个项目是做什么的-p是 print 模式输出完就退出。如果返回了合理回答说明 Base URL、Key、Model 三件套全部生效。这一步成功整个链路就通了。4.3 切换 Node 版本后的验证如果你后面用nvm use切了 Node 版本记得重新验证claude命令还在不在nvm use 22 claude --version因为全局包是装在特定 Node 版本下的切版本后claude可能失效。解决办法是在新版本下重新npm install -g anthropic-ai/claude-code或者用.nvmrc固定版本别频繁切。5. 安装期高频报错逐条排查5.1 401 认证失败报错长这样API Error: 401 {error:{message:Invalid API key}}原因基本是 API Key 写错、过期或者 Base URL 和 Key 不匹配。排查顺序先确认~/.claude/settings.json里的ANTHROPIC_API_KEY没有多余空格再去 TaoToken 控制台确认这个 Key 还有效最后检查ANTHROPIC_BASE_URL是不是https://taotoken.net/api结尾不要多加斜杠。三件套里任何一项错位都会 401。5.2 local proxy failedError: local proxy failed to start这个通常出现在你本地开了某些网络工具Claude Code 尝试走本地代理但端口被占用或配置冲突。先检查环境变量里有没有HTTP_PROXY/HTTPS_PROXY有的话临时清掉unset HTTP_PROXY HTTPS_PROXYWindows 上用set HTTP_PROXY。清完重开终端再试。如果还报检查 CC-Switch 里有没有误配代理地址。5.3 reading choices 相关报错Error: reading choices of undefined这是模型返回格式和 Claude Code 预期不一致导致的常见于 Base URL 指向了一个非兼容接口。确认你的ANTHROPIC_BASE_URL指向的是兼容 Anthropic 协议的端点而不是 OpenAI 格式的端点。TaoToken 的https://taotoken.net/api是兼容接口直接填这个即可。如果自己填了别的地址换回来。5.4 OAuth 相关报错OAuth error: invalid_grantClaude Code 某些版本会尝试走 OAuth 登录流程如果你用的是 API Key 模式这个报错说明它没读到你的 Key退回到了 OAuth。检查settings.json里env字段的层级对不对必须是顶层env对象包住三个变量。层级写错的话 Claude Code 读不到就会走默认 OAuth。5.5 claude 命令找不到claude is not recognized as an internal or external command回到 2.3 检查npm root -g的路径确认这个路径下的binWindows 是根目录在 PATH 里。最省事的办法是重开终端或者用nvm use重新激活当前版本。如果还是不行重新执行一次全局安装命令。6. 装完之后怎么继续用起来环境通了之后日常使用其实就三件事进项目目录、nvm use确认版本、敲claude。如果你想让 Claude Code 在 VS Code 里用去扩展市场搜 Claude Code 插件装上它会自动复用你~/.claude/settings.json里的配置不用重复填 Key。模型想换的时候打开 CC-Switch 点一下切换供应商就行它会帮你改写配置文件比手动编辑 JSON 稳。API Key 的管理和生成都在 TaoToken 控制台建议给不同项目建不同的 Key方便排查和吊销。接入文档里有更细的协议说明和参数列表遇到兼容性问题可以先翻一遍。最后提醒一句claude --dangerously-skip-permissions这个参数会跳过所有权限确认只建议在临时目录或容器里用别在核心项目根目录直接跑。正常开发用默认权限模式Claude Code 每次改文件前会问你安全得多。