第一次在终端里把 Claude Code 装好，让它把项目从头到尾翻了一遍、自己动手改完代码、还顺手跑通了测试的时候，我在屏幕前坐了好一会儿。过去几年我用过不少AI编程助手，大部分时候它们的工作方式是“我说一句，它给一段建议，我自己复制粘贴过去”，而 Claude Code 是直接住进终端里，能读项目、改文件、执行命令，更像一个和你并肩坐着的结对程序员。这篇教程就是写给第一次接触 Claude Code 的人：从最基础的安装环境准备开始，到第一次真正修改真实项目代码，整条链路我都会带你走一遍，并且把装机和首跑阶段最常遇到的坑一并交代清楚。无论你刚学编程还是写了很多年，照着这篇文章做，两个小时之内就能跑通。

1. 为什么值得装：它和网页端聊天的核心差别

1.1 从“复制粘贴”到“它自己动手”

用网页版AI聊天时，你要手动做三件事：把相关文件内容复制进对话、把需求用文字描述清楚、再把AI给出的代码结果复制回编辑器。这个过程本质上还是“AI当字典，人当搬运工”。Claude Code不一样，它是在你的项目目录里启动的，天然拥有三个能力：读取工程里的所有文件、直接编辑文件内容、在项目环境里执行终端命令。

有了这三项能力，协作方式就变了。我让它改一个Python脚本里的输出格式，它会自己找到脚本、阅读上下文、修改代码，然后跑一遍看看结果。我只需要描述“要把输出改成JSON数组，缩进2个空格”，剩下的观察、定位、修改、验证，都由它完成。从使用体验上看，网页版更像是“你拍照片发给远方的师傅，师傅用语音告诉你哪根线接哪里”；Claude Code则是“师傅直接来你家，拿着你的工具干活，你只需要在旁边确认”。

这就是这一类命令行AI编程工具被称为 Agent（智能体）的原因：它有工具、有执行能力、能自主完成任务链条，而不只是生成一段静态文本。

1.2 独立开发者、团队和纯新手分别能从这里得到什么

我自己的使用场景偏独立开发和自动化脚本，Claude Code 给我最直接的帮助是处理跨文件的琐碎重构：改函数签名、同步调用方、更新测试用例，这种活以前要花半天，现在描述清楚后它十几分钟就能完成，我做的是审代码。

在团队场景里，它同样有位置。拉动请求前让它自动生成清晰的提交信息、批量处理格式问题、把重复性代码改成公共函数，这些工作不需要太多业务判断，交给它反而比人手动做更快。但前提是团队里有人对它的产出做代码评审，这一点很关键。

纯新手拿它学习编程也合适：遇到报错可以把它当“旁边坐着的老师”，直接问“这个报错为什么出现，怎么修”，它会结合当期项目的文件给出解释。它还能在改代码前反过来问你“这个函数的调用方需要一起改吗”，这种对话本身就是很好的编程思维训练。

有一点要提醒：它不是什么魔法。项目一复杂，它就特别依赖“项目上下文说明”和你的需求描述是否清楚。这也是后面为什么要讲 CLAUDE.md 的原因——那是给AI写的项目说明书。

2. 装Claude Code之前，先把Node.js和Git这两件小事搞定

2.1 为什么一定要Node.js，装到什么版本才算合格

Claude Code 本身是一个 npm 包，而 npm 是随 Node.js 一起分发到电脑里的。所以安装路径是：Node.js 提供 npm，npm 负责安装 Claude Code。如果你之前没接触过前端生态，可以把 npm 理解成“应用商店”，Claude Code 只是商店里的一个应用，而 Node.js 是运行这个应用商店的基础环境。

版本要求是 Node.js 18 或更高版本。这个门槛不算高，但很多老机器上装的是 Node 16 甚至 14，那种环境装 Claude Code 大概率会直接报引擎版本不匹配的错误。安装完成之后，打开终端执行：

node -v

如果输出的版本号是 v18.0.0 以上，就合格了。如果没输出版本号，说明 Node.js 还没装上，或者装完没有重新打开终端窗口。

