Claude Code 实战：从零搭建到首次代码修改的完整指南

1. 为什么我最终把主力开发环境切到了 Claude Code第一次听说 Claude Code 是在一个做后端的朋友群里有人丢了一张截图终端里敲了一行自然语言它自己读完了整个项目结构定位到一个空指针异常改完代码还顺手跑了一遍测试。当时我的第一反应是“又一个玩具”毕竟这些年见过的 AI 编程工具太多了从最早的代码补全插件到后来的对话式助手真正能融进日常开发流的没几个。但用了两周之后我把日常的脚本维护、小功能迭代、甚至一部分重构工作都交给了它原因很简单它不是一个“聊天窗口”而是一个真正能读写你本地文件、执行终端命令、理解 Git 状态的命令行代理。这篇内容我想完整地聊一遍 Claude Code 从零到第一次改代码的全过程。不是官方文档的复述而是我自己在 macOS、Ubuntu 和 Windows 三套环境里踩过坑之后整理出来的实操路径。如果你符合下面任意一种情况这篇东西应该能帮你省掉至少一个周末的折腾时间你是一个习惯用终端但没接触过 AI 代理的开发者你已经在用 VS Code 或 JetBrains 系 IDE想看看命令行工具能不能补上 IDE 的短板你之前试过其他 AI 编程工具但觉得“它只会给建议、不会动手”所以放弃了。Claude Code 的核心价值就在于它把“建议”和“执行”之间的那道墙拆掉了而这道墙恰恰是过去所有工具都没能真正跨过去的地方。在展开之前先说清楚一件事Claude Code 不是免费的它需要 Anthropic 的账号和订阅额度这一点和那些本地跑的模型有本质区别。但它的能力上限也正来自于此后面我会在工具选型那部分详细对比。现在先假设你已经决定要试我们从最基础的环境准备开始。2. 安装前的环境盘点与工具选型逻辑2.1 三套操作系统下的前置依赖清单Claude Code 本身是一个 Node.js 写的 CLI 工具所以第一件事是确认你的机器上有可用的 Node 环境。我实测下来Node 18 LTS 是最低门槛20 LTS 更稳。如果你机器上还是 Node 16 甚至更老别犹豫直接用 nvm 或 fnm 切到 20。这里有个细节很多人系统里装了多个 Node 版本全局 npm 包会跟着当前激活的版本走所以装完 Claude Code 之后如果切了 Node 版本命令可能就找不到了。我的做法是固定一个长期使用的 LTS 版本把 Claude Code 装在这个版本下。Git 是第二个硬依赖。Claude Code 需要读 Git 状态来判断哪些文件被修改过、哪些是新增的它执行代码修改之后你也要靠 Git 来 review 和回滚。Windows 用户特别注意一定要装 Git for Windows它会附带 Git BashClaude Code 在 Windows 上很多终端操作依赖这个环境。我见过有人在 PowerShell 里直接跑然后报一堆路径错误换成 Git Bash 就正常了。Git 安装本身没什么好说的一路默认下一步就行但安装完成后记得在终端里跑一下git --version确认 PATH 配好了。第三个容易被忽略的是终端本身。macOS 自带的 Terminal 够用但我更推荐 iTerm2 或者 Warp因为 Claude Code 的输出有时候比较长好的终端在滚动和复制上体验差很多。Ubuntu 下默认的 GNOME Terminal 没问题如果你用 tmux注意 Claude Code 在 tmux 里的交互偶尔会有光标位置问题遇到的话退出 tmux 单独跑一次确认是不是环境导致的。Windows 下强烈建议用 Windows Terminal 配合 Git Bash profile比老式的 cmd 和 PowerShell 舒服太多。2.2 为什么是命令行而不是 IDE 插件这个问题我被问过很多次。VS Code 里已经有 Copilot、Continue、Cline 这些插件了为什么还要单独装一个命令行工具我的答案分两层。第一层是能力边界IDE 插件受限于 IDE 的 API它能读当前打开的文件、能给建议、能插入代码但它很难自主地遍历整个项目、执行 shell 命令、跑测试然后根据结果再改代码。Claude Code 没有这个限制它就是一个跑在你终端里的进程你给它一个任务它会自己决定读哪些文件、跑什么命令、怎么验证结果。第二层是工作流我很多工作是在 SSH 连着的远程服务器上做的IDE 插件在那种场景下要么装不了要么很别扭而 Claude Code 只要那台机器有 Node 和 Git 就能跑。当然这不是说 IDE 插件没用了。我现在的实际组合是VS Code 里开着 Claude Code 的官方扩展做快速对话和 diff 预览同时终端里跑着 CLI 做重活。两者共享同一套配置和认证切换成本很低。如果你刚开始接触我建议先把 CLI 跑通理解它的工作方式之后再决定要不要装 IDE 扩展。2.3 账号与认证的几种路径Claude Code 的认证方式这几年变过几次目前主流的是两种一种是用 Anthropic 账号直接登录走订阅额度另一种是用 API Key按 token 计费。前者适合个人开发者日常使用后者适合团队或者需要精细控制成本的场景。登录流程本身很简单第一次运行claude命令它会引导你走 OAuth浏览器里点一下授权就完事了。这里有个坑值得单独说如果你在公司网络环境下浏览器授权那一步可能会因为代理配置问题卡住。我遇到过一次终端里显示等待授权浏览器打开后一直转圈。排查下来是终端和浏览器走了不同的网络路径。解决办法是在终端里确认HTTPS_PROXY环境变量和浏览器代理设置一致或者干脆换一个网络环境完成首次授权授权信息会缓存在本地之后换回原网络也能用。另外如果你看到类似“your organization has disabled claude subscription access”的提示那基本是账号所属组织限制了订阅访问这种情况只能换个人账号或者走 API Key 路径。3. 从零安装到跑通第一条命令3.1 npm 全局安装与版本管理安装命令本身就一行npm install -g anthropic-ai/claude-code但这一行背后有几个值得注意的点。首先是权限问题macOS 和 Ubuntu 下如果 Node 是用系统包管理器装的全局安装可能需要 sudo我不建议用 sudo因为那样装出来的包属主是 root后续升级和卸载都麻烦。正确做法是用 nvm 管理 Node这样全局包都装在用户目录下不需要提权。Windows 下如果用官方 Node 安装包全局目录默认在用户 AppData 下一般不会有权限问题。其次是版本锁定。Claude Code 更新很频繁有时候新版本会引入行为变化。如果你在一个需要稳定性的项目里用可以考虑在项目本地安装而不是全局安装然后在 package.json 的 scripts 里固定版本。我自己的做法是全局装最新版用于日常探索同时在几个关键项目里用本地安装锁定版本两边互不干扰。安装完成后跑claude --version确认。如果提示 command not found九成是 npm 全局 bin 目录不在 PATH 里。用npm config get prefix看一下全局前缀然后确认那个路径下的 bin 目录在 PATH 中。这个问题在 Windows 上尤其常见因为 Git Bash 和 PowerShell 的 PATH 是分开的你在 PowerShell 里装完Git Bash 里可能找不到。3.2 首次启动与项目初始化进入你的项目目录直接敲claude。第一次启动它会做几件事检查当前目录是不是 Git 仓库读取项目里有没有 CLAUDE.md 文件然后进入交互界面。如果当前目录不是 Git 仓库它会提示你但不会强制要求。不过我强烈建议在 Git 仓库里用原因后面讲回滚的时候会说。启动之后你会看到一个类似聊天框的界面底部有输入提示。这时候先别急着让它改代码用几个简单命令熟悉一下交互方式。比如输入/help看可用命令列表输入/status看当前会话状态和 token 消耗。这些斜杠命令是 Claude Code 的内置指令和直接输入自然语言是两套体系前者控制工具本身的行为后者是给 AI 的任务描述。我建议第一次使用时先做一件事让它读一遍项目结构。输入类似“帮我梳理一下这个项目的目录结构和主要模块”这样的话观察它怎么工作。你会看到它自动调用文件读取工具逐个查看关键文件然后给出一个总结。这个过程能让你直观感受到它和普通聊天机器人的区别——它是真的在“看”你的代码而不是凭空生成。3.3 CLAUDE.md 的写法与作用CLAUDE.md 是 Claude Code 的项目级配置文件放在项目根目录。它的作用类似于给 AI 的一份“项目说明书”每次会话开始时会被自动读取。内容可以包括项目架构说明、代码规范、常用命令、注意事项等等。写得好不好直接决定了 AI 在你项目里的表现上限。我的 CLAUDE.md 通常包含这几块项目一句话简介、技术栈列表、目录结构说明、开发命令怎么跑测试、怎么启动本地服务、代码风格约定、以及一些“雷区”提示比如“不要修改 migrations 目录下的文件”。不需要写得很长关键是准确和具体。举个例子与其写“遵循项目代码风格”不如写“使用 2 空格缩进字符串用单引号组件文件用 PascalCase 命名”。后者 AI 能直接执行前者它只能猜。有个技巧是让 Claude Code 自己帮你生成初版 CLAUDE.md。启动后输入“分析这个项目并生成一份 CLAUDE.md”它会读完项目后给你一份草稿你再根据实际情况调整。这比从零写快很多而且它往往能发现一些你自己都忘了的约定。4. 第一次代码修改的完整实操4.1 选一个合适的练手任务第一次让 AI 改代码任务选择很重要。太简单了体现不出价值太难了容易翻车打击信心。我的建议是找一个“边界清晰、有明确验证方式”的小任务。比如给某个函数补一个边界条件判断、修复一个已知的拼写错误、给一个工具函数加参数校验、或者补一个缺失的单元测试。这类任务的特点是改动范围可控改完对不对一眼能看出来。我自己的第一次实操是给一个 Python 脚本加一个命令行参数。那个脚本原本硬编码了输入文件路径我想改成可以通过--input指定。任务描述大概是“这个脚本目前输入路径是写死的帮我改成支持 --input 参数默认值保持现在的路径不变用 argparse 实现。” 这个任务足够小但涉及了读代码、理解现有结构、引入新依赖argparse 是标准库但也要 import、修改多处代码是一个很典型的完整流程。4.2 任务描述怎么写才有效和 AI 协作描述任务的颗粒度直接决定结果质量。我总结了一个简单的公式现状 目标 约束。现状是“现在是什么样”目标是“我要它变成什么样”约束是“哪些不能动、必须用什么方式”。上面那个例子拆开就是现状——输入路径硬编码目标——支持 --input 参数且默认值不变约束——用 argparse。避免的写法是只给目标不给现状比如“帮我加个命令行参数”。AI 不知道你现有代码长什么样可能会用 sys.argv 手写解析也可能引入 click 这种第三方库结果和你的预期不符。另一个常见错误是一次性给太多目标比如“重构这个模块顺便加个功能再修个 bug”。Claude Code 能处理多步任务但第一次用的时候还是聚焦单一目标方便你观察它的工作方式出问题也容易定位。4.3 观察它的工作过程与中途干预提交任务后Claude Code 不会立刻给你答案它会先做一系列动作。你会看到终端里滚动出它的思考过程和工具调用记录读取了哪些文件、执行了什么命令、准备做什么修改。这个过程是实时的你可以随时按 Esc 打断或者输入补充说明。我第一次看它工作时印象最深的是它会主动验证。改完代码后它没有直接说“完成了”而是跑了一遍python script.py --help确认参数生效又跑了一遍不带参数的情况确认默认值正确。这个行为是它和普通代码生成工具最大的区别——它有“验证意识”。当然这个验证不是万能的复杂逻辑它可能验证不到位但至少基础的语法和运行检查它会做。中途干预的时机很重要。如果你看到它准备修改一个你不想让它动的文件立刻按 Esc 打断然后补充说明“不要修改 xxx 文件”。如果你等它改完再说虽然可以回滚但浪费了一轮 token。我的经验是前几次使用时多盯着点熟悉它的行为模式之后就可以放手让它跑只在关键节点检查。4.4 用 Git diff 验收与回滚Claude Code 改完代码后第一件事是跑git diff。这是你的验收关口也是安全网。diff 会清楚显示它改了哪些文件、每一处改动的具体内容。我验收时看三个东西改动范围是否符合预期有没有动不该动的文件、逻辑是否正确有没有引入明显的错误、风格是否一致缩进、命名是否和项目统一。如果 diff 有问题回滚很简单git checkout -- .丢弃所有未提交的改动或者git checkout -- 具体文件只回滚某个文件。这就是为什么我一直强调要在 Git 仓库里用 Claude Code——它给了你一个随时可以退回的锚点。我自己的习惯是每次让 Claude Code 做稍大的改动之前先手动 commit 一次当前状态这样回滚的粒度更清晰。验收通过后正常 commit 就行。我通常会在 commit message 里注明这是 AI 辅助完成的方便以后追溯。这不是必须的但团队协作时是个好习惯。5. 常见问题排查与避坑经验5.1 安装与认证类问题速查现象可能原因解决方向claude: command not foundnpm 全局 bin 不在 PATH检查npm config get prefix把对应 bin 目录加入 PATH启动后卡在授权页面终端与浏览器网络路径不一致确认代理设置一致或换网络完成首次授权提示组织禁用了订阅访问账号所属组织限制换个人账号或改用 API KeyWindows 下路径报错在 PowerShell 而非 Git Bash 中运行切换到 Git Bash 终端Node 版本报错Node 低于 18用 nvm 切换到 20 LTS这张表里的问题我基本都遇到过其中 PATH 问题在 Windows 上出现频率最高。Git Bash 和 PowerShell 的 PATH 是独立的在 PowerShell 里npm install -g装的东西Git Bash 里不一定能找到。解决办法是在 Git Bash 里也跑一遍安装或者手动把 npm 全局路径加到 Git Bash 的 PATH 配置里。5.2 代码修改类问题的排查思路Claude Code 改代码偶尔会出问题常见的有几类。第一类是改错文件比如你想改 A 模块它改了同名的 B 模块。这种情况通常是项目里有多个相似文件任务描述里最好带上具体路径。第二类是引入不必要的依赖比如为了一个小功能装了一个大库。预防办法是在任务描述里加约束“只用标准库”或“不要新增依赖”。第三类是改动范围超出预期比如你让它改一个函数它顺手重构了整个文件。这个在验收 diff 时能发现回滚重来即可下次描述时加上“只修改 xxx 函数不要动其他部分”。还有一类比较隐蔽的问题是它“看起来改对了但实际没生效”。比如它改了代码但没保存或者改了一个不被引用的副本文件。这种情况跑一遍实际功能就能发现。我的习惯是改完之后不只跑它给的验证命令自己再手动跑一遍核心流程双重确认。5.3 几个我踩过的坑和对应技巧第一个坑是长会话的上下文漂移。Claude Code 的会话是有上下文窗口的聊得太久之后它可能忘记早期的约定。我的做法是重要约定写进 CLAUDE.md而不是靠对话记忆。另外长任务可以拆成几个短会话每个会话聚焦一个目标完成一个 commit 一次这样上下文始终干净。第二个坑是它执行危险命令。Claude Code 有权限执行终端命令理论上rm -rf这种也能跑。它默认会对危险操作做确认但我不建议完全依赖这个机制。我的做法是在 CLAUDE.md 里明确写“不要执行任何删除文件或目录的命令”给自己加一道保险。另外重要项目一定在 Git 仓库里操作最坏情况也能恢复。第三个坑是 token 消耗比预期快。Claude Code 读文件、跑命令、生成修改都会消耗 token一个稍复杂的任务可能消耗几万 token。控制方法有几个任务描述尽量精确减少它探索的范围CLAUDE.md 里写清楚项目结构减少它盲目读文件不需要它读的文件可以在配置里排除。我自己的体感是日常小任务消耗可控大型重构任务要提前有心理准备。6. 进阶配置与工作流整合6.1 和 VS Code 的配合方式虽然我主力用 CLI但 VS Code 的 Claude Code 扩展确实有它的价值。最实用的是 diff 预览功能CLI 里的 diff 是文本形式的VS Code 里是并排高亮的review 起来快很多。另外扩展里可以直接在编辑器里选中一段代码然后让 Claude 解释或修改这个交互比在终端里描述“第 42 行那个函数”要自然。配置方式很简单装完扩展后它会自动检测本地的 Claude Code CLI共享同一套认证。如果你在 VS Code 的集成终端里跑 CLI扩展也能感知到会话状态。我现在的流程是重活和需要跑命令的任务在 CLI 里做纯代码 review 和快速问答在 VS Code 扩展里做两边切换很顺。6.2 在远程服务器上的使用要点SSH 到远程服务器上用 Claude Code 是完全可行的前提是那台机器有 Node 18 和 Git。安装步骤和本地一样认证走一次 OAuth 就行。需要注意的是远程机器通常没有图形界面OAuth 那一步它会给你一个链接你在本地浏览器打开授权后把 code 贴回终端。这个流程稍微绕一点但能走通。远程使用的一个实际问题是网络延迟会影响交互体验尤其是它读大文件的时候。我的做法是在远程机器上只做必要的任务复杂的探索性工作还是本地做完再同步过去。另外远程机器的 CLAUDE.md 要单独维护因为项目路径和环境可能和本地不同。6.3 把 Claude Code 纳入日常开发节奏用熟之后我逐渐形成了一套固定的使用节奏。早上开始工作时先让它跑一遍git status和最近的 commit log帮我快速回忆昨天做到哪了。开发新功能时先让它读相关模块给出实现思路我确认方向后再让它动手。修 bug 时把报错信息直接贴给它让它先定位再修改。代码 review 时让它读一遍 diff 然后指出潜在问题。这套节奏的核心是“人做决策AI 做执行”。它不替你想做什么但你想清楚之后它能很快地做出来。这个分工我觉得是当前阶段最合理的既发挥了 AI 的效率优势又保留了人对方向的把控。至于以后会变成什么样那是以后的事至少现在这套组合已经让我的日常效率有了肉眼可见的提升。最后分享一个我最近发现的小技巧如果你有一个重复性的任务比如每周都要更新某个配置文件可以把操作步骤写成一个 markdown 文件放在项目里然后让 Claude Code 读这个文件并执行。相当于给它写了一个可复用的“操作手册”下次直接说“按 xxx.md 里的步骤操作”就行省去了每次重新描述的时间。这个用法在维护类任务上特别好使你可以试试。