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，装完才发现不知道怎么登录，或者登录了但是模型调用不成功。这在工程上其实不是安装问题，而是“接入方式没提前想清楚”。

常见的方式大致有下面几类：

这里不评价哪种方式绝对更好，因为“更好”取决于你的模型能力需求、预算和数据合规要求。如果你的任务是学习 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.js

Claude 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 本身没装好。

排查顺序是这样的：

1. 先在一个新开的系统终端里执行claude --version，确认 CLI 本身可用。
2. 如果系统终端可用，VS Code 里不可用，说明 VS Code 没有继承到你刚改完的 PATH。重启 VS Code，不是重载窗口，是完全退出再打开。
3. 如果重启后仍然报错，检查 VS Code 的扩展设置，手动指定claude可执行文件的路径。
4. 极少数情况下，安装路径包含中文或空格，也可能导致定位失败，这时候可以考虑把 npm 全局目录改到一个无特殊字符的路径。

3.4 完成认证

安装和 PATH 都解决了，接下来是认证。

如果是官方订阅方式，在项目目录下直接运行claude，然后按提示执行/login，会打开浏览器完成授权。如果是 API Key 方式，设置环境变量：

export ANTHROPIC_API_KEY="你的Key"

在 Windows PowerShell 里：

$env:ANTHROPIC_API_KEY="你的Key"

这里有个很容易踩的坑：环境变量只在当前终端会话里有效。如果你关掉终端再打开，会发现又变成了未登录状态。所以建议把环境变量写入 shell 配置文件。macOS/Linux 写在~/.zshrc或~/.bashrc，Windows 可以用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 开始。

一个比较可靠的任务描述包含下面几部分：

1. 问题表现：什么操作会触发错误，看到的报错是什么。
2. 相关文件：如果知道，直接告诉它入口文件和疑似出错的位置。
3. 期望状态：修好之后应该是什么行为。
4. 验收方式：跑什么命令或测试来确认。

一个示例：

在用户登录接口中，当用户输入错误密码时，返回的错误码是 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 的任务描述时，有一个很实用的结构，我一般叫它“五要素”：

1. 角色：让 Claude Code 扮演什么角色，例如“资深前端工程师”。
2. 任务：要完成什么，尽量用结果而非过程描述。
3. 约束：哪些不能做。比如“不要修改公共组件”“不要动测试数据”。
4. 输入：需要读取哪些文件、参考哪些代码。
5. 验收：怎么判断完成。比如“测试全部通过”“没有新增 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 Code 足够的文件访问范围，或者把它放错了启动目录。

7.2 它适合什么，不适合什么

Claude Code 并不是什么地方都好用。把它的适用边界搞清楚，比一直用它更重要。

适合的场景：

• 中小型项目的日常开发，单人或小团队。
• 比较明确的 Bug 修复、测试补齐、ESLint/TypeScript 报错清理。
• 多文件重命名、API 路径迁移、统一错误处理这类机械性重构。
• 新接手一个代码库时的结构梳理。

不适合的场景：

• 需要多人并行、有严格分支管理的大型项目，它很容易制造超大改动。
• 对代码审核有强合规要求的系统，比如金融、医疗核心链路。
• 模型能力不足以理解业务逻辑的复杂场景，比如高度依赖领域经验的老旧系统。
• 完全离线的内网环境，如果没有事先准备本地模型和兼容层，它就跑不起来。

就算在适合的场景里，也有一条底线：所有改动必须经过 review。Agent 可以替你写，但接管的是“执行”部分，责任链仍然在你身上。

建议：每次让它批量修改文件前，先确认改动范围；每次接受 diff 前，先看一眼它动了哪些文件。这个习惯花不了几分钟，但能避免绝大多数“改着改着项目起不来了”的情况。

7.3 长期使用的三条建议

最后，给真正打算长期用的人三条建议。

第一，从最小任务开始，别上来就拆项目。先让它修一个 Bug、补一个测试、清理一个模块的报错，跑通交互流程之后，再逐步扩大任务范围。

第二，维护好CLAUDE.md。项目结构变了，命令改了，坑找到了，随手更新进去。这个文件的长期积累价值，会超过任何一次精心编排的提示词。

第三，把大任务拆成小步骤。每次只交付一个明确结果，确认后再进入下一步。与其让它一口气改 20 个文件，不如分 3 次、每次改 5 个，再分别验收。这样即使出问题，范围也是可控的。

技术工具每隔几个月就会换代。Claude Code 这类编码 Agent 真正带来的改变，不是让你少打字，而是重新分配了你在一条开发流程里的精力和位置。你不需要变成不写代码的人，你只是从“逐行执行”切换到了“定义结果、审查质量”。这是两条完全不同的工作路径，而切换的入口很小：找一个真实的小任务，从安装开始，跑通一次，然后认真看一遍它改的 diff。

这是理解这类工具最好的方式，也是唯一能真正入门的方式。