1. 为什么 Claude Code 本地安装总卡在 node.js 版本上
Claude Code 是 Anthropic 推出的命令行 Agent 工具，能在终端里直接读写项目文件、跑命令、改代码，适合习惯用命令行干活的开发者。它跑起来依赖 node.js 运行时，而 node.js 的版本管理如果一开始就乱，后面 npm 全局安装、权限、路径会连环出问题。我见过太多人卡在npm install -g @anthropic-ai/claude-code报 EACCES 或者装完claude命令找不到，根子都在 node.js 装法上。
这篇聚焦 Windows 和 macOS 下用 nvm 管理 node.js 与 npm 的完整链路：装 nvm、切指定 node 版本、配 npm 源、装 Claude Code、再用claude --version和一次最小对话请求验证。全程命令可复制，避开版本冲突和权限报错。
先说清楚一个概念。nvm 是 Node Version Manager，专门管 node.js 版本的。你可以把它想成手机里的「应用多开」——同一台电脑上能同时存在 node 18、20、22、24 好几个版本，用一条命令切换当前用哪个。为什么不用官网下载的安装包直接装？因为安装包装完是全局唯一的，想换版本得先卸载再装，项目之间版本需求不一样时非常痛苦。nvm 把每个版本隔离在独立目录，切换只改环境变量指向，干净利落。
Claude Code 官方要求 node.js 版本在 18 以上，实际用下来建议直接上 20 LTS 或更高。excerpt 里提到 24 以上，那是更稳妥的选择，新版本对 ESM、fetch 这些特性支持更完整，Agent 跑起来少踩坑。所以这篇的路线是：nvm 装好 → 装一个 20 以上的版本 → 设为默认 → 配 npm 源加速 → 全局装 Claude Code → 验证。
适合谁看：刚接触 Claude Code 想本地跑起来的新手；电脑里 node 版本混乱、npm 全局包装不上的；想用 nvm 把环境理顺再接入模型 API 的。如果你已经有一套干净的 node 环境，可以直接跳到第 3 节看配置。
还有一个前置认知：Claude Code 本身只是个客户端，装完之后要接模型才能对话。接入需要三样东西——Base URL、API Key、Model ID。这三件套在第 3 节会给出可复制的配置片段，第 4 节验证，第 5 节排错。整条链路走通，你就能在终端里让 Agent 帮你改代码了。
2. nvm 安装与 node.js 版本切换实操
这一节把 nvm 装好，并且切到 Claude Code 能用的 node 版本。Windows 和 macOS 的装法不一样，分开说。
2.1 Windows 装 nvm-windows
Windows 上用 nvm-windows，它和 macOS 的 nvm 不是同一个项目，但命令基本一致。去 nvm-windows 的 GitHub Releases 页面下载nvm-setup.exe，双击一路默认安装。安装过程中它会问你 node.js 的 symlink 目录放哪，默认C:\Program Files\nodejs就行，别改到带空格的奇怪路径。
装之前有个坑要提醒：如果你电脑里已经用官网安装包装过 node.js，先卸载掉。nvm 和全局 node 会抢 PATH，导致nvm use切了但node -v还是老版本。卸载完重启一次终端。
装完打开新的 PowerShell 或 cmd，输入：
nvm version能打印出版本号就说明 nvm 本身装好了。如果提示nvm不是内部或外部命令，检查环境变量 PATH 里有没有 nvm 的安装目录，通常重开终端就好。
2.2 macOS 装 nvm
macOS 推荐用官方安装脚本，别用 brew 装 nvm，brew 那个版本经常和 shell 配置打架。打开终端执行：
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash装完脚本会提示你把几行配置加到~/.zshrc或~/.bash_profile。如果你用的是 zsh（macOS 默认），执行：
echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.zshrc echo '[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"' >> ~/.zshrc source ~/.zshrc然后验证：
nvm --version打印出版本号即可。如果报 command not found，多半是 shell 配置文件没生效，重开终端或手动 source 一次。
2.3 安装并切换 node 版本
nvm 装好后，先看有哪些版本可装：
nvm list availableWindows 上这个命令会列出可安装的版本。选一个 20 以上的 LTS，比如 20.18.0 或 22.x。安装：
nvm install 20.18.0装完设为默认，这样每次新开终端都用这个版本：
nvm use 20.18.0 nvm alias default 20.18.0验证当前 node 和 npm 版本：
node -v npm -v应该分别打印v20.18.0和对应的 npm 版本。如果node -v还是老版本，说明 PATH 里全局 node 没清干净，回 2.1 检查卸载。
macOS 上如果之前用 brew 装过 node，先brew uninstall node再走 nvm，否则同样会冲突。
2.4 配置 npm 源加速
国内直连 npm 官方源下载全局包经常超时，换成国内镜像。这条命令是全局配置，一次设置长期有效：
npm config set registry https://registry.npmmirror.com验证是否生效：
npm config get registry打印出https://registry.npmmirror.com/就对了。这一步能显著减少后面装 Claude Code 时的等待和失败率。
到这里 node 和 npm 的环境就理顺了。下一节装 Claude Code 并配置接入。
3. Claude Code 安装与三件套配置片段
环境准备好，开始装 Claude Code 本体，然后配置模型接入。
3.1 全局安装 Claude Code
一条命令：
npm install -g @anthropic-ai/claude-code等十几秒，看到added 1 package之类的输出就装完了。如果卡住不动，多半是源没配好，回 2.4 检查 registry。
装完验证命令是否存在：
claude --version能打印版本号说明二进制装好了。如果提示claude不是命令，说明 npm 全局 bin 目录不在 PATH 里。先查全局路径：
npm config get prefixWindows 上通常是C:\Users\你的用户名\AppData\Roaming\npm，macOS 上是/usr/local或 nvm 对应的路径。把这个路径下的 bin 目录加进 PATH，重开终端再试。
3.2 配置三件套：Base URL + Key + Model ID
Claude Code 要接模型才能用，需要三样东西。这里以接入 TaoToken 为例，它提供兼容的 API 端点，配置方式和官方一致。
Base URL 用https://taotoken.net/api，API Key 去控制台创建，Model ID 填你要用的模型名。这三件套缺一不可，少一个就会在请求时报 401 或 model not found。
Claude Code 的配置可以走环境变量，也可以走配置文件。推荐用配置文件，路径和内容如下。
macOS / Linux 下编辑~/.claude/settings.json：
{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "sk-你的key", "ANTHROPIC_MODEL": "claude-sonnet-4-20250514" } }Windows 下路径是C:\Users\你的用户名\.claude\settings.json，内容一样。注意 JSON 里不能有多余逗号，Key 要替换成你自己在控制台创建的那串。
如果你用 CC Switch 这类工具管理多个厂商，配置逻辑一样：Base URL 填https://taotoken.net/api，Key 填控制台生成的，Model ID 填模型名。CC Switch 的好处是能在多个厂商之间切换，测试哪个模型跑得顺。
注意：API Key 不要提交到 git，不要贴在公开聊天里。settings.json 建议加进 .gitignore。
3.3 用环境变量临时覆盖
有时候你不想改配置文件，只想临时试一个模型，可以用环境变量。macOS / Linux：
export ANTHROPIC_BASE_URL="https://taotoken.net/api" export ANTHROPIC_API_KEY="sk-你的key" export ANTHROPIC_MODEL="claude-sonnet-4-20250514"Windows PowerShell：
$env:ANTHROPIC_BASE_URL="https://taotoken.net/api" $env:ANTHROPIC_API_KEY="sk-你的key" $env:ANTHROPIC_MODEL="claude-sonnet-4-20250514"这种方式只在当前终端窗口有效，关掉就没了，适合调试。
配置写完，下一节发一次真实请求验证整条链路。
4. 验证请求：claude --version 与最小对话
配置对不对，跑一次就知道。分两步验证，先确认命令可用，再确认模型能通。
4.1 版本验证
claude --version正常输出类似1.0.x (Claude Code)。这一步只验证二进制装好了，不涉及网络和 Key。
4.2 最小对话请求
进入交互模式：
claude第一次进会提示你确认一些设置，按提示走。然后直接输入一句最简单的话，比如：
你好，用一句话介绍你自己如果配置正确，几秒内会流式返回模型回复。看到回复就说明 Base URL、Key、Model ID 三件套全部生效，整条链路通了。
如果不想进交互模式，也可以用一次性命令：
claude -p "用一句话介绍你自己"-p是 print 模式，跑完直接输出结果退出，适合脚本里调用。
4.3 验证成功的样子
成功的标志有三个：命令不报错、有流式输出、回复内容合理。如果回复是空的或者报错，看下一节。
实测下来，第一次请求偶尔会慢一点，因为要建立连接和加载配置，第二次就快了。如果一直卡着不动超过 30 秒，多半是网络或 Base URL 问题，按第 5 节排查。
4.4 在项目里跑一次真实任务
对话通了之后，可以进一个项目目录试真实场景：
cd 你的项目目录 claude然后让它读一个文件：
读一下 package.json，告诉我项目用了哪些依赖它会调用工具读文件并总结。这一步验证的是 Agent 的工具调用能力，比单纯对话更能说明问题。如果这一步也通了，说明 Claude Code 本地安装和接入全部完成。
5. 常见报错排查：401、proxy、choices、OAuth
这一节列真实会遇到的报错和对应处理。按报错信息对号入座。
5.1 401 Unauthorized
最常见。报错长这样：
API Error: 401 {"error":{"message":"Invalid API key"}}原因就三个：Key 填错、Key 过期、Key 没配对 Base URL。检查顺序：先确认 settings.json 里的ANTHROPIC_API_KEY是完整的，没有多余空格或换行；再去控制台确认这个 Key 还有效；最后确认ANTHROPIC_BASE_URL是https://taotoken.net/api，末尾不要多加斜杠。
如果用的是环境变量，注意别和配置文件里的旧值冲突。环境变量优先级通常更高，检查一下当前终端有没有残留的旧 export。
5.2 local proxy failed / connection refused
报错类似：
Error: connect ECONNREFUSED 127.0.0.1:xxxx local proxy failed这说明 Claude Code 在尝试走一个本地代理端口，但那个端口没有服务。检查你有没有设过HTTP_PROXY或HTTPS_PROXY环境变量指向本地。清掉：
unset HTTP_PROXY unset HTTPS_PROXYWindows PowerShell：
Remove-Item Env:HTTP_PROXY Remove-Item Env:HTTPS_PROXY清完重开终端再试。这类报错和 Base URL 配置无关，纯粹是环境变量残留。
5.3 reading choices / unexpected response
报错里带reading 'choices'或Cannot read properties of undefined (reading 'choices')，通常是返回体格式和客户端预期不一致。可能原因：Base URL 填成了不兼容的端点，或者 Model ID 填错导致返回了错误结构。
处理：确认 Base URL 是https://taotoken.net/api，Model ID 是控制台里列出的可用模型名，别自己拼。改完重试。
5.4 OAuth / login 相关报错
如果报错提到 OAuth、login、authentication flow，说明 Claude Code 在走官方登录流程，而不是用你配的 Key。检查 settings.json 里有没有ANTHROPIC_API_KEY，有的话它会优先用 Key 而不是 OAuth。如果两个都配了可能冲突，删掉 OAuth 相关的配置，只留 Key。
5.5 claude 命令找不到
claude --version报 command not found。查npm config get prefix，把输出的路径加进 PATH。Windows 上还要确认 nvm 的 symlink 目录和 npm 全局目录都在 PATH 里。改完 PATH 必须重开终端。
5.6 版本冲突：node 版本不对
报错提到SyntaxError或Unsupported engine，多半是 node 版本太低。node -v确认是不是 20 以上。如果 nvm 切了但没生效，检查 PATH 里有没有残留的全局 node 路径排在 nvm 前面。
排查完这些，基本能覆盖 90% 的安装和接入问题。剩下的看具体报错信息，多数和 Key、Base URL、Model ID 三件套有关。
6. 装完之后：把 Claude Code 接进日常开发流
环境通了只是起点，真正省时间的是把它接进日常流程。
我自己的用法是：进项目目录直接claude，让它先读一遍代码结构，再提需求。比如「把这个模块的错误处理统一成 try-catch 并加日志」，它会自己找文件、改代码、跑测试。比手动翻文件快很多。
几个实用技巧。第一，把常用配置写进项目根目录的CLAUDE.md，Claude Code 启动时会读，相当于给它一份项目说明书，减少每次重复解释。第二，用claude -p "..."做一次性任务，适合塞进脚本或 CI。第三，模型选择上，日常改代码用响应快的，复杂重构用能力强的，在 settings.json 里换 Model ID 就行。
如果你要长期跑 Agent 任务、频繁调用模型，可以了解下 Coding Plan 这类方案，比按次调用更划算。想先试试模型对话效果，可以直接在模型对话页面发几条请求感受一下。API Key 在控制台创建，接入细节看接入文档。
整条链路走下来，核心就三件事：nvm 把 node 版本管住，npm 源配对，三件套填对。这三步稳了，Claude Code 本地安装就不会再反复折腾。
