Claude Code 保姆级教程：从安装配置到高效编程实战

最近这几个月，我身边无论后端还是前端的朋友，基本都在聊一个叫 "Claude Code" 的东西。它不是又一个网页版聊天机器人，而是一个能直接住进你项目里的命令行 AI 协作者——你自己看代码、改文件、敲命令，它也能看、能改、能敲，还比大多数人手快。这篇保姆级教程就是把我从零开始装好、登录、接模型、调上下文、接 VSCode、再一路用到顺手这套完整流程里的经验和坑全盘端出来，基于 2026 年这会儿最新的 v2.x 版本，适用 Windows、Linux 和 macOS。前端、后端、嵌入式甚至写文档的人都值得读一读，尤其是那些被"能不能装、能不能连上"这种破事卡住的朋友。

1. 先说清楚：Claude Code 到底是什么

1.1 一个会干活的命令行 Agent，不是一个聊天框

我第一次听人安利 Claude Code 时，心里想的是"命令行里的 ChatGPT 呗"。真用起来才发现完全不是一回事。网页版 ChatGPT 或者 Claude 网页版，是你提问、它回答，然后你把答案复制到编辑器里，手工改、手工保存、手工跑测试。Claude Code 是直接跑在你项目目录里，你能让它"去看下 src 下哪个文件最可疑""给这个组件补个单元测试""把刚才那个报错修了"。它可以读文件、写文件、执行 shell 命令、跑测试跑构建，然后根据结果继续调。

这个差别用一句糙话概括：别人给你指路，它直接开车。Claude Code 本质上是一个"agentic coding tool"，也就是智能体式编码工具。它不需要你每一步都手动确认"下一步干嘛"，而是基于当前项目状态持续决策。它会自己列出改动计划、动手改、跑测试、发现挂了继续修，直到任务完成为止。你需要的技能，更多是"把需求说清楚"和"在关键节点踩刹车"。

1.2 它能干什么，不能干什么

能干的活很多：

• 代码理解与重构：丢给它一个几万行的老项目，让它梳理模块关系、找出重复代码、给出重构方案并直接落地。
• 测试补全：让它为指定函数补边界测试，它真的会先读实现、列用例、写测试、再跑一遍。
• 报错排查：你把报错贴给它，它会自己看堆栈、查文档、改代码、重试。
• 多文件跨模块修改：改一个接口，它能顺着调用链把上游下游相关文件一起改掉。
• 非代码场景：写 CHANGELOG、生成项目文档、写周报草稿、甚至起草一份离谱的 README，都行。

它不擅长的事也得分清：

• 它不知道你脑子里没写出来的需求。你要是不说清楚"只改后端，不动前端"，它可能顺手把前端也重构了一遍。
• 涉及公司密钥、生产环境数据库、线上权限变更的这些高危操作，它敢问你敢让它做吗？这种活不适合放手让它自动干。
• 真正需要"拍板"的架构决策，它能给建议，但背锅的得是你。

1.3 适合谁，不适合谁

适合的人是：日常有大量编码、调试、重构、写测试任务的技术人；一个人要撑好几个项目、经常在多语言多技术栈里横跳的"全栈杂工"；还有像我这样长期在终端里干活、不爱被 IDE 各种弹窗打断的人。

不适合的人是：完全没写过代码、指望用对话凭空生成一个能上线的商业项目的新手——你可以当它是脚手架加速器，但别当它是程序员平替；还有对代码质量有洁癖、但完全不愿意做代码审查的人，用它之前得先接受"AI 写的代码要人审"这个底线。

2. 安装：三分钟跑起来

2.1 先检查 Node.js 环境

安装 Claude Code 最主流的路径是通过 npm，所以第一步是确认你的机器上有 Node.js。先打开终端跑node -v，正规做法是要求 18 以上的版本。我见过很多人在老项目里带的 Node 16 上折腾安装，结果各种报错，浪费一小时之后把 Node 升到 20 才算消停。

如果你机器上完全没有 Node.js，或者版本太老，建议装一个 nvm 来管理 Node 版本。别用那种从网上随便下的"一键安装包"，版本混乱后面有你受的。nvm 装好后执行：

