如果你写过一阵子代码大概率已经听过 Claude Code 的名字。它是 Anthropic 官方推出的命令行 AI 编程工具直接在终端里读懂整个项目按你的指令改代码、修 bug、跑测试甚至能帮你解释一段没人敢动的祖传逻辑。这篇教程我按自己实际折腾过的路径来写从零开始装好环境、完成配置再到真正上手改第一处代码尽量把每一步的“为什么”也讲清楚而不是只给一串命令。适合谁看完全没用过 Claude Code 的新手或者装过但没跑通、卡在登录或权限环节的人。如果你已经在日常用 Copilot 或 Cursor这篇也能帮你快速对比出 Claude Code 在“整个仓库级别操作”上的差异。我默认你用的是 Windows / macOS / Linux 任一系统能打开终端剩下的我们一步步来。1. 安装前的准备与环境要求1.1 Claude Code 到底是什么Claude Code 本质上是一个跑在终端里的命令行工具通过自然语言和 Claude 模型交互。它和你平时用的 ChatGPT 网页版最大的区别是它能直接看到你当前目录下的文件结构、读取文件内容、执行终端命令并且在你授权后修改代码文件。也就是说它不像聊天机器人那样“只给建议”而是真正把手伸进代码库帮你把事做了。它适合处理三类很典型的任务。一是跨文件的代码修改比如把项目里所有接口的返回格式从 JSON 改成 XML人工改可能要找几十个文件Claude Code 可以在一次对话里扫描并逐文件修改。二是理解陌生项目你接手一个新仓库直接让它梳理模块结构、画调用链虽然它不会真的画图但能输出清晰的文字关系。三是跑命令和脚本比如让它帮你执行测试、格式化、构建然后根据报错继续调整。这三点构成了它的核心价值不是“问答”而是“动手”。1.2 需要提前装好的软件安装 Claude Code 之前我建议你先确认机器上有 Node.js 和 Git。这两个不是可选项而是基础依赖。Node.js 是 Claude Code 的运行环境它本身是 JavaScript 写的需要通过 npm 全局安装。Git 则用于版本管理和识别项目状态Claude Code 很多操作会依赖 Git 来查看改动、创建提交比如它帮你改完代码后你可以对比 diff或者让它自己 commit。哪怕你的项目不是 Git 仓库它也会尝试读取 Git 配置没有 Git 的话一些功能会变得不太顺手。检查方法很简单在终端里分别输入node -v npm -v git --version如果能输出版本号比如v20.11.0、10.2.4、2.43.0就说明已经装好。如果提示“command not found”那就需要先装。Node.js 我建议装 LTS 版本长期支持版例如 20.x 或 22.x。不推荐用太老的版本Claude Code 对 Node.js 版本有最低要求太老会出现奇怪的兼容性报错。Python、MySQL 这些和它没有直接关系纯属凑热闹不用装。1.3 操作系统与终端选择Claude Code 官方支持 Windows、macOS、Linux但不同平台体验有细微差异。Windows 上最好用 PowerShell 5.1 或 Windows Terminal。旧版 CMD 可能会有编码和交互渲染问题建议早点换掉。macOS 上直接用自带的 Terminal 或 iTerm2 都行。Linux 上只要是常见的 bash/zsh 都没问题。我见过不少 Windows 用户在安装时卡住最后发现是 PowerShell 执行策略限制导致 npm 全局命令无法运行。如果遇到cannot be loaded because running scripts is disabled这类报错可以用管理员身份打开 PowerShell执行Set-ExecutionPolicy -Scope CurrentUser RemoteSigned然后输入Y确认。这个操作只是允许本机运行签名的本地脚本不会影响系统安全。2. 安装 Claude Code官方方法与常见坑2.1 通过 npm 全局安装等 Node.js 环境就绪后安装过程就是一条命令npm install -g anthropic-ai/claude-code这条命令会把 Claude Code 安装到全局 node_modules并生成一个claude命令。安装过程可能需要一两分钟取决于网速。如果下载慢可以配置 npm 的镜像源但这不是 Claude Code 特有的事属于 npm 本身的优化。不建议在安装时就折腾第三方模型接入先保证官方默认安装成功后面再谈扩展。安装完成后验证一下claude --version能输出类似Claude Code 2.x.x的版本号就说明装好了。如果提示找不到命令大概率是 npm 全局目录没加到 PATH 里。可以通过npm config get prefix查看全局安装路径然后把对应 bin 目录加到系统环境变量。这个属于 Node.js 常见问题网上资料很多不赘述。2.2 登录与身份验证第一次运行claude会进入交互式界面并提示你登录 Anthropic 账号。这里有两种选择如果你的账号绑定了订阅服务直接按提示在浏览器里完成授权如果是用 API 方式可以在后续设置环境变量ANTHROPIC_API_KEY。我不推荐把 API Key 直接写在终端命令里因为会留在 shell 历史中。更稳妥的做法是配置在系统环境变量里或者在项目根目录建一个.env文件注意别提交到 Git。Claude Code 在启动时会读取ANTHROPIC_API_KEY环境变量如果检测到有效凭据就不需要交互式登录。提示登录时如果浏览器没有自动弹出授权页终端会显示一个 URL手动复制到浏览器打开再粘贴回调地址即可。这个流程和大多数 CLI 工具一致不用慌。2.3 升级与卸载Claude Code 更新频率不算低。升级命令npm update -g anthropic-ai/claude-code卸载则是npm uninstall -g anthropic-ai/claude-code升级前最好留意官方更新日志因为大版本更新有时会改变配置文件结构或命令参数。我吃过一次亏从某个旧版本直接跳级更新后claude命令一直报配置解析错误后来删除旧的settings.json重置配置才恢复。2.4 桌面版和 VS Code 扩展除了纯命令行版本Claude Code 也有桌面版和 VS Code 扩展。桌面版适合不想碰终端的用户但它的本质还是包了一层图形界面核心能力不变。VS Code 扩展则让我觉得“AI 编程”体验更完整——你可以在编辑器里打开终端直接跑claude修改结果实时显示在文件树上。配置方式和命令行一致因为扩展底层调用的还是同一个 CLI。我的建议是新手先专注命令行版原因是教程和社区问答大多围绕 CLI 展开遇到问题更容易搜到答案。等熟悉了关键操作再按需装扩展或桌面版。3. 核心配置让 Claude Code 更好用3.1 项目级设置CLAUDE.md 是你的“项目说明书”Claude Code 会在当前工作目录读取两个重要配置一个是全局的用户配置另一个是项目根目录下的CLAUDE.md。后者是它的“记忆文件”每次启动都会读取。我在项目里通常这样写# 项目说明 这是一个人力资源管理系统后端使用 Python FastAPI前端是 React。 # 代码风格 - Python 代码使用 type hints所有函数必须写 docstring - 前端组件使用 TypeScript禁止使用 any - 数据库迁移文件放在 migrations/ 目录 # 常用命令 - 安装依赖pip install -r requirements.txt - 运行测试pytest tests/ -v - 启动服务uvicorn app.main:app --reload这样做的好处是Claude Code 每次读文件改代码时都会先看到这些规则不会自作主张改乱代码风格。比如我的项目要求所有新函数写类型注解如果不在CLAUDE.md里声明它有时会生成没有注解的代码我还得手动补。写清楚之后它生成的代码风格基本一致。3.2 用户级设置settings.json全局配置文件一般位于用户主目录下的.claude/settings.json。里面可以控制权限模式、模型选择、输出样式等。一个典型的配置片段{ permissions: { defaultMode: acceptEdits, allow: [ Bash(npm run *), Read(.*), Edit(.*) ], deny: [] }, model: claude-sonnet-4-20250514, verbose: true }defaultMode是权限模式的默认值常见的有三种default每次修改和命令执行都询问确认。acceptEdits自动接受文件编辑但执行命令前仍询问。plan只输出修改计划不实际动文件。新手我建议先保留default等你对它的行为模式足够熟悉再改为acceptEdits。我见过有人直接设为全自动结果 Claude Code 一口气改了十几个文件有些改动不是他想要的回滚起来很麻烦。allow数组用于配置允许自动执行的操作用正则表达式匹配命令。比如Bash(pytest)表示允许直接运行 pytest 命令。这里要注意正则写得太宽松容易带来风险比如Bash(.*)等于把所有命令都放行了非常不建议。我一般只放行测试、构建这类相对安全的命令。3.3 环境变量与 API 配置如果你不是用订阅账号登录而是走 API 方式需要在环境变量里设置# macOS / Linux export ANTHROPIC_API_KEY你的key # Windows PowerShell $env:ANTHROPIC_API_KEY 你的key设置完后重新运行claude就不需要登录步骤了。另外还有一个常见需求用 Claude Code 调用本地模型比如 LM Studio 里的 Qwen。这本质上是在 Clude Code 的兼容层里配置一个 OpenAI 风格的接口地址。因为 Claude Code 本身支持通过环境变量覆盖 API 端点所以思路是把它指到本地服务。具体配置涉及ANTHROPIC_BASE_URL这类变量以及模型名称参数。不过我要提醒一句本地小模型的代码修改能力远不如官方 Claude 模型玩玩可以真干活容易翻车。我实测过用 7B 级别的本地模型让它改一个跨文件的重构任务效果比较勉强。3.4 VS Code 集成的小技巧在 VS Code 里使用 Claude Code 不一定要装官方扩展。我常用的做法是在 VS Code 内置终端里启动claude这样它在修改文件时我可以直接在旁边的编辑器里看到改动配合 Git 面板查看 diff。这种“终端 编辑器”组合的好处是Claude Code 执行命令时输出的内容不会被扩展插件二次包装排查问题更直观。如果想装官方扩展在 VS Code 扩展市场搜索Claude Code安装后可以通过命令面板启动集成终端。配置信息会复用已经登录的 CLI 账号不需要重复授权。4. 第一次代码修改从需求到落地4.1 启动和选择工作目录打开终端进入你的项目目录cd /path/to/your/project claude启动后你会看到交互式提示符。此时 Claude Code 已经扫描了当前目录的文件结构你可以直接提需求。如果项目很大首轮响应可能会稍微慢一些因为它要读取目录树和部分关键文件。建议不要在这个项目里放一堆无关的二进制文件或 node_modules最好先配置.gitignore否则 Claude Code 会尝试读取一些不该读的文件拖慢速度。它本身会跳过常见噪音目录但碰到奇怪的文件结构还是会影响效率。4.2 实战修改一个 Python 函数我以一个具体的例子来说明。假设我的项目里有一个utils.py里面有个函数def format_name(first, last): return first last这个函数没有处理空值而且用的是字符串拼接而不是 f-string我想让 Claude Code 重构它。在终端里输入请修改 utils.py 中的 format_name 函数 1. 使用 f-string 返回全名 2. 处理 first 或 last 为空字符串的情况 3. 如果全名为空返回 unknownClaude Code 会先读取utils.py然后给出它的修改方案并询问是否应用。如果你已经设置defaultMode为default它会等你确认如果是acceptEdits它可能直接改。我这次先保留默认模式看到它的 diff 后再选择接受。修改后的代码大概是这样def format_name(first: str, last: str) - str: full_name f{first} {last}.strip() return full_name if full_name else unknown这是很标准的一次“指令 - 修改 - 确认”流程。你可以看到它不只是机械替换还理解了“空字符串”和“全名为空”的区别。4.3 文件修改与权限确认机制Claude Code 的文件修改有一套权限系统。当你提出修改请求后它会尝试使用Edit工具此时如果你处于默认模式终端会显示即将修改的文件路径和 diff 摘要并让你选择允许、拒绝或记住决定。如果你经常对某个文件执行修改可以在settings.json的allow中加入对应的Edit正则规则以后就不用每次都确认。但有个细节acceptEdits只自动接受“文件编辑”权限不会自动放行“命令执行”。这意味着即使你开了自动编辑它要运行python、git、npm等命令时仍会询问。这是一个很合理的安全边界我不建议为了省事把命令权限也全部开放。4.4 更复杂的修改场景跨文件引用重构一次修改往往不止动一个文件。比如你要把format_name的命名改为build_display_name并同步更新所有引用它的文件。这时你可以直接说把 format_name 重命名为 build_display_name并更新项目中所有调用它的地方Claude Code 会先全局搜索format_name的出现位置然后逐个文件修改调用点最后给你一份汇总清单。我在一个两百多文件的 Django 项目里试过类似的重构它的表现比我想象中稳定没有漏改。不过做完之后我建议立刻用它的“执行测试”能力跑一遍测试套件确认没有破坏引用关系运行 pytest如果有失败帮我分析原因并修复这个过程非常接近真实开发者的工作流修改、测试、修复。4.5 命令执行与 Git 操作Claude Code 不仅能改代码还能执行终端命令。你可以让它查看 Git 状态git status它会返回你当前分支、修改文件列表。如果你想提交所有改动可以说把这次修改的代码提交commit message 写 refactor: rename format_name to build_display_name它会执行git add和git commit。这里有个安全提示让 AI 执行 Git 操作前最好确认改动是你想要的。我的习惯是先让它git diff展示变更再确认是否提交。如果改错了就用git checkout -- file还原。Claude Code 自己也能做这些还原操作但你自己先看一眼更稳妥。5. 常见问题与排查技巧实录5.1 安装失败或claude命令找不到这类问题最多。核心排查路径是先确认 Node.js 和 npm 版本、再看 npm 全局路径是否在 PATH 中、最后看网络状况。如果你在安装时看到npm ERR!快速解决办法是清理 npm 缓存后重装npm cache clean --force npm install -g anthropic-ai/claude-code如果安装成功但claude命令无法识别执行npm config get prefix比如输出是C:\Users\你的用户名\AppData\Roaming\npm那么就把这个目录加到系统 PATH。macOS 上通常会在/usr/local/bin或~/.npm-global/bin看你的 npm 配置。5.2 登录认证失败或提示无订阅访问权限登录时可能出现浏览器已经授权但终端仍然报错的情况。首先检查你的账号是否已开通订阅。如果你用的是公司统一账号可能被组织策略限制别硬刚换个人账号或走 API Key 方式。如果是 API Key 方式确认环境变量是否生效。Windows PowerShell 里可以用echo $env:ANTHROPIC_API_KEYmacOS/Linux 用echo $ANTHROPIC_API_KEY如果输出为空说明环境变量没设置成功。设置完后要重启终端才会生效。还有一种情况是 Key 本身有效但终端代理环境变量干扰了 SDK 请求可以先临时取消这些变量再试。5.3 修改过程中“失控”怎么办Claude Code 有时会修改超出你预期范围的文件。比如你让它修复某个 bug它却顺手重构了同目录下的另一个模块。遇到这种情况最快的回滚方式是 Gitgit diff file git checkout -- file如果你还没提交可以通过git diff查看所有变更再决定保留哪些。如果你设置了acceptEdits建议在会话开始时跟它强调一句“只修改我指定的文件不要改动其他代码”。虽然它不一定百分之百遵守但说出来总比不说强。另一种“失控”是它反复尝试执行命令但没有达到预期。我在本地模型接入时遇到过它生成了一堆不存在的命令一个接一个执行每次都问我要不要允许。这种情况多半是模型能力不足导致的换回官方模型或更强大的模型就能解决。5.4 排查技巧用 h 和 /help 快速了解上下文交互界面里有很多内置斜杠命令。最常用的几个/help显示所有命令说明。h查看对话历史和相关操作。/compact压缩上下文当对话太长、响应变慢时使用。/init生成或更新项目的 CLAUDE.md。我注意很多人不知道/init它是自动分析项目结构并生成CLAUDE.md的命令。在陌生项目里先执行/init能省不少事它会根据现有代码推断模块结构、测试方式然后生成一份基础记忆文件。你再根据实际需求微调即可。5.5 关于第三方模型接入的补充热词里经常出现“cc switch 接入 deepseek、qwen、glm”这类操作本质上是修改 Claude Code 调用的 API 端点和模型名。这类工具我建议心态要放平第三方模型接入是为了体验或成本控制但 Claude Code 的 Agent 能力和模型本身强相关模型弱了很多高级功能比如多步规划、复杂重构会变成笑话。真要干活还是官方模型最稳。如果你只是想在“不耗官方额度的前提下试试流程”可以考虑在项目里建一个单独的分支或文件夹测试别拿生产代码冒险。配置方法多数工具会生成一份settings.json你只需确保模型名和接口地址填对。6. 从入门到顺手我的几点实操体会我第一次用 Claude Code 时犯的最大错误是把它当成高级聊天机器人指令说得含糊比如“帮我看看这个项目哪里有问题”。结果它扫描完文件后给了一堆无毒但无用的建议。后来我养成了“像给同事派活一样”描述需求的习惯说明背景、范围、验收标准效果立刻不一样。比如不要说“优化这段代码”而是说优化 UserService 里的 get_user 方法 - 目前每次查询都访问数据库性能差 - 请改成使用缓存缓存 key 为 user:{id} - 保持返回结构不变 - 改动后运行 tests/test_user_service.py 验证另一个体会是Claude Code 的输出质量高度依赖上下文质量。如果项目文件本身很乱它会继承这种混乱。这时候先花十分钟整理CLAUDE.md比反复追问更划算。还有一点是关于安全边界的。我会允许它自动编辑代码但命令执行永远保留确认。因为代码改错了可以回滚但它如果执行了rm -rf或者连到线上数据库改数据后果就严重了。虽然它不至于蓄意破坏但理解错了指令、执行了危险命令的可能性是存在的。保持最后一道人工确认是对项目负责。依赖模型的生成式工具每天都在进化但核心工作方法没变清晰表达需求、检查变更、跑测试、再确认。Claude Code 只是把“改代码”这个动作变得更快了做决定的还是你。