Claude Code 完全指南：从安装配置到实战排错

打开终端输入claude回车。等来的不是一行欢迎信息而是claude: command not found。如果你是在 VS Code 的终端里跑的可能还会看到failed to run claude code: error: could not locate the claude cli on path这样的报错。这不是个例。很多人第一次接触 Claude Code都是先看了演示视频觉得“AI 直接在命令行里改代码”这件事很酷然后照着命令敲结果卡在了安装这一步。真正的问题不在命令有多复杂而在于大多数人把安装理解成了“装一个软件”但它实际是一条完整链路Node.js 环境、CLI 包、认证方式、模型接入、目录权限任何一环不对都跑不起来。这篇文章的目标是把这条链路一次讲透。我会从模型接入方式的选择讲起再到安装、VS Code 集成、第一次实战、提示词的正确用法最后给你一份常见报错排查表。看完你会明白Claude Code 这类工具真正改变的不是“你问一句、它答一句”的交互方式而是把一次性的问答变成了一条可以反复执行的开发流程。1. 先搞清楚Claude Code 解决的到底是不是“写代码”这件事1.1 它和 ChatGPT、Claude 网页版的本质区别如果用一句话概括Claude Code 不是一个聊天窗口而是一个在项目目录里工作的“驻场程序员”。你问 ChatGPT 或 Claude 网页版一个问题它给你一段代码你复制、粘贴、保存、运行报错再贴回去。这个循环里的每一步都要你亲自动手。而 Claude Code 不一样它直接生在项目根目录里能看到你的文件结构能读取指定文件能修改多个文件能在你的许可下执行命令然后根据命令结果继续调整代码。换句话说网页版给你的是“答案”Claude Code 给你的是“结果”。它把生成代码、写入文件、运行验证、修复错误这几个环节串了起来你只需要在旁边定义任务、审查改动、控制边界。第一次用的人很容易犯一个错误把它当成一个更聪明的代码生成器拿它去问“这个函数怎么写”。这不是它最强的场景。它最强的场景是处理跨多个文件、需要理解和修改既有代码、然后还要跑起来验证的完整任务。1.2 真正值钱的是把“开发循环”变成“可委托的流程”开发者每天大量时间花在哪里不全是写新代码更多是在重复一个循环读代码理解现状找到问题改一行跑一下看结果再改。这个循环在改 Bug、重构、补测试、排查报错时反复出现。Claude Code 提供的价值不是帮你把某一行写得更好而是把整个循环变成一个可以委托出去的任务。你负责描述“期望状态”它负责在文件系统里来回操作直到达到状态或主动停下来问你。这也是为什么它对“新接手一个项目”的场景特别有价值。传统方式是读文档、跑起来、点开关键文件光理解项目结构就要半天。有了它你可以让它先通读项目生成一份结构说明再基于这份说明开始改具体任务。这个过程中人的角色从“执行者”变成了“定义任务的人”和“审查结果的人”。不过要补充一句边界它能循环不代表它能替你做判断。关键决策、架构设计、上线审核这些仍然必须由人来完成。把它理解成一个执行力很强、但需要明确指令和严格验收的下属比把它理解成“全自动程序员”更准确。2. 安装之前先把“模型接入方式”定下来2.1 几种常见的接入路径安装 Claude Code 之前第一个要决定的不是命令而是你准备怎么让这个 CLI 连上大模型。不同选择决定了后续的环境变量、认证流程和配置方式完全不同。我见过太多人一上来就npm install -g anthropic-ai/claude-code装完才发现不知道怎么登录或者登录了但是模型调用不成功。这在工程上其实不是安装问题而是“接入方式没提前想清楚”。常见的方式大致有下面几类接入方式需要什么配置关键点适合谁官方订阅账号Anthropic 账号终端里执行/login走浏览器授权想体验完整功能接受订阅制官方 APIAPI Key设置ANTHROPIC_API_KEY按量付费想控制成本兼容网关/统一 API网关地址和 Key设置ANTHROPIC_BASE_URLANTHROPIC_AUTH_TOKEN或 API Key团队需要统一计费、日志、审计本地模型如 Ollama本地模型服务通过社区切换工具或兼容层接入数据敏感、离线环境、成本敏感这里不评价哪种方式绝对更好因为“更好”取决于你的模型能力需求、预算和数据合规要求。如果你的任务是学习 Agent 工作流、跑通流程那么用你能最快拿到的方式开始就好不要在“等一个完美模型”上卡太久。2.2 接入方式怎么影响后续配置接入方式一旦变了环境变量组合就会不一样。Claude Code 在读取配置时本质上是按“有没有显式设置端点”来决定走哪条路。如果你只设置了ANTHROPIC_API_KEY它默认会走 Anthropic 官方 API 端点。如果你额外设置了ANTHROPIC_BASE_URL它会把请求发到你指定的网关地址这时候认证用的可能是ANTHROPIC_AUTH_TOKEN也可能是 API Key取决于网关要求。如果你用本地模型通常不是直接把 Claude Code 指向 Ollama而是在中间加一个兼容层把 Anthropic API 格式翻译成本地模型能理解的格式。社区里常见的做法是配合 cc-switch 这类配置切换工具来管理多套供应商配置。我建议把这一套“供应商/端点/密钥”写在一个专门的配置文件里不要直接散落在终端会话中。这样以后切换供应商时只需要切换配置不需要重新研究环境变量。注意不同版本的 Claude Code 对环境变量的读取优先级可能略有差异。落地前先用claude --version确认版本再对照官方文档检查你使用的环境变量是否仍然有效。3. 从零到跑通环境、安装、PATH 三件事3.1 环境准备先检查 Node.jsClaude Code 是基于 Node.js 的 CLI 工具所以第一件事不是装 Claude Code而是确认 Node.js 版本。node -v npm -v一般来说Node.js 18 及以上版本是常见要求。版本太旧会导致安装报错或者运行时崩溃。如果你本机有其他 Node 版本管理工具比如 nvm建议先用一个稳定的 LTS 版本。对于国内网络环境如果 npm 安装速度很慢可以先用镜像源npm config set registry https://registry.npmmirror.com这一步是可选项不是必须。如果安装速度能接受保持默认源也没问题。3.2 安装 CLI 并验证确认 Node.js 环境没问题后执行npm install -g anthropic-ai/claude-code安装完成后先验证命令是否存在claude --version如果这一步提示claude: command not found不要急着重新安装。这通常不是安装失败而是 npm 的全局 bin 目录不在你 shell 的 PATH 里。在 macOS 和 Linux 上可以用下面命令查看npm bin -g然后把输出的目录加入 shell 配置文件.zshrc或.bashrc里的 PATH。在 Windows 上npm 的全局目录一般在%APPDATA%\npm同样需要确认它在 PATH 里。3.3 处理 VS Code 里最典型的那个报错很多人在 VS Code 的终端里运行 Claude Code 扩展会看到failed to run claude code: error: could not locate the claude cli on path.这个报错的意思是VS Code 扩展找不到claude这个可执行文件而不是 Claude Code 本身没装好。排查顺序是这样的先在一个新开的系统终端里执行claude --version确认 CLI 本身可用。如果系统终端可用VS Code 里不可用说明 VS Code 没有继承到你刚改完的 PATH。重启 VS Code不是重载窗口是完全退出再打开。如果重启后仍然报错检查 VS Code 的扩展设置手动指定claude可执行文件的路径。极少数情况下安装路径包含中文或空格也可能导致定位失败这时候可以考虑把 npm 全局目录改到一个无特殊字符的路径。3.4 完成认证安装和 PATH 都解决了接下来是认证。如果是官方订阅方式在项目目录下直接运行claude然后按提示执行/login会打开浏览器完成授权。如果是 API Key 方式设置环境变量export ANTHROPIC_API_KEY你的Key在 Windows PowerShell 里$env:ANTHROPIC_API_KEY你的Key这里有个很容易踩的坑环境变量只在当前终端会话里有效。如果你关掉终端再打开会发现又变成了未登录状态。所以建议把环境变量写入 shell 配置文件。macOS/Linux 写在~/.zshrc或~/.bashrcWindows 可以用setx或者通过 PowerShell Profile 持久化。4. 在 VS Code 里把 Claude Code 变成日常开发工具4.1 两种常见用法第一种直接在项目根目录打开 VS Code 的集成终端输入claude启动。这是最朴素也最稳定的方式适合大多数场景。第二种安装 Claude Code 官方扩展。装好之后在侧边栏可以直接打开 Claude Code 面板选中代码、查看改动、管理会话会更直观。扩展本身也是调用你系统里的claudeCLI所以在扩展里遇到“找不到 CLI”的问题回到 3.3 节的排查链路处理。我自己的习惯是写代码时用扩展面板因为可以选中代码作为上下文跑批处理或长时间任务时用终端因为输出更完整、不容易被面板刷新打断。4.2 项目里该建哪些配置文件进入项目目录启动 Claude Code 后第一件值得做的事是执行/init。这个命令会扫描项目生成一个CLAUDE.md文件里面记录项目结构、技术栈、常用命令等信息。之后每次会话启动Claude Code 都会自动读取这个文件相当于给它一份项目说明书。CLAUDE.md应该放什么不是放一篇长篇文档而是放那些“一个不熟悉项目的人最需要知道的事”项目用了什么框架和语言。目录结构哪些目录可以改、哪些不能碰。常见命令怎么装依赖、怎么跑测试、怎么启动。已知的坑比如某些测试依赖环境变量某些目录不能提交。配置层面还有两个常用命令/permissions管理文件操作和命令执行的权限策略。/config查看当前配置包括模型、供应商、输出模式等。4.3 权限设置是长期使用的核心Claude Code 执行命令和改文件之前需要你的授权。默认情况下它会在执行前询问你。这个设计一开始可能觉得麻烦但建议你克制住“全部自动放行”的冲动。权限策略可以按级别设置权限级别行为适用场景每次都询问每条命令和每次文件写入都要确认刚开始用、不熟悉它行为时自动允许文件编辑文件可以自动改命令仍需确认比较熟悉它的编辑模式之后自动允许指定命令对某些安全命令自动放行比如你明确知道某个命令无副作用全面禁止某些操作直接拒绝比如删除命令、生产环境操作我建议从“每次都询问”开始跑几次之后再根据实际需要放开。这个顺序能让你更好地理解它每一步在干什么也能在它跑偏时及时发现。5. 第一次实战从“改一个 Bug”到“多文件重构”5.1 最小任务让它修一个明确的 Bug不要第一次用就给它一个“优化一下项目”这种任务你会得到一个方向不明、改动范围不可控的结果。先从一个边界清晰的 Bug 开始。一个比较可靠的任务描述包含下面几部分问题表现什么操作会触发错误看到的报错是什么。相关文件如果知道直接告诉它入口文件和疑似出错的位置。期望状态修好之后应该是什么行为。验收方式跑什么命令或测试来确认。一个示例在用户登录接口中当用户输入错误密码时返回的错误码是 401 但前端期望的是 403。问题应该出在 auth.service.ts 的 authenticate 方法里。 请修改后跑一下相关测试确认错误码已经变成 403。注意这里没有要求它“直接改”而是给了背景和验收条件。Claude Code 会自己读文件、定位问题、修改并运行测试。它跑测试失败时会自己看输出再修。这整个循环不需要你介入这就是它和普通聊天的最大区别。5.2 进阶多文件改造前先要一份计划当你需要它做的事涉及多个文件时我强烈建议先别让它动手改而是让它先写一份实施方案我们要把项目中所有使用 /api/v1 前缀的接口迁移到 /api/v2 同时把错误处理方式从回调改为 Promise 风格。 先读一下项目结构和现有接口定义 给我一份改造计划包括涉及的文件清单、改动顺序和风险点。 确认后再动手。这段提示词里最关键的是最后一句“确认后再动手”。它把流程分成了两个阶段先输出计划你审查再执行。这一步能把很多风险提前暴露出来。比如你本来以为只涉及 3 个文件它读完全项目后告诉你其实有 17 个调用点。这种信息差在改造类任务里非常常见。先计划后执行能避免改到一半发现范围失控。5.3 让它补测试是把工具价值放大的关键操作我建议你在熟悉基本用法后多尝试让 Claude Code 写测试。它的稳定产出场景之一就是写单元测试和集成测试读取函数签名设计用例补齐边界条件然后运行并修复失败的测试。一个推荐的用法为 utils/date.ts 里的 formatDate 和 parseDate 方法补充单元测试。 覆盖合法输入、空值输入、时区差异、非法日期格式。 写完直接运行测试确保全部通过。测试任务天然适合 Agent因为它的验收标准明确测试通过或不通过。这比“代码写得好不好”这种主观标准更好判断出错时也更容易让 Claude Code 自己根据报错信息修复。6. 提示词工程在 Claude Code 里不是“咒语”是“施工边界”6.1 为什么这里和聊天的提示词不一样网上讨论提示词工程时很多人关注的是“怎么让模型生成更惊艳的文案”但在 Claude Code 这类编码 Agent 里提示词的核心作用不是激发灵感而是划定边界。写编码 Agent 的任务描述时有一个很实用的结构我一般叫它“五要素”角色让 Claude Code 扮演什么角色例如“资深前端工程师”。任务要完成什么尽量用结果而非过程描述。约束哪些不能做。比如“不要修改公共组件”“不要动测试数据”。输入需要读取哪些文件、参考哪些代码。验收怎么判断完成。比如“测试全部通过”“没有新增 ESLint 警告”。对比一下两个写法差的写法“优化一下登录模块。”好的写法“登录模块目前有重复的面板逻辑请把表单校验抽取成公共函数放在 utils/validators.ts 中并同步更新 LoginForm 和 RegisterForm 两个页面。完成后运行 npm run test确保测试通过。”第二种写法里任务边界、改动范围、验收标准都清楚了。Claude Code 不会猜你想要什么。6.2 CLAUDE.md 比提示词更值钱单次会话里提示词负责定义“这一次要做什么”而CLAUDE.md负责定义“这个项目一直要遵守什么”。后者才是真正值钱的部分。因为每次新建会话Claude Code 都会自动加载CLAUDE.md它会成为所有后续任务的默认上下文。相当于你给项目建立了一份“长期记忆”。你可以把CLAUDE.md看成一种被动的提示词工程。它不需要你每次重新输入但每一次决策它都在起作用。建议项目里的CLAUDE.md放到代码仓库里随项目演进新人接手时它也是最好的人机协作文档。6.3 把常用提示词沉淀成自定义命令如果你发现自己反复在写同一类任务描述比如“给这个模块补测试”“修复 ESLint 报错”“做代码 review”就可以把它保存成自定义命令。Claude Code 支持在项目的.claude/commands/目录下创建 Markdown 文件文件名就是命令名。例如创建.claude/commands/review.md里面写好 review 的完整提示词之后每次输入/review就能调用。这一步才是提示词工程的长期价值把一个好用的提示词模板沉淀下来变成团队可复用的资产。单人使用时它是效率工具多人协作时它是标准化流程。7. 报错排查与适用边界别把 Agent 当万能7.1 一份常见的报错排查表实际使用中报错并不复杂多数集中在环境、认证和路径三类。下面是一份按出现频率排序的排查表报错或现象大概率原因排查方向claude: command not foundnpm 全局目录不在 PATH执行npm bin -g把路径加入 shell 配置could not locate the claude cli on pathVS Code 找不到 claude 可执行文件重启 VS Code检查系统终端里 claude 是否可用手动配置扩展路径认证失败 / 401API Key 或 Token 无效或环境变量没有持久化确认环境变量在当前终端生效检查网关地址是否匹配Node 版本过低运行报语法错误或安装失败升级 Node 到 18 或当前 LTSPowerShell 安装报错执行策略限制脚本运行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUserOllama 连接失败本地模型服务未启动或端口不对确认 Ollama 服务已启动默认端口是 11434输出乱码终端编码与输出编码不一致Windows 下切换到 UTF-8或执行chcp 65001排查时记住一个顺序先看现象再看输入然后看环境接着看权限最后才怀疑是工具缺陷。很多卡住的情况其实只是没有给 Claude Code 足够的文件访问范围或者把它放错了启动目录。7.2 它适合什么不适合什么Claude Code 并不是什么地方都好用。把它的适用边界搞清楚比一直用它更重要。适合的场景中小型项目的日常开发单人或小团队。比较明确的 Bug 修复、测试补齐、ESLint/TypeScript 报错清理。多文件重命名、API 路径迁移、统一错误处理这类机械性重构。新接手一个代码库时的结构梳理。不适合的场景需要多人并行、有严格分支管理的大型项目它很容易制造超大改动。对代码审核有强合规要求的系统比如金融、医疗核心链路。模型能力不足以理解业务逻辑的复杂场景比如高度依赖领域经验的老旧系统。完全离线的内网环境如果没有事先准备本地模型和兼容层它就跑不起来。就算在适合的场景里也有一条底线所有改动必须经过 review。Agent 可以替你写但接管的是“执行”部分责任链仍然在你身上。建议每次让它批量修改文件前先确认改动范围每次接受 diff 前先看一眼它动了哪些文件。这个习惯花不了几分钟但能避免绝大多数“改着改着项目起不来了”的情况。7.3 长期使用的三条建议最后给真正打算长期用的人三条建议。第一从最小任务开始别上来就拆项目。先让它修一个 Bug、补一个测试、清理一个模块的报错跑通交互流程之后再逐步扩大任务范围。第二维护好CLAUDE.md。项目结构变了命令改了坑找到了随手更新进去。这个文件的长期积累价值会超过任何一次精心编排的提示词。第三把大任务拆成小步骤。每次只交付一个明确结果确认后再进入下一步。与其让它一口气改 20 个文件不如分 3 次、每次改 5 个再分别验收。这样即使出问题范围也是可控的。技术工具每隔几个月就会换代。Claude Code 这类编码 Agent 真正带来的改变不是让你少打字而是重新分配了你在一条开发流程里的精力和位置。你不需要变成不写代码的人你只是从“逐行执行”切换到了“定义结果、审查质量”。这是两条完全不同的工作路径而切换的入口很小找一个真实的小任务从安装开始跑通一次然后认真看一遍它改的 diff。这是理解这类工具最好的方式也是唯一能真正入门的方式。