2.2 Windows、macOS、Linux 三种系统的安装方法

不同系统的安装方式差异还是存在的，这里给你三套我实测过的。

Windows：去 Node.js 官网下载页面找到 LTS（长期支持版）的 .msi 安装包，双击安装，一路点 Next 就行。安装程序会自动把 Node.js 写进系统 PATH，装完记得重新开一个终端窗口，再执行node -v验证。

macOS：如果你装了 Homebrew，一条命令就能搞定：

brew install node

没装 Homebrew 的话，去官网下载 macOS 安装包（.pkg）也是一样的效果，安装完同样需要验证。

Linux（以 Ubuntu 系为例）：我强烈建议用 nvm（Node 版本管理器）来装，不要直接用 apt 装系统包，因为 apt 源里的 Node 版本往往偏老。nvm 的安装方式：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

安装完重开终端，再执行：

nvm install --lts nvm use --lts

这样装到的 Node 一定是当前最新的长期支持版，后面给 ClauCode 做版本切换也方便。我自己就是在 Linux 机器上装过一个系统源的旧版本结果版本不对，后来全部切到 nvm 才清净了。

2.3 Git 不是可选项，两行配置别忘了

Claude Code 在工作过程中大量依赖 Git：看文件改动用git diff，被授权时检查仓库状态，很多时候完成修改后它还会主动建议提交。所以 Git 是硬依赖，不是可选项。

Windows 装 Git 最简单的方式是去 Git for Windows 官网下载安装包，安装时保持默认就好，唯一建议勾选的是“把 Git 加入 PATH”。macOS 如果在终端里执行git --version没有报错，说明系统自带的命令行工具已经可用了；不行的话执行brew install git。Ubuntu 上执行：

sudo apt update && sudo apt install git -y

装完之后，有两条全局配置必须做，否则后面自动提交时会报错：

git config --global user.name "你的名字" git config --global user.email "你的邮箱"

我第一次在项目里让 Claude Code 帮我提交代码时，就卡在“Please tell me who you are”这个报错上。当时项目里确实有局部配置，但全局配置是空的，Claude Code 在终端里执行提交命令时被 Git 拦住，整个流程卡了好几分钟。后来我把这两行配置一写，从此再没遇到。

全部装完后，用下面三个命令做一个最终体检：

node -v git --version git config --global --list

三项都有输出，就可以进入正题了。

3. 三种安装方式我都试过，推荐你这样选

3.1 官方推荐：npm 全局安装

装好 Node.js 之后，在终端里执行：

npm install -g @anthropic-ai/claude-code

这是最标准的安装方式。全局安装意味着你在任何目录下都能直接执行claude命令，不用为每个项目单独装。安装完成后验证版本：

claude --version

出现版本号就算成功了。后面想更新也很简单，执行：

npm update -g @anthropic-ai/claude-code

我的主力机器一直用这种方式，它的好处是比较透明，你能明确看到当前装的版本，路径也完全可控。

3.2 安装脚本的便利与局限

如果你觉得 npm 命令还要记，官方历史上有发布过一键安装脚本：

curl -fsSL https://claude.ai/install.sh | bash

这种方式在 macOS 和 Linux 上体验很好，脚本会自动检测环境、安装依赖、写入 PATH。我刚开始尝鲜时也是先用这个脚本装上的，一块屏幕上跑完几行日志，claude命令就能用了。

但实际使用中我发现，当脚本帮你装的路径和系统其他包管理工具冲突时，排查起来反而麻烦。有一次我升级系统自带组件后，claude命令直接找不到，最后卸载重装才解决。所以如果你第一次接触这类工具，我更推荐 npm 全局安装，至少在别人远程帮你排错时可以一句“你的是什么版本、装在哪”说清楚。

3.3 VS Code 插件方式的适用人群

Claude Code 官方还提供了 VS Code 扩展。打开编辑器，在扩展市场里搜索“Claude Code”，安装后它会提供一个侧边栏面板和独立终端，让你在编辑器里启动 Claude Code 会话。

