1. 为什么 NodeJS 版本混乱会让 Claude Code 装不上
Claude Code 是一个跑在终端里的编码 Agent，它本身是 Node 包，靠npm install -g装到全局。问题就出在这个「全局」上：如果你的机器里同时存在官网安装包版 Node、nvm 管理的 Node、甚至某些 IDE 自带的 Node，npm到底往哪个目录写、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 node（macOS 用which node），确认没有输出。
这一步别偷懒。我试过在没卸载的情况下直接装 nvm，结果nvm use切换成功，但新开终端又变回旧版本，排查了半小时才发现是旧 Node 的 PATH 优先级更高。
2.2 安装 nvm 并配置镜像加速
Windows 用户去 nvm-windows 的 Releases 页面下载nvm-setup.exe，双击安装，安装目录建议用默认的C:\Users\你的用户名\AppData\Roaming\nvm，Node 软链接目录用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.x，npm -v输出对应版本，npm root -g输出的路径里应该包含nvm字样（Windows 上是AppData\Roaming\nvm，macOS 上是~/.nvm）。如果npm root -g指向的还是旧目录，说明旧 Node 没卸干净，回到 2.1 重来。
nvm 常用命令我整理成一张表，方便你后面切换：
| 命令 | 作用 |
|---|---|
nvm list available | 查看可安装的 Node 版本 |
nvm install 22 | 安装 22.x 最新版 |
nvm list | 查看本机已安装的版本 |
nvm use 22 | 切换到 22 |
nvm uninstall 22 | 卸载 22 |
锁定版本的意义在于：Claude Code 全局装在某个 Node 版本下，如果你后面随手nvm use切到别的版本，claude命令可能就找不到了。所以建议在项目里放一个.nvmrc文件，内容写22，每次进项目先nvm use，让版本和 Claude Code 的安装环境保持一致。
3. 安装 Claude Code 并用 CC-Switch 配置模型
3.1 全局安装 Claude Code
Node 环境干净之后，装 Claude Code 就一条命令：
npm install -g @anthropic-ai/claude-code --registry=https://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.json，macOS / 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/api，API 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 状态，有基线它才知道哪些是你原有的、哪些是它改的。如果项目是空的，至少建一个 README：
echo "# my-project" > README.md git add README.md git commit -m "init: 添加 README"4.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 failed
Error: 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的路径，确认这个路径下的bin（Windows 是根目录）在 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 每次改文件前会问你，安全得多。
