1. 环境准备从零搭建 Claude Code 的运行底座1.1 为什么 Claude Code 值得折腾Claude Code 是 Anthropic 推出的一款命令行 AI 编程助手它跟你在网页上跟 AI 聊天完全不是一回事。网页版是你贴代码、它给建议来回复制粘贴Claude Code 直接跑在你的终端里能读你本地的项目文件、能执行命令、能改代码、能跑测试相当于给你配了一个坐在旁边、随时能上手干活的编程搭档。我第一次用它的时候感觉最明显的变化是以前问 AI 一个问题得把相关代码一段段贴过去还得解释上下文现在直接在项目根目录敲一句claude它自己就知道项目结构、依赖关系、甚至能看懂你的 git 历史。这个体验上的差距用过就回不去了。不过 Claude Code 对运行环境有要求不是双击一个 exe 就能跑起来的东西。它依赖 Node.js 运行时需要通过 npm 全局安装还得配置 API Key 才能调用模型。这一套流程对老手来说十分钟搞定对刚接触命令行的朋友可能会卡在几个地方。这篇教程就是把我自己踩过的坑、验证过的步骤完整梳理一遍让你少走弯路。适合读这篇的人有基本电脑操作能力、想用 AI 辅助编程但还没配好环境的开发者已经装了 Node.js 但 npm 命令报错的朋友以及想了解 Claude Code 到底怎么用、值不值得花时间折腾的技术爱好者。1.2 Node.js 版本选择与下载渠道Claude Code 官方要求 Node.js 18 及以上版本。我实测下来18.20.4 LTS 和 20.x LTS 都能正常跑但建议直接用 20.x LTS因为 18.x 已经进入维护末期某些 npm 包的兼容性会逐渐出问题。下载渠道只有一个推荐Node.js 官网。别去什么第三方软件站下载那些站点的安装包经常被捆绑东西而且版本老旧。官网地址直接搜“Node.js 官网下载”就能找到进去之后选 LTS 版本Windows 选.msi安装包macOS 选.pkgLinux 用包管理器或者二进制包都行。这里有个细节Windows 用户下载的时候注意区分 64 位和 ARM64。大部分台式机和笔记本是 x64但如果你用的是 Surface Pro X 或者某些骁龙处理器的轻薄本那就是 ARM64。装错了版本后面 npm 安装原生模块的时候会报编译错误排查起来很烦。提示安装 Node.js 的时候安装程序会问你要不要自动安装必要的工具比如 Python 和 Visual Studio Build Tools。如果你以后要装需要编译的原生模块建议勾上如果只是跑 Claude Code不勾也行能省不少安装时间。1.3 Windows 下的安装步骤与 PATH 配置Windows 上安装 Node.js 基本就是一路 Next但有两个地方要留意。第一个是安装路径。默认会装到C:\Program Files\nodejs\这个路径没问题但如果你之前装过旧版本安装程序可能不会自动覆盖而是装到另一个目录导致 PATH 里有两个 node 路径命令行调用的版本跟你以为的不一样。所以装之前先去“控制面板-程序和功能”里看看有没有旧版 Node.js有的话先卸载干净。第二个是 PATH 环境变量。正常情况下安装程序会自动把 Node.js 的安装目录加到系统 PATH 里但有时候因为权限问题或者杀毒软件拦截这一步会失败。验证方法很简单装完之后打开一个新的命令提示符CMD或者 PowerShell输入node -v和npm -v如果都能输出版本号说明 PATH 配置没问题。如果提示“不是内部或外部命令”那就得手动加 PATH。操作路径是右键“此电脑” → 属性 → 高级系统设置 → 环境变量 → 在“系统变量”里找到 Path → 编辑 → 新建 → 把 Node.js 的安装目录比如C:\Program Files\nodejs\加进去。加完之后一定要关掉所有命令行窗口重新打开因为 PATH 的变更不会自动同步到已经打开的终端。macOS 和 Linux 用户相对省心用 nvm 管理 Node.js 版本是最稳妥的做法。nvm 可以让你在同一台机器上装多个 Node.js 版本随时切换不会互相干扰。安装 nvm 之后nvm install 20然后nvm use 20就搞定了。1.4 npm 镜像源配置解决安装慢和超时的问题npm 默认的 registry 是国外的服务器国内直接访问经常慢得让人想砸键盘有时候还会超时导致安装失败。解决办法就是换成国内镜像源。换源命令很简单npm config set registry https://registry.npmmirror.com这条命令会把 npm 的默认下载源指向国内镜像。换完之后可以用npm config get registry确认一下输出应该是你设置的那个地址。如果你只想临时用一次镜像源不想改全局配置可以在安装命令后面加--registry参数npm install -g anthropic-ai/claude-code --registry https://registry.npmmirror.com我个人的习惯是全局换源因为平时装其他包也用得上。但要注意有些公司内部有私有 npm 源如果你在公司网络环境下换源之前先确认一下会不会跟内部源冲突。还有一个坑如果你之前设置过代理npm 的代理配置可能会覆盖镜像源设置。检查方法是npm config get proxy和npm config get https-proxy如果输出不是null说明有代理配置可能需要清掉npm config delete proxy npm config delete https-proxy2. Claude Code 安装与 API Key 配置2.1 全局安装 Claude Code 的正确姿势Node.js 和 npm 都就绪之后安装 Claude Code 本身只需要一条命令npm install -g anthropic-ai/claude-code-g表示全局安装这样你在任何目录下都能直接敲claude命令。安装过程大概几十秒到几分钟不等取决于网络速度。安装完成后验证是否成功claude --version如果输出了版本号说明安装成功。如果提示“claude 不是内部或外部命令”大概率是 npm 全局安装目录没有加到 PATH 里。用npm config get prefix可以查看 npm 全局安装路径然后把这个路径加到系统 PATH 里就行。Windows 用户特别注意如果你用的是 PowerShell可能会遇到脚本执行策略的限制报错信息类似“无法加载文件 npm.ps1因为在此系统上禁止运行脚本”。这不是 npm 的问题是 PowerShell 的安全策略。解决办法是以管理员身份打开 PowerShell执行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser然后输入Y确认。这个操作是允许当前用户执行本地脚本和来自可信来源的远程签名脚本安全性上是可以接受的。2.2 API Key 获取与配置的三种方式Claude Code 需要 API Key 才能调用模型。目前主要有两个渠道Anthropic 官方 API 和 OpenRouter 等第三方聚合平台。Anthropic 官方 API Key 的获取流程是注册 Anthropic 账号 → 进入控制台 → 找到 API Keys 页面 → 创建新的 Key。创建的时候会让你设置权限和额度限制建议一开始设一个较低的月度限额防止意外消耗。Key 的格式通常以sk-ant-开头创建后只显示一次一定要立刻复制保存。OpenRouter 是一个模型聚合平台除了 Claude 之外还能调用其他家的模型。它的 API Key 格式以sk-or-开头获取方式也是注册后在控制台创建。OpenRouter 的好处是可以用一个 Key 访问多个模型方便对比效果缺点是中间多了一层转发偶尔会有延迟波动。配置 API Key 有三种方式我按推荐程度排序第一种是环境变量方式也是我最推荐的。Windows 下在 PowerShell 里执行$env:ANTHROPIC_API_KEY你的Key但这只在当前会话有效关掉窗口就没了。要永久设置的话用系统环境变量界面添加或者用setx命令setx ANTHROPIC_API_KEY 你的KeymacOS 和 Linux 下加到~/.bashrc或~/.zshrc里export ANTHROPIC_API_KEY你的Key第二种是 Claude Code 的配置文件方式。首次运行claude命令时它会引导你完成配置包括输入 API Key。这个 Key 会保存在用户目录下的配置文件中后续不用重复输入。第三种是每次启动时通过命令行参数传入适合临时切换 Key 的场景claude --api-key 你的Key注意API Key 是敏感信息不要直接写在代码里提交到 git 仓库也不要在截图里暴露完整 Key。我见过有人把 Key 贴在技术论坛求助结果被人扫到之后一夜之间额度被刷光。如果不小心泄露了立刻去控制台删除旧 Key 重新生成。2.3 验证配置是否生效配置完之后进入你的项目目录敲claude启动。如果一切正常你会看到 Claude Code 的交互界面可以直接用自然语言跟它对话。验证 API Key 是否生效的最快方法是问它一个需要读取文件的问题比如“这个项目的入口文件是哪个”。如果它能正确读取并回答说明 Key 配置没问题。如果报错401 Unauthorized或者api key is required那就是 Key 没配好或者已经失效。常见的 401 错误原因有几个Key 复制的时候多了空格或者换行Key 已经被删除或过期环境变量名拼错了比如写成了ANTHROPIC_KEY而不是ANTHROPIC_API_KEY或者你用的是 OpenRouter 的 Key 但没配置对应的 base URL。2.4 在 VS Code 中集成 Claude Code虽然 Claude Code 是命令行工具但它跟 VS Code 配合起来用体验更好。有两种集成方式。第一种是在 VS Code 的内置终端里直接运行claude。这样你一边看代码一边跟 Claude 对话它改完代码你立刻能在编辑器里看到变化。VS Code 的终端默认就是 PowerShell 或者 bash跟独立终端没区别。第二种是安装 Claude Code 的 VS Code 扩展。在扩展市场搜索“Claude Code”就能找到安装之后会在侧边栏加一个面板交互方式更接近聊天窗口。不过扩展的功能更新通常比命令行版本慢一些我一般还是用终端方式。如果你在 VS Code 终端里遇到npm.ps1无法加载的报错跟前面说的一样改一下 PowerShell 执行策略就行。或者把 VS Code 的默认终端从 PowerShell 换成 CMD也能绕过这个问题。3. 实操上手用 Claude Code 完成一个真实任务3.1 启动与基本交互进入一个你熟悉的项目目录敲claude回车。第一次启动会稍微慢一点因为要初始化环境。启动后你会看到一个提示符直接输入你的需求就行。Claude Code 的交互逻辑跟聊天窗口不太一样。它更像一个能执行操作的助手你说“帮我看看这个项目用了什么框架”它会去读package.json然后告诉你你说“把 utils.js 里的日期格式化函数改成用 dayjs”它会找到那个函数、修改代码、甚至帮你装 dayjs 依赖。我常用的几个开场指令“介绍一下这个项目的结构”——快速了解陌生项目“最近一次 git commit 改了什么”——回顾变更“帮我找出所有硬编码的 API 地址”——代码审查3.2 让 Claude Code 读取和理解项目Claude Code 启动时会自动读取当前目录下的关键文件比如package.json、README.md、.gitignore等。但它不会一次性把所有文件都读进来而是根据你的问题按需读取。如果你想让它了解某个特定模块可以直接说“读一下 src/services 目录下的所有文件”。它会逐个读取并总结。这个过程消耗的 token 比较多所以项目大的时候建议缩小范围。有个技巧在项目根目录放一个CLAUDE.md文件里面写上项目的基本信息、技术栈、代码规范、常用命令等。Claude Code 启动时会自动读取这个文件相当于给它一份项目说明书。这样你就不用每次重复解释项目背景了。3.3 代码修改与命令执行实战Claude Code 最核心的能力是改代码。你描述需求它定位文件、修改内容、然后告诉你改了什么。改完之后你可以用git diff查看具体变更确认没问题再提交。它还能执行命令。比如你说“跑一下测试”它会执行npm test并把结果反馈给你。如果测试失败你可以直接说“帮我修复失败的测试”它会分析错误信息然后尝试修改代码。但这里有个重要的注意事项Claude Code 执行命令之前会征求你的确认不要无脑点同意。特别是涉及删除文件、修改系统配置、安装全局包这类操作一定要看清楚它要执行什么命令再确认。我一般会扫一眼命令内容确认没有rm -rf这种危险操作。3.4 卸载与重装如果 Claude Code 出了问题需要重装卸载命令是npm uninstall -g anthropic-ai/claude-code卸载之后重新执行安装命令即可。配置文件通常保存在用户目录下卸载不会自动删除所以重装后之前的配置还在。如果想彻底清理手动删掉配置目录就行。4. 常见报错与排查速查4.1 npm 相关报错报错信息原因解决方法npm 无法加载文件 npm.ps1因为在此系统上禁止运行脚本PowerShell 执行策略限制管理员运行 PowerShell执行Set-ExecutionPolicy RemoteSigned -Scope CurrentUsernpm 无法将“npm”项识别为 cmdletNode.js 未安装或 PATH 未配置检查 Node.js 是否安装手动添加 PATHnpm warn deprecated node-domexception依赖包过时警告不影响使用可忽略或更新相关依赖安装超时或卡住默认源访问慢切换国内镜像源npm config set registry https://registry.npmmirror.com4.2 API Key 相关报错报错信息原因解决方法401 Unauthorized: incorrect api keyKey 错误或失效检查 Key 是否复制完整重新生成api key is required in authorization header未配置 Key设置环境变量或配置文件no api key for provider route使用了不支持的模型路由检查模型名称和 provider 配置4.3 网络与连接问题如果 Claude Code 启动后一直卡在连接阶段先检查网络是否能正常访问 API 端点。可以用curl测试一下curl -I https://api.anthropic.com如果返回 200 或 401 都说明网络通返回超时就是网络问题。这种情况下检查系统代理设置或者换个网络环境试试。4.4 我的避坑经验汇总第一个坑Node.js 版本太老。我一开始用系统自带的 Node.js 16装 Claude Code 的时候各种报错。后来用 nvm 装了 20.x LTS问题全没了。所以别省这一步直接上 LTS 版本。第二个坑API Key 环境变量在 IDE 里不生效。VS Code 启动的时候会继承系统的环境变量但如果你是在 VS Code 打开之后才设置的环境变量它不会自动刷新。解决办法是设置完环境变量后完全退出 VS Code 再重新打开。第三个坑项目太大导致响应慢。Claude Code 读取文件是按需的但如果你的问题描述太宽泛它可能会尝试读取大量文件导致响应时间很长。尽量把问题描述得具体一些缩小范围。第四个坑误删文件。Claude Code 执行删除操作之前会问你但有时候手快点了同意。建议在重要项目里先用 git 确保所有变更可回滚这样即使误操作也能恢复。4.5 性能优化小技巧如果你觉得 Claude Code 响应慢可以试试这几个方法。一是把不相关的大目录加到.gitignore或者.claudeignore里减少它扫描的文件数量。二是尽量用具体的问题代替宽泛的问题减少不必要的文件读取。三是如果项目依赖很多第一次启动会慢一些后续有缓存会快很多。另外Claude Code 的会话是有上下文长度限制的。如果一次对话轮次太多早期的上下文会被截断。重要信息建议在CLAUDE.md里写清楚而不是依赖对话历史。我在实际使用中的体会是Claude Code 最大的价值不是帮你写多少代码而是帮你省去在文件和文档之间来回切换的时间。你描述需求它去执行你审查结果这个循环一旦跑顺了效率提升是很明显的。但前提是环境得配好Key 得配对不然光折腾报错就够消耗耐心的。希望这篇教程能帮你把环境这关顺利过了后面的使用就是熟能生巧的事。
