Claude Code 实战指南：从安装配置到项目代码修改与 Git 提交

1. 为什么我最终把 Claude Code 装进了日常工作流第一次听说 Claude Code 的时候我的反应和大多数人一样命令行里跑一个 AI 编程助手听起来像是极客的玩具真到了项目里能顶什么用直到有一次我需要在一个十几万行的老项目里批量替换一套已经废弃的 API 调用手动改了两百多个文件之后手指发酸、眼睛发花我才认真去研究了一下这个工具。结果一个下午的时间它帮我把剩下三百多个文件全部处理完还顺手把相关的单元测试也更新了。从那天起Claude Code 就成了我终端里常驻的一个窗口。这篇内容想做的事情很明确带你从零开始把 Claude Code 装到你的机器上配置好然后完成第一次真正意义上的代码修改。不是那种打印一个 hello world的演示而是让它在你的真实项目里干活——读代码、改代码、跑测试、提交 Git。整个过程我会把每一步背后的逻辑讲清楚包括我踩过的坑和绕过的弯路。适合谁看如果你已经会用命令行做基本操作知道 Git 是什么写过至少一门编程语言的代码那这篇内容就是为你准备的。如果你完全没碰过终端也不用慌我会把每个命令都解释清楚你照着敲就行。关键词里提到的 Git、CLAUDE.md、VS Code 配置这些我都会在对应的环节展开讲。先说一个很多人关心的问题Claude Code 和你在网页上用的对话式 AI 有什么区别核心差异在于上下文获取方式。网页版你需要手动复制粘贴代码片段它只能看到你给它的那几百行。而 Claude Code 直接跑在你的项目目录里它可以自己读文件、搜索代码、执行命令、查看 Git 历史。这意味着它理解的是你的整个项目而不是一个孤立的代码片段。这个差异在实际使用中带来的效率差距比你想象的大得多。2. 安装前的环境盘点别急着敲命令2.1 Node.js 是绕不开的前置依赖Claude Code 目前的分发方式是通过 npm 包管理器安装所以你的机器上必须有 Node.js 环境。这里有一个很多人忽略的细节Node.js 的版本不能太低。我实测下来18.x 及以上的版本都能正常工作但如果你还在用 16.x 甚至更早的版本安装过程大概率会报错。检查当前版本很简单node --version npm --version如果版本低于 18建议直接去 Node.js 官网下载最新的 LTS 版本。Windows 用户下载 msi 安装包双击安装就行macOS 用户可以用 Homebrewbrew install nodeUbuntu 用户可以用 NodeSource 的源来安装最新版本比系统自带的 apt 源版本要新很多curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs注意如果你之前用 apt 装过旧版本的 Node.js建议先卸载干净再装新版本否则可能出现两个版本共存导致命令冲突的问题。2.2 Git 不只是顺便装一下Claude Code 的很多核心功能都依赖 Git。比如它会通过git diff来查看你当前的代码改动通过git log来理解项目的演进历史在修改代码之后也会建议你提交。如果你的项目没有用 Git 管理Claude Code 的能力会打不少折扣。Windows 用户去 Git 官网下载安装包安装过程中有一个选项叫Adjusting your PATH environment建议选Git from the command line and also from 3rd-party software这样 Git 命令在任意终端里都能用。macOS 用户通常自带 Git但版本可能比较老用brew install git更新一下更稳妥。Ubuntu 用户直接sudo apt install git即可。安装完之后配置一下身份信息这是提交代码时必须的git config --global user.name 你的名字 git config --global user.email 你的邮箱2.3 终端的选择也有讲究Claude Code 是一个交互式的命令行工具它对终端的能力有一定要求——需要支持 ANSI 转义序列来渲染界面。Windows 上我强烈建议用Windows Terminal而不是老旧的 cmd.exe前者对颜色和光标控制的支持好得多。macOS 自带的 Terminal.app 或者 iTerm2 都没问题。如果你在 VS Code 里用集成终端那也可以后面我会讲怎么把 Claude Code 和 VS Code 配合起来用。3. 安装 Claude Code 的完整过程与常见报错处理3.1 一条命令搞定安装环境准备好之后安装本身其实非常简单npm install -g anthropic-ai/claude-code-g表示全局安装这样你在任何目录下都能直接使用claude命令。安装过程会从 npm 仓库拉取包速度取决于你的网络环境。如果卡住不动可以试试切换 npm 的镜像源npm config set registry https://registry.npmmirror.com安装完成后验证一下claude --version能看到版本号就说明安装成功了。3.2 首次启动与认证流程第一次运行claude命令时它会引导你完成认证。整个过程是在浏览器里完成的终端会给出一个链接你打开链接登录账号并授权即可。授权完成后终端会显示认证成功之后就可以正常使用了。这里有一个我踩过的坑如果你在公司网络环境下浏览器和终端可能不在同一台机器上。比如你在远程服务器上安装 Claude Code终端给出的链接在你本地浏览器打开后回调地址指向的是服务器的 localhost这就没法完成认证。解决办法是在本地机器上也装一个 Claude Code 完成认证然后把认证文件复制到远程服务器对应的目录下。认证文件通常在~/.claude/目录下。3.3 安装过程中可能遇到的几个典型问题问题一npm 权限不足。在 macOS 和 Linux 上如果 Node.js 是通过系统包管理器安装的全局安装 npm 包时可能报 EACCES 错误。解决方案是配置 npm 的全局目录到用户目录下mkdir -p ~/.npm-global npm config set prefix ~/.npm-global export PATH~/.npm-global/bin:$PATH把最后一行加到你的.bashrc或.zshrc里下次打开终端就自动生效了。问题二安装成功但命令找不到。这通常是 PATH 没有配置好。用npm config get prefix看看 npm 的全局安装路径在哪里然后确认这个路径下的bin目录在 PATH 里。问题三公司网络限制。有些公司的网络策略会拦截 npm 仓库的访问。如果你确认网络没问题但就是装不上可以试试用代理或者换一个网络环境。这个具体怎么处理取决于你的网络环境我就不展开说了。4. 第一次代码修改从读懂项目到提交改动4.1 让 Claude Code 先看懂你的项目安装好之后进入你的项目根目录直接运行cd /path/to/your/project claude你会看到一个交互式的界面。这时候不要急着让它改代码先让它熟悉一下项目。我的习惯是第一步让它读一下项目的 README 和目录结构请帮我分析一下这个项目的整体结构包括用了什么技术栈、主要的模块划分、以及入口文件在哪里。Claude Code 会自动读取相关文件并给出分析。这一步的价值在于它会建立起对项目的整体认知后续你让它改代码时它知道该去哪里找相关文件而不是盲目搜索。4.2 CLAUDE.md给 AI 写一份项目说明书这是我认为 Claude Code 最值得花时间配置的一个功能。在项目根目录创建一个CLAUDE.md文件里面写清楚项目的关键信息Claude Code 每次启动时都会自动读取这个文件。内容可以包括项目的技术栈和主要依赖代码风格约定比如用几个空格缩进、命名规范常用的开发命令怎么启动开发服务器、怎么跑测试、怎么构建项目的目录结构说明任何你希望 AI 遵守的特殊规则举个例子一个典型的前端项目CLAUDE.md可能长这样# 项目说明 这是一个基于 React TypeScript 的后台管理系统。 ## 常用命令 - 开发npm run dev - 测试npm run test - 构建npm run build - 代码检查npm run lint ## 代码规范 - 使用 2 空格缩进 - 组件文件名用 PascalCase - 工具函数文件名用 camelCase - 所有新组件必须写单元测试 ## 目录结构 - src/components/ 通用组件 - src/pages/ 页面组件 - src/utils/ 工具函数 - src/api/ 接口封装有了这个文件你就不需要每次对话都重复交代项目背景了。我实测下来配好CLAUDE.md之后Claude Code 改出来的代码风格和项目现有代码的一致性明显提升。4.3 一个真实的修改任务给现有函数加参数校验假设你的项目里有一个处理用户注册的函数现在需要给它加上参数校验。你可以这样跟 Claude Code 说在 src/utils/validate.js 里有一个 validateEmail 函数现在它只检查了邮箱是否为空。请帮我增强它加上格式校验要求 1. 必须包含 符号 2. 前面至少有一个字符 3. 后面必须包含至少一个点号 4. 域名部分至少两个字符 改完之后帮我在 tests/validate.test.js 里补充对应的测试用例。Claude Code 会先读取这两个文件理解现有代码的结构和风格然后进行修改。修改完成后它会展示 diff你可以逐条审查它改了什么。如果某处你不满意可以直接告诉它调整。这里有一个使用技巧尽量把需求描述得具体。加上参数校验和检查邮箱格式要求包含 符号且域名部分至少两个字符后者得到的结果会精准得多。Claude Code 不会读心术你给的信息越明确它改出来的代码越符合预期。4.4 审查改动与运行测试Claude Code 改完代码后不要直接接受。我通常的做法是先看它展示的 diff确认改动范围是否符合预期让它运行相关测试请运行 tests/validate.test.js 里的测试如果测试通过再让它跑一下完整的测试套件确保没有破坏其他功能确认无误后让它帮你提交请把这些改动提交到 Git写一个合适的 commit messageClaude Code 执行 Git 提交时会遵循你项目的提交规范。如果你在CLAUDE.md里写了 commit message 的格式要求比如遵循 Conventional Commits它会自动遵守。5. 把 Claude Code 接入 VS Code 的两种方式5.1 在 VS Code 集成终端里直接使用这是最简单的方式。打开 VS Code按Ctrl打开集成终端直接运行claude就行。好处是你可以在编辑器里看代码在终端里跟 Claude Code 对话两边对照着看。但这种方式有一个小问题Claude Code 在集成终端里的界面渲染可能不如独立终端流畅尤其是涉及光标移动和颜色渲染的时候。如果你遇到显示异常可以试试在 VS Code 设置里把terminal.integrated.gpuAcceleration设为off。5.2 通过 VS Code 扩展获得更紧密的集成Claude Code 提供了 VS Code 扩展安装之后可以在编辑器内直接看到 Claude Code 的改动建议点击就能跳转到对应的代码位置。安装方式是在 VS Code 扩展市场搜索 Claude Code 然后安装。装好扩展之后在 VS Code 里打开终端运行claude扩展会自动检测到并建立连接。之后 Claude Code 修改文件时VS Code 会自动打开对应的文件并高亮显示改动区域审查起来方便很多。注意扩展和命令行工具是两个独立的组件需要分别安装。只装扩展不装命令行工具是用不了的。6. 几个让我少走弯路的使用心得6.1 上下文窗口的管理策略Claude Code 的对话是有上下文长度限制的。当你跟它进行了很多轮对话之后早期的内容可能会被遗忘。我的做法是一个任务一个会话。改完一个功能、提交完代码之后退出当前会话重新开始。这样每个会话的上下文都是干净的不会因为历史对话太长而影响效果。如果任务比较复杂需要多轮对话才能完成可以在关键节点让它把当前的理解和计划写到一个临时文件里下次会话开始时先读这个文件恢复上下文。6.2 善用先计划再执行的模式对于涉及多个文件的复杂改动我习惯先让 Claude Code 出一个计划我需要把项目里所有的 API 请求从 fetch 改成 axios。请先不要改代码先给我一个改动计划列出需要修改的文件和每个文件的改动要点。等它列出计划之后我审查一遍确认没问题再让它执行。这样做的好处是避免它改到一半发现方向不对来回返工浪费时间。6.3 遇到问题时怎么排查如果 Claude Code 改出来的代码不符合预期不要直接说不对重来。更好的做法是指出具体哪里不对你修改的 validateEmail 函数里域名部分的校验逻辑有问题。当前的正则表达式会把 userdomain 这种没有点号的邮箱判定为合法但我们的需求是必须包含点号。给它具体的反馈它就能精准地修正。这跟带新人的逻辑是一样的——你告诉它你错了它不知道错在哪你告诉它第三行的判断条件写反了它立刻就能改。6.4 关于安全性的考量Claude Code 在执行某些操作时会请求你的确认比如运行终端命令、修改文件等。不要无脑点同意。尤其是涉及删除文件、修改配置文件、执行数据库操作这类命令时一定要看清楚它要做什么再确认。我一般会在CLAUDE.md里明确写出哪些目录是只读的、哪些操作需要额外确认这样能减少误操作的风险。另外如果你的项目涉及敏感信息比如 API 密钥、数据库密码确保这些内容不在 Claude Code 能读取到的文件里。用.gitignore和.claudeignore把敏感文件排除掉。7. 从第一次修改到日常使用的过渡第一次成功让 Claude Code 帮你改完代码并提交之后你会发现它的使用场景远不止于此。我现在日常会用它做的事情包括写单元测试、重构老旧代码、排查 bug、写文档注释、review 代码改动、甚至帮我分析性能瓶颈。每一个场景的使用方式都不太一样但核心逻辑是一致的给它足够的上下文给它明确的需求然后审查它的输出。有一点需要提醒Claude Code 不是万能的。它偶尔会犯错会误解你的意图会写出看起来对但实际有问题的代码。把它当成一个能力很强但需要监督的助手而不是一个可以完全放手的自动化工具。你审查它改动的能力决定了你使用它的上限。最后分享一个我最近发现的用法当你接手一个陌生的老项目时让 Claude Code 帮你生成一份项目架构文档。它会读取关键文件、分析依赖关系、梳理调用链路最后输出一份结构清晰的说明。这比你自己一个个文件翻要快得多而且它不会漏掉那些藏在角落里的重要逻辑。