这个方式的优势是界面亲和，适合已经重度依赖 VS Code、不习惯纯终端的人。它的底层执行逻辑和命令行版一模一样，只是换了入口。我自己在写前端代码时也会偶尔切到侧边栏操作，看代码高亮和文件树确实比纯终端舒服一些。

但有一点要提醒：插件模式里跑的命令仍然是在本地终端环境里执行的，权限逻辑没有变，不要因为界面看起来像普通聊天面板就放松对权限的检查。

3.4 三种方式怎么选

我把它总结成一张表：

结论很简单：第一次装，直接走npm install -g @anthropic-ai/claude-code这条路，前面基础环境只要没问题，这一步基本不会失败。

4. 第一次实战：半小时内让它完成一次真实代码修改

4.1 启动和首次授权

找一个你想用来练习的小项目目录，进入终端：

cd ~/your-project claude

第一次启动时，Claude Code 会进入授权流程。最常用的方式是登录你的订阅账号，终端会显示一个链接，让你在浏览器里完成登录授权，授权成功后回到终端继续。如果你的账号已经关联了 API Key，也可以选择对应的 API Key 登录方式。这一步只做一次，之后在同一台机器上启动就不需要重复了。

首次启动会花一点时间，它需要扫描当前环境、读取项目结构，看起来像是一堆日志在滚动。别紧张，这个过程正常。启动完成后，你会进入一个交互式提示符，可以像聊天一样输入指令。

我给新手的建议是：第一次就老老实实用一个小项目试，不要直接进公司核心代码库。压力小，权限也好控制。

4.2 用 /init 让AI自己建项目说明

进入交互界面后，第一件事我建议你输入：

/init

这个命令会让 Claude Code 扫描整个项目目录，生成一份叫做CLAUDE.md的文件。通俗地讲，这是一份“给AI看的项目说明书”，里面记录着项目的用途、目录结构、技术栈、约定和常用命令。之后每次会话开始，Claude Code 都会读取这个文件作为上下文基础。

为什么这一步很重要？因为 AI 虽然能看懂代码，但它不认识你项目的“潜规则”：比如测试命令是npm test还是python -m pytest，代码风格是 2 空格缩进还是 4 空格。CLAUDE.md 把这些约定写清楚后，后面改代码的准确率会明显上升。

我自己的一个项目在没写 CLAUDE.md 之前，让它加个接口它总是按默认风格生成代码，和现有代码风格很不协调。执行过一次 /init 后，改了配置项，后面生成的代码自动跟着项目风格走。

4.3 一次具体的修改演示

假设有一个练习项目，里面有个 Python 脚本scripts/format.py，原本的功能是把一个名字列表打印成逗号拼接的文本，现在需求是改成输出 JSON 数组。

我直接在交互界面里输入：

把 scripts/format.py 的输出格式改成 JSON 数组，每个名字单独一行，缩进用2个空格，不要逗号拼接文本那种格式了

Claude Code 会回应一段简要的方案说明，然后自动操作文件。典型情况下它会先读取format.py，再执行编辑。改完之后我可以让它运行一下验证：

运行 python scripts/format.py 看看结果对不对

它会调用终端执行命令，然后根据输出再自我检查。整个过程中我只需要在它请求执行权限时按一下确认——这一点后面会详细讲，不要直接无脑允许。

按下确认第一下之后，你大概率会对“它真的在我的电脑上干活”这个事实产生一种很直接的体感。脚本的修改结果大致长这样（我简化过原代码）：

import json def format_names(names): return json.dumps(names, ensure_ascii=False, indent=2) if __name__ == "__main__": print(format_names(["Alice", "Bob", "Cindy"]))

注意，它不会只给你代码片段，而是直接修改了磁盘上的源文件。

4.4 审查修改，再让它帮你提交

AI 改完代码不等于工作结束。你仍然需要扮演代码评审者。在终端里执行：

git diff

会清楚看到 Claude Code 到底改了哪些行。这个习惯我从第一天就坚持到现在，AI 给出的代码一定要过自己的眼睛，尤其要注意它是不是动了不该动的文件。

确认没问题之后，你可以在交互界面里直接说：

