002、安装与登录实战Node.js 环境、认证配置与故障排查上周五下午团队新来的同学小张在配置Claude Code时卡了整整三个小时。他跑过来找我屏幕上是满屏的红色报错核心问题就一个Error: Cannot find module anthropic-ai/claude-code。我扫了一眼他的Node.js版本——16.x。好问题找到了。Claude Code对Node.js版本有硬性要求低于18.x直接罢工而且文档里写得很隐晦只在安装日志的某个角落提了一句。今天这篇笔记就把这些坑一次性填平。Node.js 环境版本不对一切白费先检查你的Node.js版本。打开终端敲node-v如果输出是v16.x.x或更低别往下走了直接升级。Claude Code依赖ESM模块系统和一些较新的API比如fetch原生支持这些在Node 18才稳定。我推荐用nvm管理版本别用系统自带的包管理器去装容易版本冲突。# 安装nvm如果还没有curl-o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh|bash# 重新加载shell配置source~/.bashrc# 安装并切换到Node 20 LTS这里踩过坑18.x虽然能用但某些插件兼容性不如20nvminstall20nvm use20# 验证node-v# 应该输出 v20.x.x别这样写sudo apt install nodejs。Ubuntu默认源里的Node.js版本通常滞后两年装完大概率是16.x然后你会在各种诡异报错里浪费一整天。安装Claude Code全局还是项目级官方推荐全局安装但我在生产环境里吃过亏——全局安装会导致不同项目间的版本冲突。我的做法是开发机用全局CI/CD用项目级。全局安装适合个人开发npminstall-ganthropic-ai/claude-code安装完成后验证一下claude--version如果报command not found检查npm全局bin目录是否在PATH里。常见路径是~/.npm-global/bin或/usr/local/bin。用npm config get prefix查看然后手动加到shell配置里# 加到 ~/.bashrc 或 ~/.zshrcexportPATH$(npmconfig get prefix)/bin:$PATH项目级安装适合团队协作锁定版本# 在项目根目录npminit-y# 如果还没有package.jsonnpminstallanthropic-ai/claude-code --save-dev# 然后通过npx调用npx claude--version这里有个小技巧在package.json里加一个script{scripts:{claude:claude}}之后团队成员只需npm run claude不用关心全局安装路径。认证配置API Key的三种姿势Claude Code需要Anthropic的API Key才能工作。获取方式很简单去console.anthropic.com注册账号生成一个key。但怎么配置这里有三条路按优先级排列。方式一环境变量推荐最安全exportANTHROPIC_API_KEYsk-ant-xxxxxxxxxxxx别直接写在终端历史里用.env文件管理# 创建 .env 文件echoANTHROPIC_API_KEYsk-ant-xxxxxxxxxxxx.env# 然后 source 加载source.env别这样写把key硬编码在代码里或者提交到Git仓库。我见过有人把key写在README.md里然后被爬虫扫到一夜之间被刷了2000美元。方式二配置文件适合多环境切换Claude Code会在~/.claude/config.json里读取配置。手动创建{apiKey:sk-ant-xxxxxxxxxxxx,defaultModel:claude-sonnet-4-20250514}注意这个文件权限要设成600防止其他进程读取。方式三交互式登录适合快速测试直接运行claude第一次启动会提示输入API Key。输入后会自动保存到配置文件。但这种方式有个坑——如果你在CI环境里跑没有交互终端会直接卡死。所以CI环境必须用环境变量。故障排查我踩过的五个坑坑1Error: connect ECONNREFUSED网络问题。Claude Code需要访问api.anthropic.com如果你在公司内网大概率被防火墙拦了。检查代理设置# 查看当前代理echo$HTTP_PROXYecho$HTTPS_PROXY# 如果公司有代理设置exportHTTPS_PROXYhttp://proxy.company.com:8080坑2Error: 401 UnauthorizedAPI Key无效或过期。先检查环境变量是否真的生效echo$ANTHROPIC_API_KEY|head-c20# 只显示前20位避免泄露如果输出为空说明没加载成功。再检查.env文件格式别有多余空格或换行符。坑3Error: Rate limit exceeded免费账户有速率限制。解决方案升级到付费账户或者在请求间加延迟。Claude Code本身有重试机制但如果你并发调用太多还是会触发。我一般会在脚本里加sleep 1。坑4Error: Model not available你指定的模型名称不对。Claude Code默认使用claude-sonnet-4-20250514但如果你手动指定了claude-3-opus这种旧名称会报错。用claude models命令查看可用模型列表。坑5Error: EACCES: permission deniednpm全局安装时权限不足。别用sudo npm install这会导致权限混乱。正确做法是配置npm使用用户目录npmconfigsetprefix ~/.npm-globalmkdir-p~/.npm-global# 然后重新安装npminstall-ganthropic-ai/claude-code验证安装是否成功跑一个最简单的测试确认整个链路通了claude-p用一句话介绍你自己如果返回类似“我是Claude由Anthropic开发的AI助手”恭喜环境配置完成。如果报错回到上面的故障排查逐条核对。个人经验性建议版本锁定是血的教训。我在三个项目里遇到过“昨天还能用今天突然报错”的情况最后发现是npm自动升级了Claude Code的依赖。解决方案在package.json里锁定anthropic-ai/claude-code的精确版本别用^或~。API Key轮换要自动化。别手动复制粘贴写个脚本从密钥管理服务比如AWS Secrets Manager或Vault里拉取然后注入环境变量。我见过有人把key写在便签纸上贴在显示器旁边——别笑真事。日志是调试的命根子。Claude Code默认日志级别是info但遇到问题时要切到debugexportCLAUDE_DEBUGtrue claude-ptest日志会输出到~/.claude/logs/里面包含完整的HTTP请求和响应定位问题一针见血。别在生产环境用最新版。Claude Code的发布节奏很快有时一周两个版本。我习惯在测试环境先跑一周确认没有回归问题再推生产。用npm view anthropic-ai/claude-code versions查看所有版本挑一个稳定的。最后一条也是最重要的永远保留一个回滚方案。每次升级前记录当前版本号备份配置文件。我见过一次升级导致所有项目无法调用API回滚花了半小时那半小时里团队全员摸鱼。别问我怎么知道的。配置环境这件事看起来简单但细节决定成败。下一篇我会讲Claude Code的核心工作流——如何用MCP协议和自定义工具链把AI真正嵌入到你的开发流程里。
