最近后台收到最多的问题就是：Claude Code 到底怎么装？装完之后第一次改代码该干什么？我先把答案摆在这里——Claude Code 是 Anthropic 官方推出的命令行编程助手，简单说就是一个跑在终端里的智能体。你输入一句"帮我把登录接口加上参数校验"，它会自己去读写项目文件、执行命令、观察报错、修正后继续，直到任务完成。这篇文章就是一份完整的 Claude Code 入门教程，覆盖从安装、授权登录、配置 VS Code，再到完成第一次真正的代码修改，全程给你能直接抄的步骤和避坑方法。适合所有想用 AI 真正动手改代码的人，不管你是 Vue 前端、Python 后端，还是刚学 Verilog、STM32 的嵌入式玩家，这套流程都通用。
1. Claude Code 是什么：先搞清楚它解决什么问题
1.1 一个能跑命令的"结对程序员"
很多人第一次打开 Claude Code 时会懵：这不是另一个聊天窗口吗？确实，它的界面看起来像个终端里的对话框，但工作机制和网页版聊天完全不一样。
网页版 ChatGPT、Claude 网页版，本质上是"问答机器"，你问一句它答一句，给出一段代码之后，复制粘贴、建文件、装依赖、跑测试，全都要你自己来。Claude Code 不是这样，它运行在你的项目目录里，能直接读取项目文件、修改代码、执行终端命令，甚至在你明确许可的情况下运行测试脚本，然后根据报错信息继续调整，形成一个"读代码——写代码——跑命令——看结果——再修正"的闭环。
打个比方：给一个实习生布置任务，你说"把用户列表接口加上分页"，他得自己去翻项目、找 Controller、改 Mapper、写测试，最后给你交付。Claude Code 就是这个实习生，只不过它不会累、不会抱怨、速度极快。它能做的事包括但不限于：在大型老仓库里定位一段逻辑并重构、给函数补单元测试、解释某段看着像"屎山"的代码、批量修改重复模式、帮你写 Git 提交信息。这套机制有一个专业说法叫 Agent，也就是智能体，而 Claude Code 是当前这个品类里成熟度最高、生态最完整的之一。
1.2 它到底能帮你干哪些活
Claude Code 的核心能力可以分成四个方向，我按实际使用频率排序：
第一，定向修改。这是最常用的场景。比如你有一个 Python 项目，想给数据导出模块增加 CSV 支持；或者在 ESP8266 的固件工程里加一段 PWM 控制逻辑；再比如在 Verilog 代码里补一个状态机的分支。这些任务要是不熟悉项目结构，光靠人肉搜得花半小时，但你可以直接告诉 Claude Code 目标，它会先梳理涉及的文件，再动手改。
第二，排错与解释。遇到报错堆栈，把信息原样贴给它，让它顺着调用链往下查；或者对着一块逻辑复杂的老代码，让它画个数据流解释给你听。实测下来，它的解释比大多数文档写得清楚，因为它会结合你当前的代码上下文。
第三，测试与重构。让它给关键函数补单测，或者把一个三百行的函数拆成多个小函数。这个过程最好配合 Git 使用，改完看一眼 diff，不满意就回滚。
第四，学习辅助。很多朋友在学 Python 零基础、C++、Flutter、FreeRTOS 这些内容时，完全可以把 Claude Code 当陪练老师。比如你学 C51 单片机，有个中断处理逻辑不理解，直接打开工程问它"这段代码为什么会导致定时器冲突"，它会结合你的具体代码给解释，这种学习效率是最高的。
顺便说一句，同类工具还有 Codex，它们在原理上都是"终端里的 AI 编程智能体"。但 Claude Code 对项目级操作的理解、上下文管理能力和工具调用的稳定性，是我目前用得最顺手的，所以这篇文章以它为例来写。
2. 安装前的环境准备
2.1 Node.js 版本检查与安装
Claude Code 是一个 npm 包，所以它在你的机器上运行需要一个 JavaScript 运行时，也就是 Node.js。官方要求 Node.js 18 及以上版本，我建议直接用最新的 LTS 版本，不要用开发版。
先检查你机器上有没有装过 Node.js。打开终端（macOS/Linux 打开 Terminal，Windows 打开 PowerShell 或 Windows Terminal），输入：
node -v npm -v如果看到版本号，比如v20.11.0，说明已经有了，只要大版本号大于等于 18 就能继续。如果提示command not found，说明还没安装。
Node.js 的安装方式取决于你的操作系统。Windows 和 macOS 最简单的方式是去官网下载 LTS 安装包，一路下一步。但我个人更推荐用版本管理工具，因为以后切换版本、升级都很方便：
# macOS 使用 Homebrew 安装 nvm brew install nvm # Linux 使用脚本安装 nvm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash装完 nvm 之后，重开终端，执行：
nvm install --lts nvm use --ltsWindows 用户可以下载 nvm-windows 的安装包，或者使用 winget 装：
winget install OpenJS.NodeJS.LTS安装完成后重新打开终端，此时node -v应该能输出版本号。这一步是整个安装过程中最容易被忽略的坑——很多人命令敲了没反应，结果发现 Node.js 装了但 PATH 没刷新，重启终端就解决了。
2.2 终端、Git 与工作目录准备
Claude Code 的主战场是终端，所以终端的选择直接影响使用体验。Windows 上请务必使用 Windows Terminal 或 VS Code 的内置终端，别再用老旧的 cmd.exe 了——老终端对 UTF-8 的支持很差，Claude Code 输出中文时容易出现乱码。macOS 自带的 Terminal 够用，如果想更舒服可以装 iTerm2。Linux 用户通常自带 Terminal，就不多说了。
另外必须提前装好 Git。Claude Code 修改代码时必须能看到项目的 Git 状态，否则你很难判断它改了什么、能不能安全回滚。Git 安装也是一样，官网下载或者：
# macOS brew install git # Linux (Debian/Ubuntu) sudo apt install git # Windows 建议直接下载 Git for Windows，会附带 Git Bash装完之后创建一个干净的练手目录。我不建议一上来就拿生产项目测试，先准备一个空目录或者一个小项目，把流程跑通再说。我自己第一次用的时候，直接对仓库一顿操作，三方合并、暂存区全被动了，吓得够呛。新手阶段，请一定在副本项目上练习。
mkdir ~/claude-playground cd ~/claude-playground git init如果你还没有任何代码，可以在网上下载一个开源小项目，或者自己手写一个简单的 Python 脚本放进去。后文我会用一个 Python 小工具来做第一次代码修改的实操演示，你可以提前准备类似结构的项目，也可以直接用我的示例。
3. Claude Code 安装全流程
3.1 npm 全局安装与版本验证
环境准备好之后，真正的安装其实就一条命令：
npm install -g @anthropic-ai/claude-code-g 表示全局安装，装完之后claude命令就能在任意目录使用了。安装过程根据网络情况，通常几十秒到几分钟不等。装完之后验证一下：
claude --version正常情况下会输出类似1.0.x的版本号。如果这一步报错，别慌，往下看安装报错三连。
3.2 安装报错三连：权限、执行策略、PATH
我帮人排查安装问题时，90% 的情况是这三个原因之一。
第一个是 EACCES 权限错误。npm 全局安装需要写入系统目录，macOS/Linux 下如果 Node.js 不是通过 nvm 安装的，经常遇到EACCES: permission denied报错。解决办法有两种：一是用 nvm 重装 Node.js，这样全局目录就在用户主目录下，不需要 sudo；二是不想重装，那就用sudo npm install -g临时解决，但这会留下权限隐患，后面每次更新都要 sudo，我不推荐。
第二个是 Windows PowerShell 执行策略限制。报错大概是无法加载 claude.ps1，因为在此系统上禁止运行脚本。这是 PowerShell 的安全机制，阻止了第三方脚本运行。解决办法是在管理员权限的 PowerShell 里执行：
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned输入Y确认即可。建议只设置CurrentUser级别，不要动全局策略，保持系统安全。
第三个是"命令找不到"。装完之后执行claude提示command not found或者不是内部或外部命令。这不是安装失败，而是 npm 的全局 bin 目录不在 PATH 里。先执行：
npm prefix -g这个命令会输出 npm 全局目录，比如 Windows 下通常是C:\Users\你的用户名\AppData\Roaming\npm，macOS 下是/usr/local或 nvm 目录。把目录加到 PATH 里就可以。Windows 在"系统属性——环境变量"里加；macOS/Linux 在~/.zshrc或~/.bashrc里加：
export PATH="$(npm prefix -g)/bin:$PATH"改完重启终端，再看claude --version就正常了。
3.3 VS Code 里集成 Claude Code
桌面版和 VS Code 集成是目前很多人问的入口。官方提供了桌面版应用，安装包在官网下载，Windows 下有 exe 安装包，macOS 下有 dmg。桌面版本质上还是终端体验，只是做成了独立应用，看个人喜好。
如果你主力编辑器是 VS Code，那么更推荐直接装官方扩展。在 VS Code 的扩展市场搜索 "Claude Code"，找到 Anthropic 官方发布的扩展，点击安装。装完之后侧边栏会出现一个 Claude Code 面板，你可以在编辑器里直接启动会话。
这个集成的最大好处是：Claude Code 在改代码的时候，旁边就是编辑器的 diff 视图，哪里改了、改了多少，一眼就能看到，比在终端里敲git diff直观得多。我个人现在的主力使用方式就是在 VS Code 里用这个扩展，终端反而用得少了。不过要说明的是，扩展只是换了个外壳，命令运行、授权、配置逻辑和终端版完全一样，所以这篇文章后面的内容对两种方式都适用。
4. 启动与账号授权
4.1 首次启动与浏览器授权流程
安装完成之后，第一次运行claude之前，请确保你已经cd到目标项目目录。Claude Code 的工作目录概念很重要，它默认只操作当前目录及子目录里的内容。
cd ~/claude-playground claude如果是第一次运行，它会提示需要登录。这时终端里会显示一个授权链接和一串 code，按回车或点击链接，浏览器会自动打开。在浏览器页面里选择允许登录，然后回到终端，它就会提示登录成功，并进入对话界面。Claude Code 会询问你用的是订阅账号还是 API 账号——Pro/Max 订阅用户选择订阅登录，按 API 用量付费的开发者选择 API Key 方式。选错问题不大，后续可以改。
登录成功之后，它还会做一次环境检查，包括 Git 状态、工作目录等等。都没问题后就出现输入提示符了，光标在那里等你输入命令。这时候你可以先试试最简单的：
介绍一下当前目录下的项目结构它会给你列出目录树，并对每个文件角色做个简短说明。看到这一步，说明安装和授权已经彻底打通。
4.2 组织禁用、登录超时与 API Key 方案
授权环节有三个高频报错，我在评论区被问烂了。
第一个是Your organization has disabled Claude subscription access for Claude Code。如果你用的是企业订阅，管理员可以在后台关闭 Claude Code 的访问权限。这时候拿这个账号是绕不过去的，要么找管理员开通，要么切换成个人订阅账号，要么改用 API Key 方式。同样道理，如果看到Project not authorized之类的提示，也是组织策略限制了项目访问，处理方式相同。
第二个是登录超时。浏览器开了授权链接，但终端迟迟没反应。这通常是网络环境问题，授权服务器握手不稳定。先确认浏览器能正常打开那个授权页面，能打开就多等几秒；实在不行 Ctrl+C 终止进程，重新执行claude再试一次。注意，我在这里说的只是网络连通性，排查思路就一条：浏览器能打开页面，终端才有戏。
第三个是需要切换成 API Key。如果你没有 Claude 订阅，只想用 API 模式，可以用环境变量指定密钥：
# macOS/Linux export ANTHROPIC_API_KEY="sk-ant-xxxx" # Windows PowerShell $env:ANTHROPIC_API_KEY="sk-ant-xxxx"设置完之后重新运行claude，它会自动跳过浏览器授权，直接用 API Key 认证。这里有一个很多人踩过的坑：ANTHROPIC_API_KEY和ANTHROPIC_AUTH_TOKEN是两个完全不同的变量，前者用于 Anthropic 官方 API 认证，后者用于自定义网关或第三方服务的认证，千万别混用。很多第三方服务只支持ANTHROPIC_AUTH_TOKEN，如果你设置了前者，会一直报 401 认证失败。
5. 第一次代码修改：完整实操演示
5.1 准备一个最小练手项目
讲再多理论，不如来一次完整的实操。我们用一个小 Python 脚本来走通"第一次代码修改"的全流程。项目结构很简单：
claude-playground/ ├── expenses.py └── data/ └── expenses.csvexpenses.py的内容是一个简单的记账小工具，目前只能记录支出到 CSV：
import csv from datetime import datetime FILE = "data/expenses.csv" def add_expense(amount, category, note=""): with open(FILE, "a", newline="", encoding="utf-8") as f: writer = csv.writer(f) writer.writerow([datetime.now().isoformat(), amount, category, note]) print(f"已记录支出: {amount} 元, 分类: {category}") if __name__ == "__main__": add_expense(25.5, "餐饮", "午餐")data/expenses.csv已经有几条模拟记录。这个小项目麻雀虽小五脏俱全，有文件读写、有数据格式，足够演示 Claude Code 的完整工作流。
5.2 从自然语言需求到成功修改的完整过程
在项目根目录启动 Claude Code：
cd ~/claude-playground claude我输入的需求是：
我想给这个记账脚本增加一个功能：把 expenses.csv 中的数据按月份汇总，输出每个月的总支出和分类明细，保存到 reports/monthly_report.txt。请先分析现有代码，然后告诉我你的修改计划。注意我最后加了一句"先告诉我计划"。这是我强烈建议新手养成的习惯，Claude Code 在你确认之前，可以先只出计划不动手，这样避免它理解偏差导致白改。
它很快给出了分析结果：现有expenses.csv没有表头，第一列是 ISO 格式时间戳，第二列金额，第三列分类，第四列备注。然后提出修改计划，大致是：新增一个generate_monthly_report()函数；用csv.reader读取数据；解析时间戳提取月份；用defaultdict按月汇总；写出文本报告；创建reports目录。
我确认计划可行，说"开始吧"。然后它开始干活，核心动作包括：修改expenses.py，生成reports/monthly_report.txt，甚至运行了一次脚本来验证输出。整个过程终端里会实时显示每一步操作，像这样：
✳️ Reading expenses.py ✳️ Editing expenses.py + def generate_monthly_report(): ✳️ Creating reports/ directory ✳️ Running: python expenses.py ✳️ Checking reports/monthly_report.txt改完之后它还会总结一遍改了哪些文件、新增了什么函数、怎么调用。这时候我要求看一下改动内容，它展示了 diff。确认没问题之后输入/exit退出会话。
这个例子虽然简单，但完整展示了 Claude Code 的典型工作方式：理解需求、制定计划、修改代码、执行验证、汇报结果。你在生产项目里用到的每一步，都和这里是一样的。
5.3 提升控制力的四个小习惯
第一次上手的人最容易把 Claude Code 当成"自动完成机"，但其实它更像一个需要你管理的合作伙伴。我总结四个实用习惯，照着做能明显提升成功率和安全性。
第一个习惯：先要计划再执行。哪怕需求很明确，第一次下达指令时都带上"先分析，再给计划，等我确认后执行"。这相当于人工设置 check point，你可以及时纠正方向。第二个习惯：限定范围。如果只改一个模块，明确告诉它"只修改 xxx 文件，不要动其他文件"，能有效防止它顺手帮你重构了别的地方。第三个习惯：存入 Git 再动手。开始修改之前先git add . && git commit -m "before claude changes"，这样无论它改得多离谱，都能一键回滚。第四个习惯：及时打断。看到它跑偏就立刻按 Esc 或 Ctrl+C，直接说明"方向不对，应该优先处理 xxx"，重新拉回正轨。这听上去像在管人，但实际体验下来，控制力越强，产出质量越高。
6. 接入本地模型与自定义 API
6.1 为什么很多人想用本地模型
Claude Code 默认调用 Anthropic 的官方 API，但很多开发者想用本地模型，比如 LM Studio 加载的模型、Ollama 里的 Qwen3、DeepSeek-Coder 等。原因无非三个：数据不出本机，敏感代码放在公司内网之外总是不踏实；按量计费的成本对大项目来说不低；还有一些网络环境下连不上官方服务。
Claude Code 本身就支持通过环境变量指定自定义 API 地址，这也是它设计得比较开放的地方。你可以把请求转发到任意一个兼容 Anthropic API 格式的服务上，包括本地模型服务和第三方兼容网关。
6.2 环境变量配置与本地模型服务
配置的核心是三个环境变量。以 Ollama 为例，在 macOS/Linux 下：
export ANTHROPIC_BASE_URL="http://localhost:11434" export ANTHROPIC_AUTH_TOKEN="ollama" export ANTHROPIC_MODEL="qwen3"Windows PowerShell 下对应：
$env:ANTHROPIC_BASE_URL="http://localhost:11434" $env:ANTHROPIC_AUTH_TOKEN="ollama" $env:ANTHROPIC_MODEL="qwen3"设置好之后重新启动claude，AI 后端就切到了本地模型。LM Studio 的做法类似，它会在本地开一个 API 服务器，地址通常是http://localhost:1234，把ANTHROPIC_BASE_URL指过去就行。
这里有个关键提示：不是所有本地模型都能流畅使用 Claude Code。原因在于 Claude Code 的"智能体能力"依赖模型对工具调用（function calling）的严格遵守。模型需要能理解"什么时候该读文件、什么时候该执行命令、什么时候该修改代码"这些结构化指令。实测下来，像 Qwen3、DeepSeek-Coder、Qwen2.5-Coder 这些指令跟随能力强的模型表现不错；而一些只有对话能力的小模型，接进去后经常答非所问，连计划都会生成错。所以接入本地模型之前，先确认你选用的模型支持 tool use 并且尺寸足够。一般来说 7B 以上的代码专用模型才堪用，3B 以下基本只能陪聊。
6.3 可直连的第三方 API 替代方案
如果你在国内、没有服务端订阅，但又不想折腾本地模型，也可以使用兼容 Anthropic API 的第三方服务。很多模型服务商提供了 Anthropic 兼容接口，配置方式同样是三个环境变量，只是把地址改成对应服务的 API 地址，密钥改成服务商提供的 key：
export ANTHROPIC_BASE_URL="https://api.example.com" export ANTHROPIC_AUTH_TOKEN="你的服务商密钥" export ANTHROPIC_MODEL="deepseek-chat"需要注意两点。第一，优先选明确声明"支持 Anthropic API 格式"的服务，否则直接设置地址可能导致请求格式不兼容。第二，再次提醒ANTHROPIC_API_KEY和ANTHROPIC_AUTH_TOKEN的区别，第三方服务几乎一律使用AUTH_TOKEN，如果你两个都设置了，系统会优先读API_KEY，反而导致认证失败。我在帮人排查时见过至少十次这类配置冲突，统一处理办法是只留ANTHROPIC_AUTH_TOKEN。
我自己实测下来，本地模型方案的核心价值是隐私和成本，但体验上距离官方模型还有差距，尤其在大型仓库的上下文理解能力上。如果你没有特殊需求，直接用官方订阅或官方 API 是最省心的选择。
7. 常见问题与排查技巧实录
7.1 安装与启动时报错速查表
我把过去半年被问得最多的报错整理成一个表，每个都附上原因和解决方案，建议收藏备用。
| 报错信息 | 常见原因 | 解决方法 |
|---|---|---|
EACCES: permission denied | npm 全局目录无写入权限 | 用 nvm 重装 Node.js，或sudo npm install -g（不推荐） |
无法加载 claude.ps1，因为在此系统上禁止运行脚本 | Windows PowerShell 执行策略限制 | Set-ExecutionPolicy -Scope CurrentUser RemoteSigned |
claude: command not found | npm 全局 bin 目录不在 PATH | 执行npm prefix -g，把输出的目录加入 PATH |
| 登录浏览器打不开 / 授权超时 | 网络环境无法访问授权服务 | 确认浏览器能打开授权页面，再重试，不要盲目反复登录 |
Your organization has disabled Claude subscription access | 企业订阅管理员关闭了访问 | 联系管理员开通，或改用个人订阅 / API Key |
Project not authorized | 组织策略限制了项目访问 | 同上 |
401 authentication failed | API 密钥配置错误 | 检查ANTHROPIC_API_KEY与ANTHROPIC_AUTH_TOKEN是否混用 |
model not found | 自定义 API 时指定了不存在的模型名 | 确认服务商可用模型列表，如deepseek-chat、qwen3等 |
| 中文输出乱码 | 终端编码不是 UTF-8 | Windows 使用 Windows Terminal，macOS/Linux 确认 locale |
7.2 使用过程中的定位与回滚技巧
用 Claude Code 改代码，最怕的就是"它改完，我不知道改了什么"。我的习惯是三步定位。
第一步，在会话里用/status查看当前任务状态，它会列出已读文件、已改文件、执行过的命令。第二步，退出会话之后用git diff查看所有改动，重点关注它自己新增的代码路径和注释位置。第三步，如果不满意，直接git checkout .回滚所有改动，重新开一个会话重新描述需求。
还有一个很实用的命令：当对话历史太长、上下文快满的时候，输入/compact，Claude Code 会把之前的关键内容压缩成摘要，释放上下文空间继续干活。如果你发现它越改越糊涂，甚至开始遗忘前面的需求，多半是上下文窗口要满了，及时压缩比重启会话更高效。
另外，Claude Code 执行高风险操作之前通常会请求确认，比如删除文件、运行任意 shell 命令。我强烈建议新手不要开"自动确认模式"（Auto-accept），每一条命令都过一下眼睛再放行。等你自己熟悉了它的行为模式，再按需提高授权级别。
7.3 关于可能性边界：它做不了什么
越早认清工具的边界，使用效率越高。Claude Code 不是万能的，至少有三个地方它明显吃力。
第一，极端复杂的跨仓库重构。如果一次改动要跨越五六个服务、牵扯几十个文件，它的上下文窗口和规划能力会捉襟见肘，这时候最好拆成阶段任务，一次做一步。第二，依赖心算的精确逻辑。像并发时序、分布式一致性这类需要严密推理的问题，它给出的方案看起来头头是道，但跑起来经常暴露边界条件问题，必须人工审。第三，黑盒二进制修改。比如"用已知的代码静态修改游戏的 exe"这类需求，它只能给你通用的 PE 文件结构知识，但实际修改还是要靠专业的反汇编工具，而且这种行为还可能违规，我明确不建议做。
说到底，Claude Code 更像是"能干的实习生"，它速度快、执行力强，但决策质量和边界判断仍然需要你把握。它最大的价值是把那些重复、机械、费时间的编码劳动从你手里接过去，让你有精力专注于架构设计和关键决策。
最后说两句掏心窝的话
这篇教程写到这里，核心流程已经全部讲完了。最后分享一点个人体会：刚上手时我最大的误区是把它当成"更聪明的对话机器人"，每次需求说得过于笼统，比如"帮我优化一下这个项目"，然后看它在那里东翻西找半天，改出一堆不痛不痒的东西。后来我改成了"像带实习生一样给它上下文"——先说项目背景，再说目标文件，最后说验收标准，我发现它的准确率翻了一倍都不止，特别是在改老代码的时候。
还有一个小技巧想送给你：每次大改前，让它先把方案说清楚，你只管看、不动手，觉得计划没问题再放它开工。这个动作能帮你建立对 AI 编程助手的基本信任感，而不是每次改完都提心吊胆地查 diff。我已经用 Claude Code 处理了上百次项目级修改，这个习惯帮我省掉了至少几十次不必要的回滚。
如果你在安装环节碰到我没写到的报错，不用急，先大概率是版本问题——升级 Node.js、升级 npm、升级 Claude Code 本身，三步走完能解决大半。剩下的，就交给实际跑一次来验证吧。
