1. 为什么你的 Claude Code 装完就跑不起来很多人第一次接触 Claude Code以为它跟 VS Code 插件一样点一下安装就能用。结果npm install -g敲完终端里输入claude迎面就是一句Unable to connect to Anthropic services或者Not logged in · Run /login然后卡在那里不知道下一步该干嘛。Claude Code 是 Anthropic 推出的终端原生 AI 编程助手它不是一个 IDE 插件而是一个跑在命令行里的 Agentic 工具。你给它一句自然语言指令比如“给这个模块加上 JWT 认证并补单元测试”它会自己去读文件、搜代码、跑命令、改代码、提交 Git。它的上下文窗口大约 200K token能一次性吃下整个项目的结构适合做跨文件重构和理解老代码。但它对运行环境有要求Node.js 版本不能太低网络出口要能通API key 要配对地方项目里还得有个CLAUDE.md告诉它你的规范。这四个环节任何一个出问题都会表现为“装完了但用不了”。这篇内容面向首次接触 Claude Code 的开发者把 Node.js 环境准备、npm 全局安装、API key 配置、CLAUDE.md 项目初始化这四个环节串成一条可复制的流程。每一步都给命令、给配置模板、给验证方法你跟着敲就能在本地跑通基础工作流。我试过在 Windows 和 macOS 上各走一遍踩过的坑会直接在对应步骤里标出来。核心检索词先摆在这里Claude Code 是什么、它能做什么、适合谁。简单说它适合那些愿意在终端里干活、想让 AI 真正动手改代码而不是只给建议的开发者。下面从环境准备开始。2. Node.js 与 npm 环境准备避开版本过低导致的安装报错Claude Code 通过 npm 分发所以第一步是把 Node.js 和 npm 准备好。这里最常见的坑是 Node.js 版本太低导致安装时报TypeError: Object not disposable。这个错误的根源是 Claude Code 用到了 ECMAScript 2024 里的Symbol.dispose特性而 Node.js v18.x 系列识别不了直接抛异常。先确认你当前的版本。打开终端Windows 用 PowerShell 或 CMDmacOS/Linux 用默认终端输入node -v npm -v如果node -v输出的是 v18 开头建议直接升级到当前 LTS 版本。Node.js 官网下载 LTS 长期维护版安装程序会自动覆盖旧版本。装完再跑一次node -v确认变成 v20 或更高。除了 Node.js还需要 Git。Claude Code 的 Git 集成功能依赖它来创建分支、提交代码、写 commit message。检查 Git 是否就绪git --version没有输出或提示找不到命令就去 Git 官网下载对应系统的安装包。Windows 上安装时保持默认选项即可安装完重新打开终端让 PATH 生效。环境变量这块npm 全局安装的目录最好在 PATH 里。Windows 默认全局目录是C:\Users\你的用户名\AppData\Roaming\npmmacOS/Linux 通常是/usr/local/bin或~/.npm-global/bin。验证方法npm config get prefix输出的路径应该出现在你的 PATH 环境变量中。如果不在Windows 可以在“系统属性 → 环境变量”里把该路径加进 PathmacOS/Linux 在~/.zshrc或~/.bashrc里加一行export PATH$PATH:$(npm config get prefix)/bin然后source一下。还有一个容易被忽略的点如果你在公司网络或受限网络环境下npm 的 registry 可能连不上。可以先测一下npm ping返回PONG说明 registry 可达。如果超时需要检查网络出口策略这部分不在本文展开但你要知道安装失败不一定是 Claude Code 的问题可能是 npm 源本身不通。环境准备好之后建议把 npm 自身也升一下避免旧版 npm 在处理某些包元数据时出问题npm install -g npmlatest这一步不是必须但能减少很多莫名其妙的报错。做完这些Node.js 和 npm 这一层就算稳了接下来进入正式安装。3. npm 全局安装 Claude Code 与 API key 配置模板安装命令本身很简单但配置 API key 的方式决定了你后面能不能顺利启动。先装npm install -g anthropic-ai/claude-codeWindows 上安装完成后包会落在C:\Users\你的用户名\AppData\Roaming\npm\node_modules\anthropic-ai\claude-code。macOS/Linux 则在 npm 全局目录下的node_modules/anthropic-ai/claude-code。装完验证版本claude --version能打印出版本号说明二进制已经就位。如果提示claude: command not found回到上一节检查 npm 全局目录是否在 PATH 里。接下来是 API key 配置。Claude Code 默认会尝试连 Anthropic 官方服务在国内网络环境下通常会报Unable to connect to Anthropic services。解决办法是把它指向一个兼容 Anthropic 接口协议的服务端点同时配上对应的 key 和模型 ID。配置文件的位置分两层用户级配置在~/.claude/settings.jsonWindows 上是C:\Users\你的用户名\.claude\settings.json项目级配置在项目根目录的.claude/settings.json。推荐先用用户级配置把全局跑通。一个可复制的settings.json模板如下路径和字段名保持原样{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的APIKey, ANTHROPIC_MODEL: claude-sonnet-4-20250514, ANTHROPIC_DEFAULT_HAIKU_MODEL: claude-haiku-4-20250514, ANTHROPIC_DEFAULT_SONNET_MODEL: claude-sonnet-4-20250514, ANTHROPIC_DEFAULT_OPUS_MODEL: claude-opus-4-20250514 }, includeCoAuthoredBy: false }这里三个关键字段必须成对出现Base URL、Key、Model ID。Base URL 指向兼容 Anthropic 协议的服务地址Key 填你申请到的令牌Model ID 填服务端支持的模型标识。ANTHROPIC_DEFAULT_HAIKU_MODEL、ANTHROPIC_DEFAULT_SONNET_MODEL、ANTHROPIC_DEFAULT_OPUS_MODEL这三个是 Claude Code 内部按任务复杂度分流用的建议都配上避免它在某些场景下找不到模型。如果你用 CC Switch 这类配置切换工具它本质上也是帮你写这个settings.json。手动改的好处是你清楚每个字段的含义出问题能自己排查。改完保存重新打开终端。还有一个引导检查的开关。第一次启动时 Claude Code 会走一个 onboarding 流程如果网络不通会卡住。可以在~/.claude.json注意不是 settings.json里加一行hasCompletedOnboarding: true这个文件在 Windows 上是C:\Users\你的用户名\.claude.json。加上之后启动会跳过引导检查直接进入主界面。配置写完先别急着敲claude下一节先做一次请求验证确认 key 和端点真的通。4. 验证请求与成功结果从 claude --version 到首次对话配置改完验证分三步走。第一步确认二进制可用claude --version第二步确认环境变量被正确读取。Claude Code 启动时会加载settings.json里的env字段你可以用一个简单命令看它是否生效claude config list如果这个子命令在你的版本里不存在直接进入第三步。第三步是实际发一次请求。在终端输入claude正常情况你会看到 Claude Code 的交互界面底部有输入提示。输入一句简单的话比如“用一句话说明这个目录里有什么文件”回车。它会调用模型读取当前目录然后返回结果。成功的标志有几个界面没有报Unable to connect to Anthropic services没有停在Not logged in · Run /login模型返回了内容而不是超时。如果返回了内容说明 Base URL、Key、Model ID 三件套都配对成功了。再验证一下模型分流是否正常。在对话里输入/model它会列出当前可用的模型。你应该能看到你在settings.json里配置的那几个。如果只显示一个或显示为空回去检查ANTHROPIC_DEFAULT_*_MODEL字段有没有拼错。还有一个实用的验证让它执行一个终端命令。输入“运行 git status 并告诉我结果”它会调用 Shell 执行然后把输出贴回来。这一步能验证它的工具调用链路是通的不只是聊天。如果你在项目目录里启动它还会自动读取CLAUDE.md。下一节讲怎么初始化这个文件以及它为什么重要。5. 常见报错排查401、local proxy failed 与 reading choices这一节对照真实报错给排查路径。第一个高频错误是 401API Error: 401 Unauthorized原因通常是 Key 不对或没带上。检查settings.json里ANTHROPIC_AUTH_TOKEN的值确认没有多余空格、没有换行、没有把sk-前缀漏掉。如果你用的是环境变量方式而不是配置文件确认变量名是ANTHROPIC_AUTH_TOKEN而不是ANTHROPIC_API_KEYClaude Code 认的是前者。第二个错误是 local proxy failedlocal proxy failed: connection refused这个通常出现在你本地起了代理但端口没通或者ANTHROPIC_BASE_URL指向了一个本地地址但服务没启动。检查 Base URL 是不是写成了http://localhost:xxxx这类本地地址如果是确认那个服务在跑。如果你用的是远程端点确认地址拼写正确没有多斜杠或少斜杠。第三个错误是 reading choicesError reading choices: unexpected end of JSON input这个多半是服务端返回了非预期格式常见于 Base URL 指向了一个不兼容 Anthropic 协议的端点。确认你的端点支持/v1/messages这个路径。可以在终端手动测一下curl -X POST https://taotoken.net/api/v1/messages \ -H Content-Type: application/json \ -H x-api-key: sk-你的APIKey \ -H anthropic-version: 2023-06-01 \ -d {model:claude-sonnet-4-20250514,max_tokens:64,messages:[{role:user,content:hi}]}返回 JSON 里有content字段说明端点正常。返回 HTML 或 404说明路径不对。第四个错误是 OAuth 相关OAuth error: invalid_grant这个出现在你试图用账号登录而不是 API key 时。如果你走的是 API key 模式不需要 OAuth直接在settings.json里配好 token 即可。如果界面一直提示/login说明它没读到你的配置检查配置文件路径和 JSON 格式是否合法。可以用python -m json.tool ~/.claude/settings.json验证 JSON 有没有语法错误。最后一个坑Windows 上路径里的反斜杠。在settings.json里写路径时用正斜杠或双反斜杠单反斜杠会被当成转义字符。比如C:/Users/你的用户名/.claude/settings.json是安全的写法。排查完这些基本能覆盖 90% 的启动失败场景。剩下 10% 多半是网络出口策略问题那就不在配置层面了。6. CLAUDE.md 项目初始化与长期编码工作流CLAUDE.md是 Claude Code 的项目级说明书。放在项目根目录每次会话启动时它会自动读取然后按里面的规则干活。没有这个文件它也能工作但生成的代码风格、命令习惯可能跟你的项目不一致。初始化很简单在项目根目录建一个CLAUDE.md内容按你的项目实际情况写。一个模板# 项目说明 这是一个 Node.js TypeScript 的后端服务使用 Express 框架。 ## 技术栈 - 运行时Node.js 20 - 语言TypeScript 5 - 框架Express 4 - 测试Jest - 包管理pnpm ## 常用命令 - 安装依赖pnpm install - 启动开发pnpm dev - 跑测试pnpm test - 构建pnpm build ## 编码规范 - 使用 2 空格缩进 - 函数优先用箭头函数 - 错误处理统一用 try/catch 自定义 AppError - 提交信息用 conventional commits 格式 ## 目录结构 - src/routes路由定义 - src/services业务逻辑 - src/models数据模型 - tests测试文件写完之后在项目目录里启动claude它会读取这个文件。你可以验证一下输入“这个项目用什么包管理器”它应该回答 pnpm 而不是 npm。如果答错了说明它没读到CLAUDE.md检查文件名大小写和位置。CLAUDE.md的另一个用法是放“禁止事项”。比如“不要修改src/config目录下的文件”“不要直接操作生产数据库”。Claude Code 默认对文件只有只读权限执行修改前会请求确认但把规则写进CLAUDE.md能减少它提出危险操作的概率。长期编码工作流方面如果你打算把 Claude Code 当成日常主力工具可以考虑用 Coding Plan 这类按周期计费的方式比按 token 计费更适合高频使用。配置方式跟上面一样只是 Key 和端点换成对应的即可。最后给一个实用技巧把CLAUDE.md纳入 Git 版本管理团队共享。这样每个人启动 Claude Code 时都遵循同一套规范生成的代码风格一致review 成本会低很多。项目初始化这一步做完你的 Claude Code 基础工作流就算完整跑通了。