最近这几个月我身边无论后端还是前端的朋友基本都在聊一个叫 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、macOSWindows 上我建议把安装路径里的空格问题算进去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 /loginAPI 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_URLhttps://api.deepseek.com/anthropic export ANTHROPIC_AUTH_TOKEN你的DeepSeek_API_Key claudeANTHROPIC_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_URLhttps://你的API网关地址 export ANTHROPIC_AUTH_TOKEN你的token注意环境变量是当前终端会话级别的你开了一个新终端窗口如果没有加载配置环境变量就是空的。很多人栽在这个细节上明明 export 成功过新窗口一开又报认证失败。头铁一点的可以把它写进.env文件每次启动 claude 前手动 source 一下也够用。4. 上手实操第一次对话到日常干活4.1 第一次启动和基础对话环境变量配好后在项目根目录敲claude进入交互界面。你可以直接用自然语言丢给它任务比如帮我看一下这个项目的目录结构并说明各个模块的职责它会读文件然后给你一个结构化总结。建议第一次先别急着让它干活先用这种解说式任务测试它的读写能力和指令风格。等确认它能正常读取项目内容、回答靠谱之后再上真正的改动任务。交互界面的键位也很简单CtrlC可以中断当前任务斜杠开头的是内置命令。常用的有/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装官方那个插件然后在项目里打开命令面板CtrlShiftP或 macOS 的CmdShiftP输入 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-sdkSDK 本质上是把 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_1h1这个配置到底有没有用。我的实测答案是有但只对 API 计费模型有效并且要看你用的模型服务端是否支持 prompt caching。它的原理是API 会对同一个会话中反复出现的上下文比如大段项目说明、CLAUDE.md、历史对话做缓存。缓存命中后这部分 token 的计费价格大幅下降。enable_prompt_caching_1h1表示启用1 小时缓存窗口也就是一小时内重复提交的同一段上下文不再按全价算。设置方式export ENABLE_PROMPT_CACHING_1H1如果你是订阅套餐、按固定月费使用这个配置对你没啥感知意义。如果你是 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/skills/自定义技能包~/.claude/subagents/全局子代理配置~/.claude/下的配置文件全局设置、认证状态项目里的.claude/目录项目级配置和子代理终端输出中的日志路径每次会话的详细执行记录有问题时先看日志它记录了每一步工具调用、命令执行和报错堆栈。排查连接问题、权限问题时日志里的信息比屏幕上的报错强十个量级。最后分享一个我自己的体会用 Claude Code 真正顺手之后我最大的改变不是写代码变快而是思考方式变了——我开始习惯把任务拆成多个有边界的子问题先和它对齐约束条件再动手实施。这个工具逼着人养成写清楚需求的习惯而这一点恰恰是很多工程师平时最缺的。如果你刚开始接触建议从最小、最安全的任务入手比如整理文档、写测试、找死代码别一上来就让它动核心业务逻辑。等它给你的小活都干得利索了再逐步放开权限、加大任务尺寸。这套玩法用顺了后面几乎离不开它。