nvm install 20 nvm use 20 node -v

看到 v20 开头的版本号，环境这步就过了。要注意的是，Windows 用户如果用的是原生命令行，尽量把终端换成 Windows Terminal 或者 Git Bash，后面跑 claude 命令时提示排版和按键绑定都正常一些。

2.2 npm 装还是桌面版装

目前安装方式主要两种：命令行版和桌面版。

命令行版安装命令一行搞定：

npm install -g @anthropic-ai/claude-code

装完验证一下：

claude --version

能看到类似Claude Code v2.1.278这样的版本号，就算成了。-g是全局安装，意味着在任何目录下都能敲 claude。如果你常年切换 Node 版本，且用了 nvm，大概率会遇到"装完了但命令找不到"的问题，这个我在第 7 章的排查表里专门说。

桌面版（Claude Code Desktop）适合不太习惯终端的人。官方提供了安装包，装好后是一个带图形界面的应用，本质上是把同一个 CLI 引擎套了一层壳。国内用户如果下载安装包慢，优先让朋友传一份或者从可靠渠道获取安装包，反正桌面版底层和命令行版是同一套东西，日常体验差别不大。

2.3 各平台的坑：Windows、Linux、macOS

Windows 上我建议把安装路径里的空格问题算进去，npm 全局目录如果带空格偶尔会有奇怪问题。用 nvm-windows 的同学记得统一版本，别系统里同时存在 nvm 管的 Node 和独立安装版 Node，两个抢 PATH 时 claude 命令时有时无，搞得人很崩溃。

Ubuntu 等 Linux 发行版上，卡得最多的是权限问题。你敲npm install -g时如果提示权限不足，别急着sudo npm——sudo 会把全局包装到 root 目录，之后你自己用户下可能又找不到命令。优先解决 npm 全局目录权限，或者直接跑npm install -g前先whoami确认当前用户。

macOS 上相对干净，但如果你用 zsh，留意 npm 全局 bin 目录有没有加到 PATH。老手一般会把export PATH="$HOME/.npm-global/bin:$PATH"写进.zshrc，这一步做好了后面少很多事。

2.4 装完怎么验证

安装完成先别急着干活，做三件事：第一，claude --version看版本；第二，在任意空目录里敲claude，看能不能进入交互界面；第三，退出后看一眼~/.claude目录有没有自动生成，这是它存放配置、日志、技能包的目录，后面所有个性化设置基本都在这。

进到一个空目录后它会提示要不要初始化项目设置，第一次你随便选都行，后面想改可以直接改配置文件。

3. 认证与模型接入

3.1 官方账号登录 vs API Key

首次运行claude，会跳出登录流程。你有两条路：

官方订阅账号（Pro/Max）登录后使用，适合个人日常使用，按订阅套餐花钱，通常限制一定使用量内比较爽。命令是交互式登录：

claude /login

API Key 方式适合按量计费的用户和团队产品。你可能需要提前在 Anthropic 开放平台上创建一个 API Key，然后设置环境变量：

export ANTHROPIC_API_KEY=你的key

之后启动 claude 就不用再登录了。注意 API Key 属于敏感信息，写入终端历史或者配置文件里都要小心，别用明文提交到 Git 仓库。

3.2 接 DeepSeek：低成本替代方案

很多人被官方账号的地区覆盖或者支付卡住，这里我直接推荐一个合规且便宜的操作：用 DeepSeek 的 Anthropic 兼容接口接入 Claude Code，请求转发到 DeepSeek，模型则用 DeepSeek 自家模型。这类做法相当于给 Claude Code 换了一个"后端大脑"，终端界面和操作习惯完全不变。

操作非常简单，设置两个环境变量后启动：

export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic export ANTHROPIC_AUTH_TOKEN=你的DeepSeek_API_Key claude

ANTHROPIC_BASE_URL是请求转发地址，DeepSeek 官方提供了对应的 Anthropic 兼容端点；ANTHROPIC_AUTH_TOKEN填 DeepSeek 的 API Key。实测下来，日常代码补全、重构、Debug 场景都挺稳，成本也比官方 API 低不少。DeepSeek 也在持续更新模型版本，如果你正好赶上新版本发布，在模型名配置里切到对应的 deepseek 模型即可。

