1. 从零跑通 Claude CodeNode.js、npm 与 CLAUDE.md 的第一站刚接触 Claude Code 的开发者最容易卡住的地方往往不是模型能力而是环境本身Node.js 版本不对、npm 全局目录没进 PATH、CLAUDE.md 不知道写什么、MCP 配置写完没反应。这篇就把这条链路一次走完——从装 Node.js、用 npm 全局安装 Claude Code到写出第一份能约束 AI 行为的 CLAUDE.md再到接入一个 MCP 服务并验证工具调用回显。Claude Code 是什么简单说它是 Anthropic 推出的命令行 AI 编程智能体能读你的项目、改文件、跑命令、操作 Git。适合谁适合已经会用终端、想让 AI 直接动手改代码而不是只聊天的开发者。它需要 Node.js 18 以上通过 npm 全局安装核心配置文件是 CLAUDE.md扩展能力靠 MCP模型上下文协议。下面每一步都给可复制命令和验证动作照着敲就能跑通。2. 前置准备Node.js 与 npm 环境检查及版本踩坑在装 Claude Code 之前先把 Node.js 和 npm 这两块地基打牢。很多人跳过这步结果npm install -g报权限错、claude命令找不到回头排查更费时间。先检查版本。打开终端Windows 用 PowerShell 或 CMDmacOS/Linux 用默认终端执行node --version npm --versionClaude Code 要求 Node.js 18 及以上实测建议直接上 20 LTS 或 22 LTS兼容性更稳。如果node --version输出v16.x或提示command not found说明没装或版本太低。去 Node.js 官网下载 LTS 安装包Windows 选.msimacOS 选.pkg一路下一步即可。macOS 用户也可以用 Homebrewbrew install node20装完关掉终端重开再跑一次node --version确认。npm 会随 Node.js 一起装上不用单独装。这里有个高频坑Windows 上 npm 全局安装目录默认不在 PATH 里装完claude会提示「不是内部或外部命令」。先查全局目录npm config get prefix把这个路径比如C:\Users\你的用户名\AppData\Roaming\npm加进系统环境变量 Path重开终端。macOS/Linux 如果遇到EACCES权限错误不要用sudo npm install -g正确做法是改 npm 全局目录到用户目录mkdir -p ~/.npm-global npm config set prefix ~/.npm-global export PATH~/.npm-global/bin:$PATH把最后一行写进~/.bashrc或~/.zshrc并source一下后续全局安装就不会再要权限。这一步做完环境就算干净了。3. 可复制配置npm 安装 Claude Code 与 CLAUDE.md 模板环境就绪后全局安装 Claude Codenpm install -g anthropic-ai/claude-code装完验证claude --version能打印版本号就说明二进制已就位。接着进入你的项目目录启动一次交互会话cd your-project claude首次运行会引导你完成认证。如果你走的是兼容 Anthropic 协议的中转服务可以在项目根目录建一个.claude/settings.json把 Base URL、Key、Model ID 三件套写进去。下面是一个可复制的配置片段路径与字段名保持原样{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: 你的API密钥, ANTHROPIC_MODEL: claude-sonnet-4-5 } }Windows 用户如果习惯用环境变量CMD 里这样写注意是set不是exportset ANTHROPIC_BASE_URLhttps://taotoken.net/api set ANTHROPIC_API_KEY你的API密钥 set ANTHROPIC_MODELclaude-sonnet-4-5Key 的获取入口在控制台的 API Keys 页面模型 ID 以你实际开通的为准别照抄。配置写完后Claude Code 启动时会读取这些变量。接下来是 CLAUDE.md。它是项目级说明书Claude Code 每次进入项目都会读它用来对齐编码规范、构建命令、目录约定。放在项目根目录文件名严格大写。一份能用的模板# 项目说明 ## 技术栈 - 语言TypeScript 5.x - 框架React 18 Vite - 包管理pnpm ## 常用命令 - 安装依赖pnpm install - 本地开发pnpm dev - 构建pnpm build - 测试pnpm test ## 编码规范 - 组件用函数式禁止 class 组件 - 提交前必须通过 eslint 和 tsc 检查 - 新增依赖需在 PR 描述里说明理由 ## 目录约定 - src/components 放通用组件 - src/pages 放路由页面 - src/utils 放纯函数工具写 CLAUDE.md 的关键是「具体、可执行」。别写「代码要优雅」这种没法验证的话写「提交前跑pnpm lint」这种 AI 能直接执行的指令。文件越贴近项目真实情况AI 改出来的代码越少返工。4. 验证请求启动对话与 MCP 工具调用回显配置写完必须验证不然你不知道是环境问题还是配置问题。第一步启动会话claude进入交互界面后先问一个简单问题确认链路通帮我写一个读取 package.json 并打印 name 字段的 Node.js 脚本如果模型正常返回代码说明 Base URL、Key、Model ID 三件套生效。如果卡住或报错先看下一节的排查表。第二步验证 MCP。MCP 让 Claude Code 能调用外部工具比如查数据库、调 API。在项目根目录建.mcp.json加一个最简单的文件系统 MCP 服务{ mcpServers: { filesystem: { command: npx, args: [-y, modelcontextprotocol/server-filesystem, ./] } } }保存后重启claude在会话里输入列出当前目录下所有 .md 文件如果 Claude Code 通过 MCP 调用了文件系统工具并返回文件列表说明 MCP 链路通了。你会看到它先声明要调用某个工具再回显调用结果这就是「工具调用回显」。第一次跑npx会下载包稍等几秒。验证 MCP 是否被识别还可以在会话里输入/mcp部分版本支持会列出已加载的 MCP 服务。如果列表为空检查.mcp.json是否在启动目录、JSON 是否合法。JSON 里多个键值对之间别忘了逗号这是最常见的低级错误。三步验证做完——版本号、对话返回、MCP 回显——整条入门链路就算跑通了。5. 本篇常见错排查401、local proxy failed 与 reading choices入门阶段报错集中在几个固定位置对照下面逐条排。401 UnauthorizedKey 无效或没被读取。先确认ANTHROPIC_API_KEY拼写正确、没有多余空格。Windows 用set设的变量只在当前终端窗口有效换个窗口就没了建议写进.claude/settings.json而不是临时set。如果 Key 是从控制台复制的注意别把前后引号一起复制进去。local proxy failed / connection refusedBase URL 写错或服务不可达。检查ANTHROPIC_BASE_URL是否完整末尾不要多加/v1之类的路径除非文档明确要求。用curl单独测一下连通性curl -I https://taotoken.net/api能返回 HTTP 状态码说明网络层没问题问题在配置字段。reading choices / unexpected response模型返回格式不符合预期通常是 Model ID 写错或该模型不支持当前接口。把ANTHROPIC_MODEL换成你确认开通的 ID别用猜测的名字。如果换了还报检查 Base URL 是否指向了兼容 Anthropic 协议的端点。OAuth 相关报错首次启动时如果选了账号登录但环境不支持浏览器回调会卡在 OAuth 流程。这种情况直接改用 API Key 方式在.claude/settings.json里配好三件套跳过登录。claude 命令找不到回到第 2 节检查 npm 全局目录是否在 PATH。npm config get prefix的输出路径必须出现在echo $PATHWindows 用echo %PATH%里。MCP 工具不触发.mcp.json位置不对或 JSON 语法错。用node -e JSON.parse(require(fs).readFileSync(.mcp.json))验证语法没报错说明 JSON 合法。再确认启动claude时的工作目录就是.mcp.json所在目录。排查顺序建议固定先claude --version确认装上了再curl确认网络通再看配置文件字段最后看 MCP。由外到内别一上来就怀疑模型。6. 下一步把 CLAUDE.md 和 MCP 用起来环境跑通只是起点。真正让 Claude Code 好用的是持续打磨 CLAUDE.md——每次发现 AI 改错的地方就把对应规则补进去几轮下来它会越来越贴合你的项目习惯。MCP 也一样先接一个文件系统或 Git 服务用顺了再逐步加数据库、API 类工具别一次堆太多。如果你还没拿到 Key去 API Keys 页面创建一个再对照接入文档把 Base URL 和 Model ID 填对。想先感受模型对话效果可以直接在模型对话里试几句打算长期用 Claude Code 做编码和 Agent 任务Coding Plan 会更省心。配置过程中卡在某个报错优先翻接入文档里的排查章节多数 401 和连接问题那里都有对照说明。