帮我提交这次改动，提交信息用“refactor: format.py 输出改为JSON数组”

它会执行git add -A && git commit -m "..."，整个过程依然会向你请求权限。这样一次完整的“从需求到代码再到提交”的闭环就走完了。

4.5 我第一次实战翻车的地方

第一次用的时候我犯了一个典型错误：需求描述里没有限定“只改 format.py”。结果 Claude Code 分析完整个项目后，觉得另一个模块也有类似的输出格式问题，顺手一起改了。当时我没仔细看 diff，直接提交，后面测试的时候才发现牵连出一个本来不需要动的文件。

从那以后，我每次给任务都会先在脑里圈定范围：改哪个文件、影响哪些调用方、哪些不允许改。描述里明确写“只改……”是最有效的手段。还有一次，我为了图方便，在权限弹窗里直接选了“Always allow”（以后始终允许），结果它真的执行了一个我本不希望它执行的命令。我后来把权限重置成了默认的逐次确认。权限这件事，宁可多按两次确认，也不要图省事放开全局。

5. 安装和使用阶段最常遇到的五个报错与排查思路

5.1 npm 安装时的 EACCES 权限报错

在一部分 Linux 和 macOS 系统上，执行npm install -g @anthropic-ai/claude-code时会看到类似：

Error: EACCES: permission denied

原因通常是当前用户对 npm 的全局安装目录没有写权限。很多教程会让你在前面加sudo，也就是用管理员权限安装，我建议你别这么干——用 sudo 装全局包之后，后续更新和管理权限都会越来越乱，还容易让其他工具访问到这个目录时遇到权限冲突。

更稳的方案是改用 nvm 管理 Node.js，nvm 会把全局包装到你自己的用户目录下，天然绕开权限问题。如果你的 Node.js 就是 nvm 装的，这个报错基本不会出现。已经出现EACCES的话，先重置 npm 全局目录到当前用户目录：

npm config set prefix '~/.npm-global' export PATH=~/.npm-global/bin:$PATH

然后把导出行写进~/.bashrc或~/.zshrc里，重新打开终端再装一次。这是我线上排错时用过的方案，比 sudo 干净。

5.2 “Your organization has disabled Claude subscription access for Claude Code”

这条报错完整的样式通常是：

Your organization has disabled claude subscription access for claude code.

如果你用的是公司或团队统一开通的订阅账号，说明管理员在后台关闭了 Claude Code 的访问权限。这是账号策略问题，不是安装问题。处理方式也直接：联系组织管理员在后台打开对应的访问开关，或者换回你个人的订阅账号登录。我第一次遇到这个报错时还以为是工具没装好，重新装了三次，最后才确认是订阅类型的问题，白白浪费了时间。

5.3 提示服务可用性限制

有些用户安装后启动时可能遇到类似“Claude Code might not be available in your country. Check supported countries”的提示。碰到这种情况，先别急着找技术方案。这个提示说明当前账户区域和服务发布范围存在限制，属于服务商运营策略的一部分。最稳妥的做法是核对官方支持范围和你的账户区域设置是否一致，按官方渠道和规则来。不建议使用任何绕过手段去规避这类限制，既不安全也不符合使用条款。

5.4 Windows 下的路径与编码问题

Windows 上直接使用 CMD 或 PowerShell 启动claude并非不能运行，但遇到符号链接和输出编码问题时，体验会比较别扭。Claude Code 在设计和测试时更偏向 Unix 风格环境，所以我的建议是：在 Windows 上优先使用 WSL（Windows Subsystem for Linux）来安装和使用，或者至少在 Git Bash 里跑。

如果你已经装了 WSL，直接在 WSL 的终端里按前面 Linux 的步骤来：装 nvm、装 Node.js、装 Git、然后 npm 全局装 Claude Code。整个过程比在原生 Windows 环境里顺滑得多。顺带提一句，WSL 环境下文件路径访问速度和 Windows 原生有些差异，但日常跑 Claude Code 完全够用。

还有一个常见的 Windows 问题是终端编码导致的中文乱码。如果遇到 ClauCode 输出中文乱码，可以先把终端编码切到 UTF-8 再启动，很多时候不是工具的问题，而是终端区域设置的问题。