3.3 "might not be available in your country" 怎么办

安装或者启动时看到note: claude code might not be available in your country这类提示，别慌，这多半是官方服务对部分地区不提供直连支持，提示你当前网络环境连不到官方服务。遇到这个情况，我的建议是：一是检查当前网络环境是否允许访问对应官方服务；二是如果确实连不上，别折腾那些不稳定、不合规的路子，直接转 3.2 的兼容 API 接入方案。接口地址指向你自己能访问的 API 服务商，问题就绕过去了。

另外，接入第三方模型服务时注意看服务商的合规声明和使用条款，大家干干净净地在规则内用工具，这样项目才能长期跑得起来。

3.4 环境变量与转发地址的基础知识

这里把原理说透一点。Claude Code 本身是一个壳，它默认往 Anthropic 官方 API 发请求。ANTHROPIC_BASE_URL就是告诉这个壳"你把请求发到哪"，ANTHROPIC_AUTH_TOKEN是鉴权凭证。你完全可以把这两项写到 shell 配置文件里，比如.bashrc或.zshrc中：

export ANTHROPIC_BASE_URL="https://你的API网关地址" export ANTHROPIC_AUTH_TOKEN="你的token"

注意环境变量是"当前终端会话"级别的，你开了一个新终端窗口，如果没有加载配置，环境变量就是空的。很多人栽在这个细节上：明明 export 成功过，新窗口一开又报认证失败。头铁一点的可以把它写进.env文件，每次启动 claude 前手动 source 一下，也够用。

4. 上手实操：第一次对话到日常干活

4.1 第一次启动和基础对话

环境变量配好后，在项目根目录敲claude，进入交互界面。你可以直接用自然语言丢给它任务，比如：

帮我看一下这个项目的目录结构，并说明各个模块的职责

它会读文件，然后给你一个结构化总结。建议第一次先别急着让它干活，先用这种"解说式"任务测试它的读写能力和指令风格。等确认它能正常读取项目内容、回答靠谱之后，再上真正的改动任务。

交互界面的键位也很简单，Ctrl+C可以中断当前任务，斜杠开头的是内置命令。常用的有/help看帮助，/status看当前会话状态和工具权限，/memory查看记忆相关设置。很多新手把 Claude Code 当搜索引擎使劲问"这是什么"，其实更好的用法是"帮我做这个"——它是干活的，不是讲题的。

4.2 CLAUDE.md：让 Claude 记住项目规则

如果说有一个配置项最能提升 Claude Code 的稳定性，那一定是CLAUDE.md。这文件放在项目根目录，里面写这个项目的规则、架构约定、常用命令、技术栈注意事项。Claude Code 每次启动和每个大任务开始前都会读它，相当于给它塞了一份"项目说明书"。

我自己的模板大概是这样的：

# 项目约定 - 使用 TypeScript，禁止 any - 测试框架用 vitest - 不要修改 public/ 下的文件 - 新增 API 必须补充对应测试 - 启动命令：npm run dev - 构建命令：npm run build

别小看这个文件。你不写，它每次都是"裸奔"状态，不知道你项目用什么语言、什么风格、哪些目录不能动。写了之后，它犯糊涂的概率成倍下降。团队协作这东西更好用，交到仓库里，所有人不管本地还是 CI 里跑 claude，看到的是同一套规则。

4.3 Skills 技能：手动装 GitHub 上的技能包

Skills 是一个比 CLAUDE.md 更"重"的个性化机制。一个 skill 是一个文件夹，里面有一个SKILL.md描述它能干什么、适用场景、参数说明，还能带脚本。你在会话里输入/skills可以查看当前已启用的技能。社区里有大量现成的 skill 放在 GitHub 上，比如"代码审查""依赖升级""生成 Git 提交信息"等等。

手动安装某个 GitHub 上的 skill，其实就是把仓库克隆到本地技能目录：

git clone https://github.com/某个用户/某个-skill.git ~/.claude/skills/某个-skill

然后重启 claude，再用/skills看它有没有被识别。被识别后，你可以在对话里自然触发它。比如装了"commit 信息生成"技能，你让它帮忙写提交信息，它会自动按技能里定义的规范来。

