最近后台收到最多的问题就是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 打开 TerminalWindows 打开 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\npmmacOS 下是/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之类的提示也是组织策略限制了项目访问处理方式相同。第二个是登录超时。浏览器开了授权链接但终端迟迟没反应。这通常是网络环境问题授权服务器握手不稳定。先确认浏览器能正常打开那个授权页面能打开就多等几秒实在不行 CtrlC 终止进程重新执行claude再试一次。注意我在这里说的只是网络连通性排查思路就一条浏览器能打开页面终端才有戏。第三个是需要切换成 API Key。如果你没有 Claude 订阅只想用 API 模式可以用环境变量指定密钥# macOS/Linux export ANTHROPIC_API_KEYsk-ant-xxxx # Windows PowerShell $env:ANTHROPIC_API_KEYsk-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的内容是一个简单的记账小工具目前只能记录支出到 CSVimport csv from datetime import datetime FILE data/expenses.csv def add_expense(amount, category, note): with open(FILE, a, newline, encodingutf-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 Codecd ~/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 或 CtrlC直接说明方向不对应该优先处理 xxx重新拉回正轨。这听上去像在管人但实际体验下来控制力越强产出质量越高。6. 接入本地模型与自定义 API6.1 为什么很多人想用本地模型Claude Code 默认调用 Anthropic 的官方 API但很多开发者想用本地模型比如 LM Studio 加载的模型、Ollama 里的 Qwen3、DeepSeek-Coder 等。原因无非三个数据不出本机敏感代码放在公司内网之外总是不踏实按量计费的成本对大项目来说不低还有一些网络环境下连不上官方服务。Claude Code 本身就支持通过环境变量指定自定义 API 地址这也是它设计得比较开放的地方。你可以把请求转发到任意一个兼容 Anthropic API 格式的服务上包括本地模型服务和第三方兼容网关。6.2 环境变量配置与本地模型服务配置的核心是三个环境变量。以 Ollama 为例在 macOS/Linux 下export ANTHROPIC_BASE_URLhttp://localhost:11434 export ANTHROPIC_AUTH_TOKENollama export ANTHROPIC_MODELqwen3Windows PowerShell 下对应$env:ANTHROPIC_BASE_URLhttp://localhost:11434 $env:ANTHROPIC_AUTH_TOKENollama $env:ANTHROPIC_MODELqwen3设置好之后重新启动claudeAI 后端就切到了本地模型。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 地址密钥改成服务商提供的 keyexport ANTHROPIC_BASE_URLhttps://api.example.com export ANTHROPIC_AUTH_TOKEN你的服务商密钥 export ANTHROPIC_MODELdeepseek-chat需要注意两点。第一优先选明确声明支持 Anthropic API 格式的服务否则直接设置地址可能导致请求格式不兼容。第二再次提醒ANTHROPIC_API_KEY和ANTHROPIC_AUTH_TOKEN的区别第三方服务几乎一律使用AUTH_TOKEN如果你两个都设置了系统会优先读API_KEY反而导致认证失败。我在帮人排查时见过至少十次这类配置冲突统一处理办法是只留ANTHROPIC_AUTH_TOKEN。我自己实测下来本地模型方案的核心价值是隐私和成本但体验上距离官方模型还有差距尤其在大型仓库的上下文理解能力上。如果你没有特殊需求直接用官方订阅或官方 API 是最省心的选择。7. 常见问题与排查技巧实录7.1 安装与启动时报错速查表我把过去半年被问得最多的报错整理成一个表每个都附上原因和解决方案建议收藏备用。报错信息常见原因解决方法EACCES: permission deniednpm 全局目录无写入权限用 nvm 重装 Node.js或sudo npm install -g不推荐无法加载 claude.ps1因为在此系统上禁止运行脚本Windows PowerShell 执行策略限制Set-ExecutionPolicy -Scope CurrentUser RemoteSignedclaude: command not foundnpm 全局 bin 目录不在 PATH执行npm prefix -g把输出的目录加入 PATH登录浏览器打不开 / 授权超时网络环境无法访问授权服务确认浏览器能打开授权页面再重试不要盲目反复登录Your organization has disabled Claude subscription access企业订阅管理员关闭了访问联系管理员开通或改用个人订阅 / API KeyProject not authorized组织策略限制了项目访问同上401 authentication failedAPI 密钥配置错误检查ANTHROPIC_API_KEY与ANTHROPIC_AUTH_TOKEN是否混用model not found自定义 API 时指定了不存在的模型名确认服务商可用模型列表如deepseek-chat、qwen3等中文输出乱码终端编码不是 UTF-8Windows 使用 Windows TerminalmacOS/Linux 确认 locale7.2 使用过程中的定位与回滚技巧用 Claude Code 改代码最怕的就是它改完我不知道改了什么。我的习惯是三步定位。第一步在会话里用/status查看当前任务状态它会列出已读文件、已改文件、执行过的命令。第二步退出会话之后用git diff查看所有改动重点关注它自己新增的代码路径和注释位置。第三步如果不满意直接git checkout .回滚所有改动重新开一个会话重新描述需求。还有一个很实用的命令当对话历史太长、上下文快满的时候输入/compactClaude Code 会把之前的关键内容压缩成摘要释放上下文空间继续干活。如果你发现它越改越糊涂甚至开始遗忘前面的需求多半是上下文窗口要满了及时压缩比重启会话更高效。另外Claude Code 执行高风险操作之前通常会请求确认比如删除文件、运行任意 shell 命令。我强烈建议新手不要开自动确认模式Auto-accept每一条命令都过一下眼睛再放行。等你自己熟悉了它的行为模式再按需提高授权级别。7.3 关于可能性边界它做不了什么越早认清工具的边界使用效率越高。Claude Code 不是万能的至少有三个地方它明显吃力。第一极端复杂的跨仓库重构。如果一次改动要跨越五六个服务、牵扯几十个文件它的上下文窗口和规划能力会捉襟见肘这时候最好拆成阶段任务一次做一步。第二依赖心算的精确逻辑。像并发时序、分布式一致性这类需要严密推理的问题它给出的方案看起来头头是道但跑起来经常暴露边界条件问题必须人工审。第三黑盒二进制修改。比如用已知的代码静态修改游戏的 exe这类需求它只能给你通用的 PE 文件结构知识但实际修改还是要靠专业的反汇编工具而且这种行为还可能违规我明确不建议做。说到底Claude Code 更像是能干的实习生它速度快、执行力强但决策质量和边界判断仍然需要你把握。它最大的价值是把那些重复、机械、费时间的编码劳动从你手里接过去让你有精力专注于架构设计和关键决策。最后说两句掏心窝的话这篇教程写到这里核心流程已经全部讲完了。最后分享一点个人体会刚上手时我最大的误区是把它当成更聪明的对话机器人每次需求说得过于笼统比如帮我优化一下这个项目然后看它在那里东翻西找半天改出一堆不痛不痒的东西。后来我改成了像带实习生一样给它上下文——先说项目背景再说目标文件最后说验收标准我发现它的准确率翻了一倍都不止特别是在改老代码的时候。还有一个小技巧想送给你每次大改前让它先把方案说清楚你只管看、不动手觉得计划没问题再放它开工。这个动作能帮你建立对 AI 编程助手的基本信任感而不是每次改完都提心吊胆地查 diff。我已经用 Claude Code 处理了上百次项目级修改这个习惯帮我省掉了至少几十次不必要的回滚。如果你在安装环节碰到我没写到的报错不用急先大概率是版本问题——升级 Node.js、升级 npm、升级 Claude Code 本身三步走完能解决大半。剩下的就交给实际跑一次来验证吧。
Claude Code入门教程：从安装配置到第一次代码修改的完整指南
最近后台收到最多的问题就是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 打开 TerminalWindows 打开 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\npmmacOS 下是/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之类的提示也是组织策略限制了项目访问处理方式相同。第二个是登录超时。浏览器开了授权链接但终端迟迟没反应。这通常是网络环境问题授权服务器握手不稳定。先确认浏览器能正常打开那个授权页面能打开就多等几秒实在不行 CtrlC 终止进程重新执行claude再试一次。注意我在这里说的只是网络连通性排查思路就一条浏览器能打开页面终端才有戏。第三个是需要切换成 API Key。如果你没有 Claude 订阅只想用 API 模式可以用环境变量指定密钥# macOS/Linux export ANTHROPIC_API_KEYsk-ant-xxxx # Windows PowerShell $env:ANTHROPIC_API_KEYsk-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的内容是一个简单的记账小工具目前只能记录支出到 CSVimport csv from datetime import datetime FILE data/expenses.csv def add_expense(amount, category, note): with open(FILE, a, newline, encodingutf-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 Codecd ~/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 或 CtrlC直接说明方向不对应该优先处理 xxx重新拉回正轨。这听上去像在管人但实际体验下来控制力越强产出质量越高。6. 接入本地模型与自定义 API6.1 为什么很多人想用本地模型Claude Code 默认调用 Anthropic 的官方 API但很多开发者想用本地模型比如 LM Studio 加载的模型、Ollama 里的 Qwen3、DeepSeek-Coder 等。原因无非三个数据不出本机敏感代码放在公司内网之外总是不踏实按量计费的成本对大项目来说不低还有一些网络环境下连不上官方服务。Claude Code 本身就支持通过环境变量指定自定义 API 地址这也是它设计得比较开放的地方。你可以把请求转发到任意一个兼容 Anthropic API 格式的服务上包括本地模型服务和第三方兼容网关。6.2 环境变量配置与本地模型服务配置的核心是三个环境变量。以 Ollama 为例在 macOS/Linux 下export ANTHROPIC_BASE_URLhttp://localhost:11434 export ANTHROPIC_AUTH_TOKENollama export ANTHROPIC_MODELqwen3Windows PowerShell 下对应$env:ANTHROPIC_BASE_URLhttp://localhost:11434 $env:ANTHROPIC_AUTH_TOKENollama $env:ANTHROPIC_MODELqwen3设置好之后重新启动claudeAI 后端就切到了本地模型。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 地址密钥改成服务商提供的 keyexport ANTHROPIC_BASE_URLhttps://api.example.com export ANTHROPIC_AUTH_TOKEN你的服务商密钥 export ANTHROPIC_MODELdeepseek-chat需要注意两点。第一优先选明确声明支持 Anthropic API 格式的服务否则直接设置地址可能导致请求格式不兼容。第二再次提醒ANTHROPIC_API_KEY和ANTHROPIC_AUTH_TOKEN的区别第三方服务几乎一律使用AUTH_TOKEN如果你两个都设置了系统会优先读API_KEY反而导致认证失败。我在帮人排查时见过至少十次这类配置冲突统一处理办法是只留ANTHROPIC_AUTH_TOKEN。我自己实测下来本地模型方案的核心价值是隐私和成本但体验上距离官方模型还有差距尤其在大型仓库的上下文理解能力上。如果你没有特殊需求直接用官方订阅或官方 API 是最省心的选择。7. 常见问题与排查技巧实录7.1 安装与启动时报错速查表我把过去半年被问得最多的报错整理成一个表每个都附上原因和解决方案建议收藏备用。报错信息常见原因解决方法EACCES: permission deniednpm 全局目录无写入权限用 nvm 重装 Node.js或sudo npm install -g不推荐无法加载 claude.ps1因为在此系统上禁止运行脚本Windows PowerShell 执行策略限制Set-ExecutionPolicy -Scope CurrentUser RemoteSignedclaude: command not foundnpm 全局 bin 目录不在 PATH执行npm prefix -g把输出的目录加入 PATH登录浏览器打不开 / 授权超时网络环境无法访问授权服务确认浏览器能打开授权页面再重试不要盲目反复登录Your organization has disabled Claude subscription access企业订阅管理员关闭了访问联系管理员开通或改用个人订阅 / API KeyProject not authorized组织策略限制了项目访问同上401 authentication failedAPI 密钥配置错误检查ANTHROPIC_API_KEY与ANTHROPIC_AUTH_TOKEN是否混用model not found自定义 API 时指定了不存在的模型名确认服务商可用模型列表如deepseek-chat、qwen3等中文输出乱码终端编码不是 UTF-8Windows 使用 Windows TerminalmacOS/Linux 确认 locale7.2 使用过程中的定位与回滚技巧用 Claude Code 改代码最怕的就是它改完我不知道改了什么。我的习惯是三步定位。第一步在会话里用/status查看当前任务状态它会列出已读文件、已改文件、执行过的命令。第二步退出会话之后用git diff查看所有改动重点关注它自己新增的代码路径和注释位置。第三步如果不满意直接git checkout .回滚所有改动重新开一个会话重新描述需求。还有一个很实用的命令当对话历史太长、上下文快满的时候输入/compactClaude Code 会把之前的关键内容压缩成摘要释放上下文空间继续干活。如果你发现它越改越糊涂甚至开始遗忘前面的需求多半是上下文窗口要满了及时压缩比重启会话更高效。另外Claude Code 执行高风险操作之前通常会请求确认比如删除文件、运行任意 shell 命令。我强烈建议新手不要开自动确认模式Auto-accept每一条命令都过一下眼睛再放行。等你自己熟悉了它的行为模式再按需提高授权级别。7.3 关于可能性边界它做不了什么越早认清工具的边界使用效率越高。Claude Code 不是万能的至少有三个地方它明显吃力。第一极端复杂的跨仓库重构。如果一次改动要跨越五六个服务、牵扯几十个文件它的上下文窗口和规划能力会捉襟见肘这时候最好拆成阶段任务一次做一步。第二依赖心算的精确逻辑。像并发时序、分布式一致性这类需要严密推理的问题它给出的方案看起来头头是道但跑起来经常暴露边界条件问题必须人工审。第三黑盒二进制修改。比如用已知的代码静态修改游戏的 exe这类需求它只能给你通用的 PE 文件结构知识但实际修改还是要靠专业的反汇编工具而且这种行为还可能违规我明确不建议做。说到底Claude Code 更像是能干的实习生它速度快、执行力强但决策质量和边界判断仍然需要你把握。它最大的价值是把那些重复、机械、费时间的编码劳动从你手里接过去让你有精力专注于架构设计和关键决策。最后说两句掏心窝的话这篇教程写到这里核心流程已经全部讲完了。最后分享一点个人体会刚上手时我最大的误区是把它当成更聪明的对话机器人每次需求说得过于笼统比如帮我优化一下这个项目然后看它在那里东翻西找半天改出一堆不痛不痒的东西。后来我改成了像带实习生一样给它上下文——先说项目背景再说目标文件最后说验收标准我发现它的准确率翻了一倍都不止特别是在改老代码的时候。还有一个小技巧想送给你每次大改前让它先把方案说清楚你只管看、不动手觉得计划没问题再放它开工。这个动作能帮你建立对 AI 编程助手的基本信任感而不是每次改完都提心吊胆地查 diff。我已经用 Claude Code 处理了上百次项目级修改这个习惯帮我省掉了至少几十次不必要的回滚。如果你在安装环节碰到我没写到的报错不用急先大概率是版本问题——升级 Node.js、升级 npm、升级 Claude Code 本身三步走完能解决大半。剩下的就交给实际跑一次来验证吧。