5.5 旧版本 Node.js 导致安装失败

如果安装时报错信息里出现了engine、node或npm版本相关的字样，大概率是 Node.js 版本太旧。这类报错很明确，核心解决思路就是升级 Node.js 到 18+。用 nvm 的话：

nvm install --lts nvm alias default 'node'

装完再验证node -v。我见过不少同事在旧 Node 版本上反复重试安装同一个包，换版本后一次就成功。环境版本这东西，真的是第一顺位排查项。

6. 从“能跑”到“好用”：三条我沉淀下来的使用习惯

6.1 把 CLAUDE.md 写成一份入职说明书

前面说了 /init 能自动生成 CLAUDE.md，但它生成的内容偏基础。真正让项目变好用，还需要你手动维护这份文件。我的做法是把它当成“一个新人入职第一天要看的文档”来写：

• 项目是干什么的，解决什么问题
• 目录结构，哪里放业务代码，哪里放工具脚本
• 常用命令：怎么装依赖、怎么跑测试、怎么启动
• 代码风格约定：缩进、命名规范、注释语言
• 有哪些目录或文件是“雷区”，AI 不应该去动

把这些写清楚之后，你会明显感受到 Claude Code 的产出质量上一个台阶。写得好不好，直接影响后续所有会话的效率。这是整个使用过程中性价比最高的一步。

6.2 用非交互模式做自动化小任务

Claude Code 除了可以进入交互界面聊天，还支持一次性的命令模式。比如：

claude -p "分析 server.py 里所有TODO注释并整理成列表"

-p表示 print 模式，执行完直接把结果输出到终端，适合把它接进自己的脚本流程里。还有一个我常用的：

claude -c "继续上次会话，把刚才说的 bug 修完"

-c用于延续上一次会话上下文，适合每天开工时接着前一天的工作继续。这些模式配合起来，可以把 Claude Code 变成一个可以被脚本调用的“AI终端命令”，而不只是人工对话窗口。

6.3 本地模型和第三方模型：当玩具可以，当生产要谨慎

现在社区里有一个热门玩法，是用路由工具把 Claude Code 的请求转发到本地模型（比如 LM Studio 或 Ollama 里的模型）或第三方 API 上，社区里常见的工具有 claude-code-router、cc-switch 这类。我专门花过一晚上折腾这个，把请求切到本地模型跑过。

结论是：本地模型日常问答还可以凑合，但让它真的执行修改代码这类高精度工具任务时，经常会在“工具调用”这一环卡住——明明模型理解了需求，却不知道该怎么调用编辑文件的接口。我也试过用 Ollama 里跑 Qwen3 这类模型来接，聊天没问题，动手改代码就明显力不从心。逆向用第三方 API 接入时，同样要仔细确认数据流向和合规情况。

所以我的建议是：这类玩法适合技术爱好者实验，不适合作为日常生产的主力方案。Claude Code 的核心体验建立在靠谱的工具调用能力上，这部分目前还是官方模型最稳。你可以在玩具项目里折腾，但别让它在关键代码上拖后腿。

6.4 从一个玩具项目开始，比看十篇文档管用

最后说点实际的。如果你之前完全没用过这类工具，我建议你从身边最小的脚本或静态网页项目开始，给它派一些小而明确的任务，比如“把样式从浅色改成深色”“给函数加上类型注释”。一步一步体验它的读代码、改代码、跑命令的完整链路。等理解了它的工作方式和权限逻辑，再把规模一点点加大。别第一天就拿公司核心代码试水，AI 编程工具的上手成本不在“打开”这一步，而在你学会如何描述需求、如何审查产出、如何划清边界——这些能力只能靠实际操作养出来。

我自己用下来的体会是，Claude Code 给我最大的收获不是“它替我写了多少代码”，而是“为了让 AI 理解项目，我把自己的项目逻辑梳理得更清楚了”。当你不得不把需求、边界、约束用准确的语言描述出来时，你对代码本身的理解也会更深入。工具会持续更新，但这个核心价值不会变。