我踩过的坑是：技能仓库里有时候塞了一堆与 skill 无关的示例文件，占空间还容易让 claude 误读。我会在克隆后清理掉examples和tests里没用的部分，这不会影响技能运行，反而让加载更快。

4.4 权限与安全：别一口气放开所有工具

Claude Code 能读文件、改文件、执行命令，所以权限设计很关键。默认情况下，执行真正有副作用的工具（比如 Bash 命令）前它会请求你确认，按y允许、按n拒绝。这个确认机制别嫌烦，你也不想它把rm -rf直接敲下去。

如果你是自己一个人用、且项目是本地开发环境，可以在启动时指定允许工具：

claude --allowedTools "Read,Write,Edit,Bash"

限制它只能跑这几类工具。也可以完全不指定，让它每次询问。我的习惯是明确给白名单，但把Bash单独列出来，这样每次执行命令它还是会问我一下，多一道防线。生产环境上我连 Bash 都不给，只允许读文件和分析。

4.5 非交互模式与自动化

Claude Code 不只支持交互界面，还能用一条命令直接执行任务，这个叫非交互模式：

claude -p "找出项目中所有未使用的依赖并给出清理建议"

-p代表 print，也就是一次性任务，执行完直接输出结果退出。这个模式特别适合丢进 CI/CD 流水线：比如在代码合并前自动跑一轮代码审查、生成变更说明、检查是否有调试代码残留。配合 7.5 里的模型切换工具，甚至可以在不同任务里用不同模型，整体非常灵活。

自动化场景下别忘了给足权限，否则它会卡在"等待用户确认"这一步直到超时。一般配合--allowedTools使用，且任务内容要写得尽量精确。自动化任务失败也不丢数据——日志永远有记录，地址我放第 7 章。

5. 编辑器集成与桌面版的正确姿势

5.1 VSCode 集成

我日常一半时间在终端里跑 claude，另一半在 VSCode 里面写完代码顺手交给它改。VSCode 接 Claude Code 非常简单，直接在扩展市场搜索 "Claude Code"，装官方那个插件，然后在项目里打开命令面板（Ctrl+Shift+P或 macOS 的Cmd+Shift+P），输入 "Claude Code: Open"，它会在编辑器的内置终端里启动一个 claude 会话。

好处是，你正在看某个文件时，可以直接用编辑器框选代码，然后在 claude 会话里说"改一下我选中的这段，优化性能"。它会自动关联到当前项目和文件上下文，不用复制粘贴一堆代码，体验比来回切换窗口舒服不少。插件还会把 Claude 的思考过程和文件改动高亮在编辑器里，代码审查效率能高不少。

5.2 桌面版 Desktop 使用

桌面版适合不常驻终端的用户。它本质是一个把 CLI 引擎包装成图形界面的应用，左边是文件树和会话列表，右边是对话和命令记录。你依然可以用自然语言下达任务，改动结果它会显示成类似"diff"的形式，你可以选择接受或者退回。

注意一点：桌面版和命令行版共用同一套底层的配置和凭据。也就是说，你在命令行里export过的环境变量，在桌面版里不一定自动生效——桌面版读的是系统级或启动时的环境变量。解决办法是把相关配置写入全局配置文件，或者干脆在桌面版自己的设置面板里填入 API 地址和密钥。别两边各配一套，到时候这个能用那个不能用，你自己都分不清。

5.3 用 SDK 把 Agent 嵌进自己的程序

如果你不想用现成的 CLI 或桌面版，而是想把自己程序里接一个"AI 编程助手"的能力，可以用官方 SDK。安装命令：

npm install @anthropic-ai/claude-code-sdk

SDK 本质上是把 claude 的 agent 循环封装成可被代码调用的接口。举个例子，你写了个代码生成器工具，希望生成完自动让 AI 做一轮代码审查，就能在 Node 脚本里调用 SDK，传项目路径和任务文本，拿到运行结果。这个路径适合做内部工具的人，普通用户直接跳过不心疼。

6. 高阶：上下文、思考等级与工作流

6.1 1M 大上下文怎么用不爆

