Claude Code 是 Anthropic 官方出品的终端 AI 编程助手。装好之后你可以在命令行里直接用自然语言让它读项目、找问题、改代码、跑测试甚至帮你把改动提交到 Git。这篇文章就是一份完整的入门教程从安装环境准备开始一直走到你亲手完成第一次真实代码修改为止中间会穿插我实际使用中踩过的坑和总结出来的经验。如果你之前只用过代码补全类工具会觉得 Claude Code 是另一个物种。补全工具是“你写一行它补一行”而 Claude Code 是“你交代一个任务它自己翻代码、设计改动方案、动手改、改完汇报”。这篇文章适合所有想把 AI 真正用进日常开发流程的人无论你是独立开发者、刚入行的学生还是需要在远程开发机上干活的老手照着做一遍基本就能上手。1. 先搞清楚 Claude Code 到底是什么1.1 它解决的是“改代码”这件事不是“写代码”很多朋友第一次听说 Claude Code第一反应是这不就是个更聪明的自动补全吗真不是。补全工具和项目级 AI 助手的最大区别在于——前者只盯着你光标后面那几十个字符后者会读你的整个仓库。我举个实际例子。你接到一个任务“把支付模块里所有的金额单位从分改成元注意牵扯到数据库字段别动。”传统做法是你先全局搜索所有用到金额的地方逐个分析哪些要改、哪些不能碰然后小心翼翼地改完再跑一遍测试。用 Claude Code 的话你只需要把这句话原样丢给它它会自己去读代码、搜索引用、理解模块结构然后给你一份修改计划列出它准备动哪些文件、为什么不改数据库字段。你确认之后它才会动手。这个“理解整个项目”的能力是关键。Claude Code 本身是一个跑在终端里的智能体程序它可以执行 Shell 命令、读写文件、调用 Git、运行测试然后根据结果继续调整自己的操作。它不是在“帮你写代码”而是在“替你完成一个开发任务”。1.2 为什么要用命令行版本Claude Code 确实有桌面应用但说实话我强烈建议新手从命令行版本开始。原因有几个第一命令行版本最轻量安装完一条命令就能跑不占额外内存也不依赖特定操作系统。Windows、macOS、Linux 都能跑。第二它天然融入你现有的开发环境。不管你是用 VS Code、JetBrains、还是纯粹在 Vim/Neovim 里干活终端版 Claude Code 都能无缝配合。第三命令行版本方便做脚本化操作比如一键给某个目录跑一轮代码审查、批量修 bug这些都是可以在 CI 流程里接起来的。我见过不少朋友一上来就追求“看起来好看”的工具结果装了一堆插件实际开发效率没提升多少。如果你真想踏实把 AI 编程用起来终端版是最不容易出幺蛾子的路子。1.3 适合谁用不适合谁用适合独立开发者需要快速熟悉自己或别人的代码库日常要做大量代码重构、bug 排查、重复性修改的人需要在一个项目里基于自然语言做“批处理”式修改的人经常在远程开发机上工作的人——它不是图形工具SSH 登录服务器就能用不太适合只想要“打字时的自动补全”的人——这类需求用 IDE 自带补全或 Copilot 类插件体验更好不愿意把代码提交到 AI 服务的人——虽然可以配置本地模型但完整能力需要联网使用官方服务完全不会命令行操作的人——不用会多高深至少得知道怎么打开终端、切换目录2. 安装前的准备工作三个底子必须先打好2.1 Node.js 安装与版本确认Claude Code 是跑在 Node.js 运行时上的所以第一步是装 Node.js版本要求 18.0.0 以上。建议直接装 LTS长期支持版别盲目追最新版稳定性优先。Windows 用户去 Node.js 官网下载 msi 安装包双击一路下一步就行。macOS 用户推荐用 Homebrew终端执行brew install node省心而且方便以后升级。Linux 用户可以用系统包管理器装但我更推荐先装 nvm 再通过 nvm 装 Node原因后面讲权限问题时会提到。装完别急着继续先验证一下。打开终端node -v npm -v能输出版本号就说明 OK。npm是随 Node 一起装的包管理器后面装 Claude Code 全靠它。这里有个坑有些人电脑上已经装过旧版 Node版本号一看是 14 或者 16低于 18。这时候直接升级别想着“应该也能跑吧”。Claude Code 启动时会做版本检查版本太老会直接报错。Windows 上卸载旧版再装新版即可macOS 上如果之前用 brew 装的brew upgrade node就行。2.2 Git 安装与基础配置第二个必装的是 Git。很多朋友会问我又不准备开源装 Git 干嘛这里有个很实在的原因Claude Code 在改代码之前会借助 Git 来看文件变更、生成 diff、甚至在出错时帮你恢复原样。如果项目还没纳入 Git 管理相当于让它在没有安全网的情况下动手动脚出错了想回滚都很麻烦。Windows 和 macOS 用户到 git-scm.com 下载对应安装包安装时除了默认选项基本不用改。Linux 用apt install git或yum install git之类即可。装完之后两件事必须做配置用户名和邮箱。不然后面提交代码时 Git 会一直报错。git config --global user.name 你的名字 git config --global user.email 你的邮箱example.com这两行配完之后git --version确认能输出版本号就行。另外一个容易被忽略的点如果你打算让 Claude Code 提交代码提交信息里默认会带上 Git user 信息所以这个配置要认真填别随手敲个测试字符串进去。我见过有人配了一个奇怪的用户名结果提交历史里全是乱码名字后面改起来很烦。2.3 终端选择建议Claude Code 是终端应用你的终端体验直接影响使用感受。Windows 用户强烈建议用 Windows Terminal别用老旧的 cmd 或 PowerShell 默认窗口。Windows Terminal 对 UTF-8 编码支持更好字体渲染也更舒服Claude Code 输出的中文内容不容易乱码。macOS 用户可以直接用系统自带的 Terminal或者装一个 iTerm2。Linux 用户基本随便但注意字体别选太奇怪的。还有个小建议终端窗口宽度尽量调大一点至少能显示 120 列。Claude Code 会输出 diff 和文件列表窗口太窄的话排版会挤成一团看起来非常难受。3. 正式安装 Claude Code 并完成登录3.1 全局安装命令与权限处理准备工作做完安装本身其实就是一条命令的事npm install -g anthropic-ai/claude-code-g表示全局安装这样你在任何目录下都能直接执行claude命令。这里我必须多说一句权限问题。如果你在 macOS 或 Linux 上执行这条命令时报EACCES错误说明 npm 全局安装目录没有写权限。这种情况很常见尤其是用系统包管理器装的 Node全局目录默认在/usr/lib/node_modules这类系统路径下普通用户没有写入权限。我在前面提到推荐用 nvm 装 Node原因就在这nvm 会把 Node 整个装在你的用户目录下全局包也是往用户目录里写根本不会有权限问题。如果你已经用 npm 装完遇到了权限错误有两个解决方案方案一修改 npm 全局目录到用户目录下npm config set prefix ~/.npm-global然后把这个目录加到 PATH 环境变量里。方案二简单粗暴用sudo npm install -g。我不推荐因为它把问题延后了后面你用 Claude Code 的各种缓存、配置文件可能都惹上权限麻烦。装完之后验证一下claude --version能输出版本号安装就成功了。3.2 登录认证与 API Key 配置第一次运行claude时它会进入登录流程一般有两种认证方式。方式一是浏览器授权登录。终端里会显示一个确认码和一个授权链接在浏览器打开链接、登录 Anthropic 账号、输入确认码授权即可整个过程一两分钟。方式二是 API Key 方式适合已经有 Anthropic API Key 的用户或者想用脚本方式接入的人。设置环境变量export ANTHROPIC_API_KEY你的API KeyWindows PowerShell 里用$env:ANTHROPIC_API_KEY 你的API Key持久化配置的话Windows 在系统设置的环境变量里加macOS/Linux 可以写进~/.zshrc或~/.bashrc。有些人会遇到公司账号提示 “Your organization has disabled Claude subscription access for Claude Code”这是管理员在后台限制了这个功能。要解决只能找管理员开通或者改用 API Key 方式绕过订阅限制API Key 是独立的计费通道不受订阅权限开关控制。另外Claude Code 是支持通过环境变量切换 API 端点的。如果你所在的环境有内部部署的兼容服务或者想接本地模型服务可以设置ANTHROPIC_BASE_URL指向对应的服务地址再配合对应的 Key 使用。这个配置适合有特殊接入需求的场景常规用户不需要动它。3.3 验证安装与配置文件登录成功之后Claude Code 会在你的用户目录下创建配置文件目录一般是~/.claude/。里面会存放设置文件、历史记录等。想快速验证是否一切正常可以建一个测试目录随手放一个文本文件然后启动claude问它一句帮我看一下当前目录下有哪些文件并简单说明每个文件的用途。它能正常读文件、输出回答就说明整条链路是通的。4. 第一次代码修改的完整实操4.1 从一个干净的示例项目开始别一上来就拿自己最复杂的生产项目练手那是给自己找不痛快。我建议先新建一个迷你项目把整个流程跑通建立信心之后再去碰真实项目。比如我们做一个超级简单的 Python 计算器脚本文件就一个calc.pydef divide(a, b): return a / b def add(a, b): return a b if __name__ __main__: print(divide(10, 0))这个代码有个明显问题除数为零时会抛异常。我们就让 Claude Code 来修它。关键一步先把项目初始化成 Git 仓库。mkdir calc-demo cd calc-demo git init git add . git commit -m init project这一步非常重要。有了 Git 这个安全网Claude Code 的任何修改你都可以通过git diff查看、通过git checkout还原。后面你会明白这个习惯有多值钱。4.2 启动 Claude Code 并下达任务在项目根目录执行claude启动之后会进入交互模式终端左上角会显示一个可以输入文字的区域。第一次在项目里启动时它可能会建议你创建CLAUDE.md项目记忆文件。这里建议先跳过等跑完第一轮再回来补。然后输入你的任务打开 calc.py给 divide 函数加上除数为零的处理逻辑如果 b 等于 0 就抛出一个 ValueError并附带清晰的错误消息。注意看我这句话的构成指定了文件、指定了函数、指定了期望的行为和错误类型。Claude Code 虽然是 AI但你给的信息越具体它的第一步探索就越准确整体改动就越少出偏差。4.3 观察它的行为探索、计划、确认、修改输入任务后Claude Code 不会秒改。它会先用 Read 工具打开文件理解现有函数结构然后给出一个修改方案。终端里会显示类似这样的内容将要修改 - calc.py: divide 函数中增加除零检查 改动内容预览 if b 0: raise ValueError(除数不能为 0) 是否继续(Y/n)这里的设计非常关键它在默认配置下不会直接动文件而是先把计划摆在你面前你点头它才执行。不要嫌这个确认烦尤其是刚上手的时候“每一步改动都过一遍”能帮你建立一个很重要的心智模型——AI 改的每一行代码你都应该看得懂。等信任建立起来再调成自动模式不迟。按y确认之后它会去修改文件。改完后你可以自己再看看git diff你会看到非常清晰的改动记录。这一步我每次都会做哪怕是很小的改动。因为有时候 Claude Code 会顺手改掉一些你没要求的东西偶尔还会改得比需求多这种多管闲事的动作全靠 diff 才能发现。4.4 让 Claude Code 跑测试并提交代码文件改完还没完真实开发流程里你得验证它改得对不对。在交互界面继续输入运行一下 calc.py确认零除是正确的再写两个测试用例验证正常情况下的 divide 功能。注意这里它可能有两种做法一是直接执行python calc.py看输出二是帮你写一份简单的 pytest 测试脚本。不管是哪种都是在用实际执行来验证自己的改动不是纸上谈兵。等它验证通过之后你可以让它帮你提交帮我提交这次改动commit message 按 conventional commits 风格写。它会先git add相关文件然后查看 diff 生成提交信息最后执行 commit。你可以在终端里直接看到它执行了哪些 Git 命令。提交之后自己看一眼git log确认提交信息没有鬼扯。到这里你已经在 Claude Code 的辅助下完成了一次完整的“理解代码 → 修改代码 → 验证代码 → 提交代码”的闭环。别小看这个流程很多老手第一次用的时候都低估了它对工作流的影响。5. 让 Claude Code 更好用的配置与技巧5.1 权限模式该怎么选默认情况下Claude Code 每一步改动都要跟你确认一次。安全是安全但如果你已经对它很熟悉了这种频繁确认确实会影响效率。Config 设置里可以调整权限。运行/permissions命令就能查看当前的权限规则你可以允许它自动执行某些操作比如 Git commit、读取特定目录等。还有一个更“野”的方式启动时加参数claude --dangerously-skip-permissions这个参数会让 Claude Code 跳过所有确认全程自动执行。我明确说新手不要用不要在你不完全理解它要干什么的时候用。我自己的习惯是只有跑特别机械的任务比如批量给一堆 markdown 文件加上 front-matter时才会开自动模式而且一定是在干净的 Git 分支上开。在~/.claude/settings.json里可以配更细的权限比如允许哪些工具、禁止哪些命令。比如你不想让它执行删除类的危险操作可以配{ permissions: { deny: [Bash(rm -rf *)] } }5.2 记住这几个斜杠命令交互界面里输入反斜杠/可以调出命令面板。常用的几个/help查看帮助文档/status查看当前任务的进度和状态/cost查看本次会话消耗了多少 token 和费用/permissions查看和调整权限/compact压缩上下文当对话太长导致它“记不住”前面内容时用/clear清空当前会话重新开始/compact是个很有用的命令也是第一次用的人最容易忽略的。Claude Code 每次交互都会把对话历史塞进上下文里聊得越长、上下文越满、既费 token 又影响回答质量。聊到感觉它开始“犯傻”了就/compact一下把关键信息浓缩成摘要会明显清爽很多。另外快捷键方面Esc可以中断 Claude Code 当前的工具执行CtrlC两次可以退出会话。这些在你发现它路走偏的时候很救命。5.3 配合 VS Code 和远程开发环境使用Claude Code 虽然是终端工具但和 VS Code 的配合也很顺。在 VS Code 里装官方扩展之后可以直接在编辑器内打开 Claude Code 面板同时查看代码和 AI 的操作两边的 diff 可以实时对照。如果你常年通过 VS Code Remote SSH 连接远程开发机干活Claude Code 其实也可以直接装在远程机器上使用。它本质上是个命令行程序SSH 登录到远程服务器之后照常运行。唯一要注意的是在远程机器上运行它也需要完成登录认证如果远程机器没有浏览器可以用设备码方式认证或者直接把 API Key 设为环境变量。我个人非常推荐在远程开发场景里配一个 Claude Code 的只读模式用来快速解读项目结构、搜索定义比人肉grep高效太多。当然前提是项目数据合规允许你把它接入外部 AI 服务。6. 常见问题与排查技巧实录6.1 安装报 EACCES 权限错误现象npm install -g时提示EACCES: permission denied。原因npm 全局目录没有写权限Node 装在了系统级目录。解决办法如果之前没装 nvm建议现在装一个然后从 nvm 安装 Node。如果不想折腾把 npm 全局目录改到用户目录也能彻底解决npm config set prefix ~/.npm-global echo export PATH~/.npm-global/bin:$PATH ~/.zshrc source ~/.zshrc之后重新执行安装命令即可。6.2 Node 版本过低导致启动失败现象运行claude时提示 Node 版本不支持或者干脆没反应。解决办法先查node -v确认是否大于等于 18。版本低于 18 就升级没有别的捷径。我在实践中见过某些老项目环境固定了 Node 14这种环境想跑 Claude Code 就得用 nvm 装一个新版本 Node并用nvm use切换。6.3 登录或鉴权一直失败现象运行claude进入登录流程后浏览器里授权成功但终端还是提示未认证或者每次启动都要求重新登录。排查思路检查环境变量里是否残留了过期或不正确的ANTHROPIC_API_KEY有时候环境变量优先级高于账号登录状态反而把登录覆盖了。检查系统时间是否准确鉴权机制对时间很敏感。尝试把~/.claude/.credentials.json删掉重新走一遍登录流程。6.4 中文字符显示乱码现象Claude Code 输出的中文变成乱码或者某些字符显示成菱形问号。解决办法终端编码统一成 UTF-8。Windows 用户检查 Windows Terminal 的“设置 → 配置文件 → 外观 → 字体”和“区域设置”别用旧版 cmd 窗口。还有一个细节部分 Windows 下 PowerShell 执行chcp 65001临时切到 UTF-8但治标不治本还是建议直接用 Windows Terminal 默认配置。6.5 它改错了代码怎么回滚这是新手最慌的场景但其实有 Git 保护就不用怕。如果还没提交直接git checkout -- 文件还原单个文件或者git checkout .还原当前目录所有改动。如果已经提交了但还没 push用git reset --soft HEAD~1撤销这次提交改动回到暂存区。如果已经 push 到远端就别乱 reset 了用git revert反向提交一次更安全。真的每一次让 Claude Code 动手前第一件事永远是确认当前分支是干净的、可回滚的。我甚至有段时间习惯在claude启动前自动创建一个工作分支跑完验证没问题再合并心里踏实得多。6.6 大项目里它响应慢、容易乱现象项目代码量很大时Claude Code 一开始探索耗时很长甚至后面操作开始“东一榔头西一棒槌”。原因上下文和探索范围太大模型容易抓不住重点。解决办法在对话里明确限定范围比如“只看 backend/src/modules/payment 目录”。或者直接把相关文件路径给它让它别全局搜索。还可以通过CLAUDE.md文件提前告诉它哪些目录不用管、哪些是核心代码。上下文越聚焦输出质量越好。6.7 接第三方或本地模型时行为不稳定有朋友问过能不能让 Claude Code 接本地跑的 Qwen 这类模型或者通过 Ollama、LM Studio 管起来。技术上确实可行本质上就是ANTHROPIC_BASE_URL指向本地兼容端点再把 Key 填成占位符。但我得说句实话目前市面上大多数本地模型在“自主读代码、改代码、跑测试”这类复杂智能体任务上的表现跟官方模型差距很大。我实测遇到过模型“看到了代码但不改”“改了一半就停”“执行的命令不连续”等各种状况不是工具坏了是模型能力确实顶不住。我的建议是如果是日常开发用官方订阅或 API Key 更省心如果你对本地模型感兴趣拿探索型、只读型任务练手先别指望一步到位替代主力开发。最后分享一点我的实际体会用 Claude Code 这几个月下来我最大的感受是这个工具的体验上限很大程度取决于你给它输入的上下文质量。我刚用它的时候喜欢把任务描述得天花乱坠各种修辞、各种希望结果它反而方向跑偏。后来我把话说短、说具体直接告诉它“文件在哪、函数叫什么、需要什么行为、别动什么东西”它执行得又快又准。第二个体会是CLAUDE.md这件事值得认真做。后来我在每个项目里都花十几分钟写一份内容包括项目结构说明、构建测试命令、目录用途和代码风格约定。Claude Code 每次启动都会自动读它相当于你提前给 AI 做了一次项目培训。实测下来有了这份文件之后它改代码的准确率明显提升反复折腾的次数也变少了。最后想对所有第一次上手的朋友说别怕让它犯错但给自己留好退路。Git 提交做勤一点diff 多看一眼权限确认多留几秒。等这套流程成为肌肉记忆你会发现很多过去要花一下午的机械改动现在喝杯水的功夫就已经搞定了。