Claude Code 入门实战：从安装配置到第一次代码修改

1. 为什么我建议你从命令行开始用 Claude Code很多人第一次听说 Claude Code脑子里浮现的画面是又一个 AI 聊天窗口觉得无非是把问题贴进去、把代码复制出来。如果你也这么想那大概率会在装完之后十分钟内把它卸载——因为你根本没用到它真正的能力。Claude Code 的核心价值不在于回答问题而在于它能直接读写你本地的项目文件、执行终端命令、理解整个代码仓库的上下文然后像一个坐在你旁边的同事一样把改动真正落到磁盘上。这个差别决定了你必须把它装在一个真实的项目目录里而不是随便找个空文件夹玩。我接触过不少朋友卡在第一步的原因五花八门有人 Node.js 版本太老有人 Git 没配好导致 Claude Code 无法感知文件变更有人在 Windows 上被环境变量折腾到放弃。这些问题本身都不难难的是没有一个从零到跑通的完整路径。这篇内容就是干这个的——从安装、配置、写第一份 CLAUDE.md到让它真正帮你改完第一段代码并提交到 Git我会把每一步的意图和坑都讲清楚。适合谁看如果你满足下面任意一条这篇就是写给你的完全没碰过 Claude Code想找个靠谱的入门路径装过但没跑通卡在环境或认证环节已经能对话但不知道怎么让它改代码、怎么和 Git 配合想在自己的 Windows、macOS 或 Linux 机器上把它用起来而不是只在别人的演示视频里看。我会尽量把为什么这么做讲透因为入门阶段最怕的就是照抄命令却不知道自己在干什么一旦报错就彻底懵了。在正式开始之前先明确一个前提Claude Code 是一个跑在终端里的工具它依赖 Node.js 运行时并且强烈建议在 Git 仓库里使用。所以整条链路是Node.js → Claude Code → Git 仓库 → 第一次代码修改。这个顺序不要乱后面每一步我都会解释它为什么排在这个位置。2. 装之前先把地基打好Node.js 与终端环境2.1 Node.js 版本这道坎比你想的更重要Claude Code 是通过 npm 分发的这意味着你机器上必须有一个能正常工作的 Node.js 环境。很多人栽在这里不是因为没装而是因为装了个太老的版本。我的建议是直接上Node.js 18 LTS 或更高如果你不确定自己现在是什么版本打开终端敲一行node -v npm -v如果输出的版本号低于 18别犹豫去官网下最新的 LTS 版本覆盖安装。这里有个细节值得说Windows 用户下载.msi安装包时安装向导里会有一个Automatically install the necessary tools的勾选项很多人习惯性跳过。我的经验是如果你后续要用到需要编译的原生模块这个勾选能省掉你后面手动装构建工具的麻烦建议勾上。macOS 用户如果用的是 Homebrewbrew install node一条命令就够但要注意 Homebrew 装的 Node 有时会和系统里已有的版本打架装完记得which node确认一下路径。为什么版本这么关键因为 Claude Code 内部用到了较新的 JavaScript 语法和部分 Node API老版本运行时会在启动阶段直接抛错而且报错信息往往很隐晦看起来像是网络问题或者权限问题实际根源就是版本。我见过有人折腾了一下午认证最后发现是 Node 14 在作祟。所以这一步别省先确认版本再往下走。2.2 终端的选择别用错工具给自己添堵Claude Code 是终端程序你用什么终端直接决定了体验。Windows 上我强烈建议用Windows Terminal配合 PowerShell或者干脆用 Git Bash。老式的 cmd.exe 在字符渲染和颜色支持上会让你怀疑人生尤其是 Claude Code 输出带格式的内容时cmd 经常显示成一团乱码。macOS 和 Linux 用户就简单了系统自带的 Terminal 或者 iTerm2 都行没什么坑。还有一个容易被忽略的点终端的编码。Windows 上如果终端默认编码不是 UTF-8中文路径或者中文输出可能变成乱码。你可以在 PowerShell 里执行chcp 65001临时切到 UTF-8想永久生效就改系统区域设置里的Beta: 使用 Unicode UTF-8 提供全球语言支持。这个设置对后续处理含中文注释的代码文件很有帮助值得花两分钟搞定。2.3 Git 不是可选项是必需品标题里提到了 Git这不是凑关键词。Claude Code 的很多能力是建立在 Git 之上的它能感知哪些文件被修改了、能帮你生成提交信息、能在你要求时回滚改动。如果你在一个非 Git 目录里运行它虽然也能对话但会失去一大半改代码的便利性。所以装完 Node.js顺手把 Git 也配好。Windows 用户去 Git 官网下安装包一路默认即可但有一个选项要注意安装向导里会让你选择默认编辑器如果你不熟悉 Vim千万别选 Vim选 VS Code 或者 Notepad 都行否则以后每次 Git 让你写提交信息都会陷入怎么退出 Vim的经典困境。装完之后配置一下身份这是提交代码的前提git config --global user.name 你的名字 git config --global user.email 你的邮箱macOS 用户如果装了 Xcode Command Line ToolsGit 通常已经自带了git --version能出版本号就不用再装。Linux 用户sudo apt install git或对应的包管理器命令即可。配好之后用git config --list检查一下确认 user.name 和 user.email 都在这一步没做的话后面 Claude Code 帮你提交时会直接失败。3. 安装 Claude Code一条命令背后的门道3.1 全局安装与权限问题环境就绪后安装本身其实只有一条命令npm install -g anthropic-ai/claude-code但这条命令在不同系统上会遇到不同的权限问题。macOS 和 Linux 用户如果直接这么敲很可能报EACCES权限错误因为全局安装要往系统目录写文件。有两种解法一是加sudo但我不推荐因为 sudo 装的包后续升级、卸载都容易出权限混乱二是配置 npm 的用户级全局目录一劳永逸mkdir -p ~/.npm-global npm config set prefix ~/.npm-global export PATH~/.npm-global/bin:$PATH最后那行 export 要写进你的 shell 配置文件.bashrc、.zshrc之类否则新开终端就失效了。Windows 用户一般不会有权限问题因为 npm 默认装在用户目录下但如果你的 Node 是装在 Program Files 里的也可能遇到权限报错这时候用管理员身份打开终端重装一次即可。装完之后验证一下claude --version能输出版本号就说明装成功了。如果提示command not found八成是 PATH 没配好回头检查上面那步。这个报错非常常见别慌就是环境变量的事。3.2 首次启动与认证流程第一次运行claude它会引导你完成认证。这个过程会打开浏览器让你登录账号并授权授权完成后终端会拿到一个凭证。这里有几个实操心得第一认证需要浏览器和终端在同一台机器上。如果你是在远程服务器上装 Claude Code浏览器打不开就得用另一种方式——通常是复制终端给出的链接在本地浏览器打开授权再把拿到的码贴回终端。这个流程第一次做会有点绕但跟着提示走就行。第二认证凭证会存在本地配置目录里一般不需要每次重新登录。但如果你换了机器、重装了系统或者手动清了配置目录就得重新走一遍。第三如果你所在的组织对账号访问做了限制可能会在认证阶段看到权限相关的提示。这种情况不是安装问题而是账号层面的策略需要联系你的管理员不是靠改配置能绕过的。遇到这类提示先确认自己的账号状态别在安装环节反复折腾。3.3 在 VS Code 里用 Claude Code热词里频繁出现vscode 配置 claude codeclaude code for vs code说明很多人希望在编辑器里直接用。这是完全可行的而且体验不错。核心思路是Claude Code 本体还是那个终端程序VS Code 只是提供了一个集成终端让你不用来回切窗口。具体做法是在 VS Code 里打开你的项目文件夹然后调出集成终端快捷键通常是 Ctrl或 Cmd在里面直接运行claude。因为集成终端的工作目录就是你的项目根目录Claude Code 一启动就能看到整个项目省去了手动 cd 的步骤。如果你想让这个流程更顺手可以在 VS Code 的 settings 里把默认终端设成你习惯的那个PowerShell、bash、zsh 都行避免每次都要手动切换。有一点要提醒VS Code 的集成终端和系统终端在环境变量上偶尔会有差异尤其是 Windows 上。如果你在系统终端里claude能用在 VS Code 里却提示找不到命令多半是 VS Code 没继承到最新的 PATH。解决办法是彻底重启 VS Code不是重载窗口是完全退出再打开让它重新读取系统环境变量。4. CLAUDE.md让 Claude Code 真正懂你的项目4.1 这个文件到底解决什么问题装好之后很多人上来就开始问问题结果发现 Claude Code 的回答很泛像是不知道自己在哪个项目里。原因很简单它默认对你的项目一无所知只能靠临时读取文件来猜。而CLAUDE.md就是解决这个问题的——它是放在项目根目录的一份说明文件Claude Code 每次启动时会自动读取它把它当作项目的背景知识。你可以把它理解成给新同事写的入职文档这个项目是干什么的、用什么技术栈、代码放在哪、怎么跑起来、有哪些约定俗成的规矩。写得好Claude Code 的表现会有质的提升不写它就只能靠现场摸索效率和准确度都打折扣。4.2 一份能用的 CLAUDE.md 该写什么我的建议是别一上来就追求面面俱到先写最关键的几块用起来之后再逐步补充。一个实用的起步模板大概长这样# 项目说明 这是一个基于 Node.js 的 Web 服务提供用户管理相关的 API。 # 技术栈 - 运行时Node.js 18 - 框架Express - 数据库PostgreSQL - 测试Jest # 目录结构 - src/routes路由定义 - src/services业务逻辑 - src/models数据模型 - tests测试文件 # 开发约定 - 所有新接口必须有对应的测试 - 提交信息用中文格式为类型: 描述 - 不要直接修改 migrations 目录下的历史文件 # 常用命令 - 启动开发服务npm run dev - 跑测试npm test - 代码检查npm run lint这份文件的价值在于它把那些你脑子里知道但没写下来的信息显性化了。比如不要改历史 migration这条如果你不写Claude Code 在帮你重构时可能真会去动它然后引发一堆数据库问题。写下来它就会避开。4.3 维护 CLAUDE.md 的几个经验第一它是活的文档。每次你发现 Claude Code 做了某件你不希望它做的事就把对应的约束补进去。比如它老是忘记跑测试就提交你就在约定里加一条提交前必须运行 npm test。这种踩坑后补充的方式比一开始憋一份完美的文档要实际得多。第二别写太细。CLAUDE.md 是给 AI 看的背景不是 API 文档。把每个函数的参数都列进去没意义反而占用了上下文空间。抓住项目是什么、怎么跑、有什么规矩这三条主线就够了。第三可以分层。如果你的项目很大根目录放一份总览各个子模块目录里再放各自的 CLAUDE.mdClaude Code 在处理对应目录时会读取就近的那份。这个机制对大型仓库特别有用能让它在你关心的模块里获得更精准的上下文。5. 第一次代码修改从对话到落盘的完整链路5.1 先建一个 Git 仓库别在裸目录里动手在让 Claude Code 改代码之前务必确保你的项目是一个 Git 仓库。如果还不是进到项目目录执行git init git add . git commit -m 初始提交为什么要先提交一次因为这样你就有了一个干净的起点。Claude Code 改完代码后你可以用git diff清楚地看到它到底改了什么不满意就git checkout .一键还原。没有这个起点改动就是不可逆的出了问题只能靠记忆手动改回来非常痛苦。这一步还有个隐藏好处Claude Code 能通过 Git 状态感知哪些文件是新增的、哪些是修改的从而更准确地理解你的工作进度。它甚至能帮你生成符合规范的提交信息。所以别跳过 Git它是整个工作流的安全网。5.2 描述需求的方式决定了改动的质量很多人第一次让 Claude Code 改代码就丢一句帮我优化一下这个文件然后期待奇迹。结果往往是它改了一堆你不需要的地方或者理解偏了方向。正确的做法是把需求拆成目标 范围 约束三部分。举个例子假设你想给一个接口加上参数校验。差的描述是给用户接口加校验。好的描述是在 src/routes/user.js 的创建用户接口里加上对 email 和 password 的校验。email 要符合邮箱格式password 长度至少 8 位。校验失败时返回 400 和错误信息。不要改动其他接口也不要引入新的依赖。这个描述明确了改哪个文件、改什么、边界在哪、有什么限制。Claude Code 拿到这样的指令基本能一次做对。而模糊的指令会让它自由发挥发挥的结果往往不是你想要的。5.3 观察它改代码的过程别当甩手掌柜Claude Code 在动手前通常会先读取相关文件、理解上下文然后提出改动方案。这个过程中它会显示自己在读哪些文件、准备做什么。我的建议是认真看这个过程尤其是前几次使用。原因有两个一是你能及时发现它理解偏了在它改坏之前叫停二是你能从它的思路里学到东西比如它会先看测试文件来理解预期行为这个习惯本身就值得借鉴。当它提出要修改文件时一般会征求你的确认。这时候别条件反射地按回车花几秒看看它打算改什么。如果改动范围超出你的预期直接告诉它只改 X别动 Y它会调整。这种来回沟通是正常的用熟了之后你会形成自己的节奏。5.4 改完之后用 Git 验收成果改动落盘后第一件事是看 diffgit diff这会显示所有被修改的内容。重点看三样改动是否只发生在你指定的范围内、逻辑是否符合预期、有没有引入奇怪的格式变化比如整个文件被重新缩进。如果一切正常跑一下测试确认没破坏现有功能npm test测试通过就可以提交了。你可以让 Claude Code 帮你写提交信息也可以自己写。如果让它写记得检查一下内容是否准确别闭眼提交。提交命令git add . git commit -m feat: 为用户创建接口添加参数校验如果改动有问题git checkout .丢弃所有未提交的改动回到干净状态重新描述需求再来一次。这个改—看—测—提交或回滚的循环就是你和 Claude Code 协作的基本节奏跑顺了之后效率提升非常明显。6. 新手最容易卡住的几个地方6.1 命令找不到、认证失败、权限报错这三类问题占了新手求助的绝大多数。命令找不到九成是 PATH 问题回头检查 npm 全局目录有没有加进环境变量。认证失败先确认浏览器和终端在同一台机器远程场景要用链接加码的方式。权限报错macOS 和 Linux 上优先考虑配置用户级 npm 目录而不是无脑 sudo。这里特别说一下 Windows 上的一个高频坑如果你同时装了多个 Node 版本比如系统装了一个nvm 又管了一个claude命令可能指向了错误的那个环境。用where claudeWindows或which claudemacOS/Linux看看它到底在哪再对照npm root -g的输出就能判断是不是装串了。6.2 它改代码改得太热情怎么办有些朋友反馈Claude Code 一动手就改一大片把不相关的文件也动了。这通常是因为需求描述太宽泛或者项目里没有 CLAUDE.md 给它划边界。解决办法有两个一是在指令里明确只改 X 文件二是在 CLAUDE.md 里写清楚哪些目录是敏感的、不要随便动。另外养成先看 diff 再提交的习惯任何超出预期的改动都能在提交前拦下来。6.3 中文项目和编码问题如果你的项目里有中文注释、中文文件名Windows 上要特别注意编码。确保终端是 UTF-8Git 也配置成不自动转换换行符和编码git config --global core.autocrlf false git config --global core.quotepath falsecore.quotepath false能让 Git 正常显示中文文件名不然你会看到一堆八进制转义根本认不出是哪个文件。这两条配置对中文项目来说几乎是必配的。6.4 关于本地模型和其他工具的联想热词里出现了不少关于本地模型、其他代码工具的内容这里简单说一句Claude Code 本身是围绕特定模型服务设计的它的工作流、认证、能力边界都建立在这个基础上。如果你出于某些原因想用本地模型那是另一套工具链的事情配置方式、能力表现都不一样不要指望用同一套步骤套过去。入门阶段我建议先把标准流程跑通建立对AI 改代码这件事的直觉再去探索其他方案否则容易在配置里迷失连基本体验都没建立起来。7. 把它变成日常习惯几个提效的小动作跑通第一次修改之后接下来就是把它融入日常工作流。我自己的习惯是每天开始写代码前先让 Claude Code 读一遍我昨天改动的文件让它快速建立上下文然后我再描述今天要做的任务。这个预热动作花不了一分钟但能让后续的沟通顺畅很多。另一个习惯是善用它的终端执行能力。比如你想跑测试但记不住命令直接问它这个项目怎么跑测试它会读 package.json 告诉你。想批量重命名文件、想查某个函数在哪被调用都可以让它代劳。它不只是改代码更是一个懂你项目的助手。还有一点定期回顾你的 CLAUDE.md。用了一两周之后你会发现有些约束已经内化有些新的坑需要补充。把它当成项目的一部分来维护而不是一次性写完就扔。这份文档的质量直接决定了 Claude Code 在你项目里的表现上限。最后分享一个我踩过的坑刚开始用的时候我总想让它一次完成一个大功能结果改动太大、审查困难、出问题难定位。后来我改成小步快跑——每次只让它做一件明确的小事改完立刻看 diff、跑测试、提交。这样每一步都可控出了问题也能快速回滚。这个节奏看起来慢实际整体效率反而更高因为返工少了。入门阶段稳比快重要。