Claude Code 的单次会话上下文已经能做到百万 token 级别，理论上整个大型项目塞进去都有可能。但上下文越大，响应越慢、越贵、也越容易 "迷路"——它可能记住开头你让它做的事，写着写着忘了最新的约束。所以我的经验是大上下文是"能"，但不是"每次都要用满"。

控制上下文有几个实用手段：

• /context查看上下文占用比例；
• /compact手动压缩对话历史，它会主动对那些关键约束和未完成任务做一个总结；
• 开启自动压缩，在设置里把它调成"当接近上限时自动压缩"。

对于大项目，我更推荐拆分子代理来缓解主会话上下文压力，具体见 6.4。每次会话聚焦一个子任务，上下文质量会高很多，你的心理压力也小很多——反正会话是可重建的，别把一次会话当成什么传世之作。

6.2 思考等级 xhigh 有多香

Claude Code 有思考等级的概念，控制模型在回答前进行多少"内心推演"。类似你在脑子里预演三遍再开口，还是想到哪说到哪。日常简单任务，默认等级就够。遇到复杂重构、跨模块改动、性能瓶颈定位这类任务，把思考等级拉高，输出质量确实不是一个量级。

在会话里调整的命令是：

/thinking

它会让你选等级，一般有 low、medium、high 甚至 xhigh 几个挡位。我遇到最难啃的"老项目兼容层重构"时切到 xhigh，它给出的方案明显更有条理，还主动列了回滚风险点。代价是响应变慢、消耗更多 token，所以别所有任务都 xhigh，简单任务用高等级纯属烧钱加磨蹭。

工作流（workflows）里也可以预设思考等级。比如项目里某个目录是核心支付链路，对这个目录的任务默认走 xhigh；文档、示例代码这类低风险任务走 medium。这个机制在团队里非常实用，等于给同一个工具配了"不同岗位的认真程度"。

6.3 缓存与成本控制：enable_prompt_caching_1h 实测

很多人问enable_prompt_caching_1h=1这个配置到底有没有用。我的实测答案是：有，但只对 API 计费模型有效，并且要看你用的模型服务端是否支持 prompt caching。

它的原理是：API 会对同一个会话中反复出现的上下文（比如大段项目说明、CLAUDE.md、历史对话）做缓存。缓存命中后这部分 token 的计费价格大幅下降。enable_prompt_caching_1h=1表示启用"1 小时缓存窗口"，也就是一小时内重复提交的同一段上下文，不再按全价算。

设置方式：

export ENABLE_PROMPT_CACHING_1H=1

如果你是订阅套餐、按固定月费使用，这个配置对你没啥感知意义。如果你是 API 按量付费、或者接了 DeepSeek 这类第三方模型，并且对方支持缓存计费模型，那这个开关能实实在在省不少钱。注意它只管缓存策略，别指望它提高模型能力，这就是个省钱开关。

6.4 子代理与工作流：团队协作的正确打开方式

当任务规模超过一个普通会话能承载的范围，就该上子代理了。Claude Code 支持在项目里定义子代理，把这些子代理当"专职员工"用。

子代理配置文件放在项目的.claude/subagents/目录下，每个就是一个 Markdown 文件，里面定义职责、擅长任务、限制条件。举个例子：

# TestEngineer 负责给所有新增代码补测试 要求：优先补边界条件和异常分支 禁止：修改业务代码本体

主会话在干活时，可以随时把子任务交给子代理去跑，比如"TestEngineer 你来补一下这个模块的测试"。子代理有独立对话上下文，不会挤占主会话空间，还能并行跑多个子任务。我在一个中大型项目上试过用三个子代理分别做测试、审查、依赖更新，主会话只负责统筹，整体效率和高水平工程师团队非常接近。

Workflows 则是把这些过程固化成可复用流程。比如你把"提交代码前检查"定义成一个 workflow，里面规定：先让审查子代理看 diff，再跑测试，最后生成 commit message。以后一个命令就能把整套流程串起来，不用每次重复交代。

7. 常见问题与排查实录

7.1 命令找不到、版本不对怎么办

