1. 为什么值得花时间把 Claude Code 跑起来第一次听说 Claude Code 的时候我其实没太当回事。命令行里跟 AI 聊天我终端里已经有一堆工具了再塞一个进去能有多大差别。直到有次改一个遗留项目里的日期处理逻辑那个文件两千多行散落着七八处new Date()的隐式时区转换我手动找一遍改一遍测一遍前后折腾了快两个小时。后来同事让我试试 Claude Code同样的事情它先扫了一遍相关文件把每一处可疑的时区处理列出来我确认之后它直接改连带把受影响的测试用例也更新了整个过程不到十分钟。这就是 Claude Code 真正区别于普通对话式 AI 的地方它不是让你复制粘贴代码而是直接在你的项目目录里读文件、改文件、跑命令。你告诉它要做什么它自己去翻代码、理解上下文、动手修改改完还能帮你跑测试验证。对于日常需要跟代码打交道的开发者来说这个工作方式的改变是实打实的。这篇内容适合几类人一是完全没接触过 Claude Code想从零装起来跑通第一次代码修改的二是装了但卡在环境配置、认证、权限这些环节的三是想搞清楚 CLAUDE.md 到底该怎么写、怎么让它在团队项目里真正好用的。我会从安装讲到第一次完整的代码修改中间踩过的坑、绕过的弯路都会写出来尽量让你少走一遍。需要提前说明的是Claude Code 目前主要通过命令行使用也有 VS Code 扩展和桌面版但核心能力都在 CLI 上。我下面以 CLI 为主线VS Code 和桌面版会单独提。另外它需要访问 Anthropic 的服务所以网络环境得能正常连通这个前置条件先确认好不然后面全是白忙。2. 安装前的环境准备与工具选型2.1 Node.js 版本选择与安装Claude Code 是通过 npm 分发的所以第一步得有 Node.js。这里有个坑我踩过Node 版本太低会直接报错官方要求Node.js 18 及以上我建议直接上 20 LTS 或者 22 LTS省得后面遇到兼容性问题。Windows 用户去 Node.js 官网下载 LTS 版本的安装包一路下一步就行。安装完之后打开 PowerShell 或者 CMD敲node -v npm -v能正常输出版本号就说明装好了。如果提示不是内部或外部命令大概率是安装时没勾选Add to PATH重新跑一遍安装程序勾上就行。macOS 用户我更推荐用 nvm 来管理 Node 版本因为后面你可能会有多个项目需要不同 Node 版本curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 重开终端后 nvm install 20 nvm use 20Linux 用户同理用 nvm 或者系统包管理器都行。Ubuntu 下如果直接用apt install nodejs装出来的版本可能偏低建议还是走 nvm。提示如果你之前装过 Node 但版本很老先升级再装 Claude Code。我见过有人 Node 16 硬装装是装上了一跑就各种模块报错排查半天才发现是版本问题。2.2 Git 的安装与基础配置Claude Code 很多能力依赖 Git比如它要理解你的代码变更、生成 diff、帮你提交。所以 Git 得先装好。Windows 去 git-scm.com 下载安装包安装过程中有个选项是Adjusting your PATH environment选默认的Git from the command line and also from 3rd-party software就行。装完在终端里验证git --versionmacOS 一般自带 Git没有的话brew install git。Linux 用apt install git或yum install git。装完之后配置一下身份信息这个不只是 Claude Code 需要你日常提交代码也得用git config --global user.name 你的名字 git config --global user.email 你的邮箱还有一个配置我强烈建议加上尤其是 Windows 用户git config --global core.autocrlf input这个是为了避免换行符在 Windows 和 Unix 之间来回转换导致的诡异 diff。我之前有个项目Claude Code 改完文件后 git diff 显示整个文件都变了就是因为换行符问题加上这个配置之后就正常了。2.3 终端选择的一点经验Claude Code 是交互式的终端体验直接影响使用感受。Windows 上我推荐用Windows Terminal比自带的 CMD 好用太多支持多标签、字体渲染也好。macOS 用 iTerm2 或者自带的 Terminal 都行。VS Code 内置的终端也可以好处是改完代码直接在编辑器里就能看到变化。如果你打算在 VS Code 里用 Claude Code那 VS Code 本身也得装好。这个后面单独讲。3. Claude Code 的安装与认证实操3.1 三种安装方式对比Claude Code 目前有几种安装途径我整理了一下各自的适用场景安装方式命令适用场景优缺点npm 全局安装npm install -g anthropic-ai/claude-code最通用所有平台需要 Node 环境升级方便原生安装脚本官方提供的安装脚本不想装 Node 的用户依赖少但升级要重跑脚本VS Code 扩展扩展市场搜索安装习惯在编辑器里工作集成度高但功能可能滞后 CLI我个人的选择是npm 全局安装因为升级一条命令搞定而且 CLI 功能最全、更新最快。下面以这个为主讲。3.2 npm 安装全过程确认 Node 和 npm 都正常之后直接跑npm install -g anthropic-ai/claude-code这里有个常见问题权限报错。macOS 和 Linux 下如果没配好 npm 全局目录会提示EACCES权限不足。解决办法有两个一是用sudo不推荐容易搞乱权限二是配置 npm 的用户级全局目录mkdir -p ~/.npm-global npm config set prefix ~/.npm-global # 然后把 ~/.npm-global/bin 加到 PATH 里 export PATH~/.npm-global/bin:$PATH把最后那行加到你的.bashrc或.zshrc里重开终端生效。Windows 用户一般不会有权限问题但如果 npm 装得慢可以换个镜像源npm config set registry https://registry.npmmirror.com装完之后验证claude --version能输出版本号就成功了。如果提示命令找不到检查一下 npm 全局 bin 目录有没有在 PATH 里。Windows 下可以用npm config get prefix看看全局目录在哪然后确认那个路径在系统环境变量里。3.3 首次启动与认证第一次运行claude它会引导你完成认证。目前主要是两种方式一是用 Anthropic 账号登录二是配置 API Key。登录方式会打开浏览器让你授权授权完回到终端就绪。API Key 方式适合在服务器或者无浏览器的环境里用你需要先去控制台生成一个 Key然后export ANTHROPIC_API_KEY你的key或者写进 shell 配置文件里持久化。注意如果你在公司网络或者某些受限环境里遇到订阅相关的提示通常是账号权限或组织策略的问题这种情况需要联系你的账号管理员确认不是本地配置能解决的。认证成功后在任意项目目录下敲claude就会进入交互界面。第一次进去它会问你一些偏好设置比如主题、是否允许自动执行某些操作等按自己习惯选就行。3.4 VS Code 集成配置如果你主要用 VS Code 写代码装个 Claude Code 扩展会方便很多。在扩展市场搜 Claude Code 安装装完在侧边栏会出现图标。扩展本质上还是调用 CLI所以 CLI 得先装好。VS Code 里的好处是Claude Code 改完文件编辑器里直接高亮显示变更你可以逐块 review接受或拒绝。这个体验比纯终端里看 diff 直观。配置上扩展会读取你 CLI 的认证状态一般不用额外设置。如果遇到连不上的情况检查一下 VS Code 的终端能不能正常跑claude命令能跑的话扩展通常也没问题。4. 第一次代码修改从理解需求到验证结果4.1 准备一个练手项目别一上来就拿生产项目试找个自己的小项目或者新建一个练手。我建议建一个简单的 Node 项目包含几个文件方便观察 Claude Code 的行为mkdir claude-demo cd claude-demo git init npm init -y然后建一个utils.js写几个函数比如一个计算数组平均值的、一个格式化日期的。再建一个index.js调用它们。这样有个基本结构Claude Code 有东西可读。4.2 启动并下达第一个任务在项目根目录下敲claude进入交互界面。第一次用我建议先让它做点只读的事情熟悉一下它的工作方式帮我看看这个项目里有哪些函数各自是做什么的它会去读文件然后给你一个概览。这一步很关键你能观察到它是怎么探索代码库的——它会用类似ls、读文件、搜索关键词这些操作。如果它读的文件不对你可以纠正它。确认它理解了项目结构之后再下达修改任务。比如utils.js 里的平均值函数没有处理空数组的情况空数组会返回 NaN。帮我加上处理空数组时返回 0并且更新对应的测试这时候它会读utils.js找到那个函数读测试文件如果有的话提出修改方案执行修改关键点来了默认情况下Claude Code 在修改文件前会征求你同意会显示它打算改什么你按回车确认它才动手。这个机制很重要别嫌麻烦前期一定要看清楚它改了什么。等你信任度上来了可以在设置里调整权限让它对某些操作自动执行。4.3 看懂它的修改与 diff改完之后用git diff看变更git diff你会看到它具体改了哪几行。这里要养成习惯每次修改后都 review diff。AI 改代码不是百分百正确尤其是涉及业务逻辑的地方它可能理解偏了。我遇到过它把空数组返回 0理解成所有异常情况都返回 0把本该抛错的情况也吞掉了。所以 diff 必须看。如果改得不对直接跟它说不对只有空数组才返回 0其他异常情况还是要抛错改回来它会重新调整。这种来回对话是正常的工作方式别指望一次就完美。4.4 让它跑测试验证改完代码让它自己验证跑一下测试确认修改没问题它会执行npm test之类的命令把结果反馈给你。如果测试挂了它会尝试分析原因并修复。这一步能省你不少手动验证的时间。如果项目没有测试你可以让它先写一个给这个平均值函数写几个测试用例覆盖空数组、正常数组、包含非数字的情况它会生成测试文件并运行。这也是 Claude Code 比较实用的一个场景——给老代码补测试。4.5 提交这次修改验证通过后可以让它帮你提交把这次修改提交一下写个合适的 commit message它会生成 commit message 并执行git add和git commit。生成的 message 一般还挺规范遵循 conventional commits 风格。当然你也可以自己写 message让它只执行提交命令。到这一步你就算完整走通了一次安装 → 理解项目 → 修改代码 → 验证 → 提交的闭环。后面就是在这个基础上不断扩展使用场景了。5. CLAUDE.md让 Claude Code 真正懂你的项目5.1 CLAUDE.md 是什么为什么重要用了几次之后你会发现一个问题每次新开一个会话Claude Code 对你的项目一无所知你得重新解释项目结构、技术栈、代码规范。这时候就需要CLAUDE.md。CLAUDE.md 是放在项目根目录的一个 Markdown 文件Claude Code 每次启动时会自动读取它把它作为项目上下文。你可以把它理解成给 AI 看的项目说明书。写好这个文件能极大提升它每次响应的准确度。我见过很多人装了 Claude Code 觉得也就那样很大一部分原因是没写 CLAUDE.md每次都在跟一个对项目零了解的助手对话效果自然打折。5.2 CLAUDE.md 该写什么不用写得太长重点是它猜不到、但必须知道的信息。我一般包含这几块# 项目说明 ## 技术栈 - 语言TypeScript 5.x - 框架React 18 Vite - 测试Vitest - 包管理pnpm ## 目录结构 - src/componentsUI 组件 - src/hooks自定义 hooks - src/utils工具函数 - src/api接口封装 ## 代码规范 - 组件用函数式不用 class - 状态管理用 zustand不用 redux - 所有异步操作必须有错误处理 - 提交前必须跑 pnpm lint 和 pnpm test ## 常用命令 - 开发pnpm dev - 测试pnpm test - 构建pnpm build - 类型检查pnpm typecheck ## 注意事项 - 不要修改 src/generated 下的文件那是自动生成的 - 环境变量在 .env.local不要提交关键是把约定写清楚。比如你团队规定所有 API 请求都要走统一的封装那就写进去不然 Claude Code 可能直接给你写个裸的 fetch。5.3 分层配置全局与项目级CLAUDE.md 可以放在不同位置作用范围不同项目根目录的 CLAUDE.md只对当前项目生效可以提交到 Git团队共享用户主目录的 ~/.claude/CLAUDE.md对你所有项目生效放个人偏好子目录的 CLAUDE.md对该子目录生效适合 monorepo我一般把团队规范放项目级把个人习惯比如回答用中文、解释代码时多举例子放全局级。这样换项目也不用重复配置。5.4 让 CLAUDE.md 持续进化CLAUDE.md 不是写一次就完事的。用一段时间后你会发现某些问题反复出现比如它总是忘记某个约定那就把那条约定加进去。我有个习惯每次纠正它一个错误如果这个错误是项目特有的就顺手更新 CLAUDE.md避免下次再犯。还有个技巧可以让 Claude Code 自己帮你维护这个文件。比如把我们刚才讨论的代码规范整理一下更新到 CLAUDE.md 里它会读取现有内容追加或修改。这样维护成本很低。6. 常见问题排查与避坑经验6.1 安装与认证类问题问题claude命令找不到先确认 npm 全局 bin 目录在 PATH 里。Windows 下npm config get prefix看路径然后加到系统环境变量。macOS/Linux 检查~/.npm-global/bin或/usr/local/bin是否在 PATH。问题认证一直失败检查网络能不能正常访问 Anthropic 的服务。如果是 API Key 方式确认 Key 没有过期、额度没用完。如果是登录方式清一下浏览器缓存重试。公司环境的话确认有没有代理或者防火墙拦截。问题Node 版本报错node -v看版本低于 18 就升级。用 nvm 的话nvm install 20 nvm use 20。6.2 使用过程中的典型问题问题它改的文件不对大概率是项目结构复杂它没找到正确的文件。这时候别让它瞎猜直接告诉它文件路径改 src/utils/date.ts 里的 formatDate 函数不是 src/legacy/date.js或者在 CLAUDE.md 里写清楚目录职责减少它找错文件的概率。问题改完代码跑不起来先看 diff确认它改了什么。常见原因是它引入了不存在的依赖或者改了函数签名但没更新调用方。让它自己排查代码跑不起来了报错是 XXX帮我看看哪里出了问题把报错信息贴给它它一般能定位。问题它执行了危险命令比如rm -rf之类的。默认情况下它执行命令前会问你但如果你开了自动执行就要小心。我的建议是永远不要对删除、覆盖类操作开自动执行。权限设置里可以精细控制把危险操作保留为手动确认。问题响应很慢或者超时可能是网络问题也可能是任务太复杂。把大任务拆成小步骤一步步来。比如别一次性说重构整个项目而是先重构这个模块再重构下一个。6.3 常见问题速查表现象可能原因解决方向命令找不到PATH 未配置检查 npm 全局 bin 目录认证失败网络/Key/权限逐项排查确认账号状态改错文件项目结构复杂明确指定路径完善 CLAUDE.md代码跑不起来依赖或签名问题看 diff贴报错让它排查响应慢网络或任务过大拆解任务检查网络重复犯同样的错缺少项目上下文更新 CLAUDE.md6.4 几条实操心得第一前期多手动确认后期再放权。刚开始用所有操作都手动确认观察它的行为模式。用熟了、信任了再对低风险操作开自动执行。第二任务描述要具体。别说优化一下这个函数要说这个函数在输入为负数时返回了错误结果帮我修复并加测试。描述越具体它做得越准。第三善用 Git 做安全网。每次让它改代码前确保工作区是干净的或者先 commit 一下。这样改坏了随时能回滚。我习惯在让它做大改动前先git stash或者开个新分支。第四别把它当搜索引擎。它的强项是在你的项目上下文里干活问它通用的编程问题不如直接查文档。把它的能力用在理解我的代码并动手改上价值最大。第五CLAUDE.md 是长期投资。花半小时写好它后面每次对话都受益。这个投入产出比非常高。7. 从跑通到用顺几个进阶方向跑通第一次修改之后你可以逐步尝试更多场景。比如让它帮你做代码审查把 PR 的 diff 贴给它让它找潜在问题比如让它根据现有代码风格生成新模块的骨架比如处理那些重复性的重构像批量替换某个 API 的调用方式。还有一个很实用的场景是跨文件重构。比如你要把一个工具函数从 A 文件移到 B 文件同时更新所有引用。手动做容易漏交给它它会搜索所有引用点一次性改完。这种活儿它比人靠谱。另外如果你在团队里推广建议把 CLAUDE.md 纳入代码库作为项目文档的一部分维护。新人入职时这份文件既是给 AI 看的也是给人看的项目说明一举两得。我自己用下来最大的感受是Claude Code 不是替代你写代码而是把你从找文件、改多处、跑验证这些机械劳动里解放出来让你专注在要做什么、做得对不对上。这个定位想清楚了用起来就顺了。