症状是敲claude提示command not found，但 npm 安装明明成功了。这通常是 npm 全局 bin 目录没在 PATH 里。先跑一下：

npm config get prefix

假设输出是/home/you/.npm-global，那就把export PATH="/home/you/.npm-global/bin:$PATH"加进 shell 配置。加了之后重新加载配置再验证。

如果出现"版本号很旧"的情况，比如别人都在 v2.1.278 了你还是 1.x，执行：

npm update -g @anthropic-ai/claude-code

更新完记得重启终端，别让旧进程里的缓存 shell 又把你带回去。

7.2 连接超时、无法连接到 Anthropic

症状是启动时报unable to connect或者卡在登录界面一直转圈。首先确认网络环境是否能访问官方服务。如果确定网络环境本身没问题，那就检查环境变量里有没有设置过ANTHROPIC_BASE_URL，比如之前测试 DeepSeek 时配置过但忘了改回来，所有请求都会跑到那个地址去，自然连不上官网。

我用过一个排查命令：

env | grep -i anthropic

看看当前终端里跟 Anthropic 相关的环境变量到底是什么值。很多"突然连不上"都是换了一个终端窗口导致环境变量丢失，或者旧配置残留。把那几个变量理顺，问题基本就定位了。

7.3 登录失败与令牌问题

登录时提示认证失败，排查顺序是这样：先确认你是不是在用官方订阅登录，如果是 API Key 用户，检查ANTHROPIC_API_KEY是否过期、有没有多余空格；然后跑一次简单请求验证 Key 有效。如果前两天还能用今天突然失效，大概率是 Key 被重置了，去开放平台看下 Key 状态。

另外注意，ANTHROPIC_AUTH_TOKEN和ANTHROPIC_API_KEY这两个变量别混着设。两个都配了的话，Claude Code 的优先顺序可能和你预想的不一样，结果就是你明明配了 DeepSeek 的 token，它却拿着另一个 key 去连官网，报错报得人莫名其妙。我一般只保留一种认证变量的设置。

7.4 卸载与残留清理

想彻底卸载，命令是：

npm uninstall -g @anthropic-ai/claude-code

桌面版的话，用系统自带的卸载入口，或者安装包自带的 uninstall。

卸载命令执行完，~/.claude这个目录通常还在，里面是配置、技能包、日志历史。如果你想彻底清理，把这个目录删掉即可：

rm -rf ~/.claude

注意：这里存的所有自定义 skill、全局配置、会话日志都会消失。我建议删之前先备份，万一以后要找回某些历史记录，不至于追悔莫及。

7.5 ccswitch：一键切换 DeepSeek 的两个模型

接 DeepSeek 之后，很多人会在deepseek-chat（偏通用对话和编码）和deepseek-reasoner（偏深度推理）两个模型之间横跳。手工改配置太麻烦，社区里有人做了小工具 ccswitch。

安装和使用大概是这样：

ccs --list ccs deepseek-reasoner

--list看当前配置了哪些模型，ccs后面跟模型名就完成切换。它本质是帮你改环境变量或者配置文件，不用你自己去记"BASE_URL 和 TOKEN 要怎么组合"。适合同时要用两个模型、且频繁切换的 API 用户。我个人习惯是：日常编码用通用模型，做架构分析和复杂重构切到推理模型，效率曲线好看很多。

7.6 日志与存储位置

所有配置和日志默认都在~/.claude下，各子目录作用如下：

有问题时先看日志，它记录了每一步工具调用、命令执行和报错堆栈。排查连接问题、权限问题时，日志里的信息比屏幕上的报错强十个量级。

最后分享一个我自己的体会

用 Claude Code 真正顺手之后，我最大的改变不是"写代码变快"，而是思考方式变了——我开始习惯把任务拆成多个有边界的子问题，先和它对齐约束条件，再动手实施。这个工具逼着人养成"写清楚需求"的习惯，而这一点恰恰是很多工程师平时最缺的。如果你刚开始接触，建议从最小、最安全的任务入手，比如整理文档、写测试、找死代码，别一上来就让它动核心业务逻辑。等它给你的小活都干得利索了，再逐步放开权限、加大任务尺寸。这套玩法用顺了，后面几乎离不开它。