Claude Code 上手：装好→认证→跑通第一个项目的完整第一次

绝大多数 Claude Code 教程截图很好看，但新手最容易卡的那两步——API 认证和第一次真正跑通一个项目——要么一笔带过，要么直接跳过。结果很多人装完工具就停在那里，不知道下一步该做什么。

这篇就是为了解决这个问题：从零开始，每一步你应该看到什么、出错了怎么查，全部说清楚。

---

Claude Code 是什么，和 Cursor / Codex 有什么不同

在动手之前，先用一分钟搞清楚你在装的是什么，省得装完不知道怎么用。

Claude Code 是 Anthropic 官方出的命令行 AI 编程工具。你在终端里启动它，它能读你项目的文件、帮你改代码、运行命令、解读报错、提交 git。它的特点是：

• 跑在终端里，不是 IDE 插件。你用什么编辑器都行，Claude Code 不管这个，它直接操作文件。
• 深度理解整个代码仓库，不只是看你当前打开的文件。问"这个 bug 在哪"，它会自己翻文件找答案。
• 可以直接执行命令。它不只告诉你该跑什么，它能直接帮你跑（你确认后）。

跟 Cursor 的关系：Cursor 是 VS Code 套壳加上 AI 能力，更适合喜欢图形界面的人；Claude Code 是纯命令行，更适合习惯终端、或者想在服务器 / CI 环境里用 AI 的人。两个工具定位不同，不是竞争关系。关于这几类工具的选型对比，见上一节：工具全景。

---

第一步：装好 Node.js

Claude Code 本身是个 npm 包，所以你先得有 Node.js。

检查是否已有：

node --version
npm --version

如果输出类似 v20.x.x 和 10.x.x，跳过安装。

Node 版本要求：Claude Code 需要 Node.js 18 或更高版本。如果你的 Node 版本比较老（比如 v16），需要升级——用旧版本装 Claude Code 会报奇怪的错，而且安装能成功但运行会崩。

升级方式：直接去 Node.js 官网 下载 LTS 版本安装包，覆盖安装即可。Windows 用户注意安装时勾上"Automatically install the necessary tools"。

---

第二步：全局安装 Claude Code

Node 装好后，一条命令：

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

-g 是全局安装，装完后你在任何路径都能用 claude 命令。安装过程会下载几十 MB，看网络情况等 1-3 分钟。

验证安装成功：

claude --version

看到版本号就对了，比如 1.x.x。

如果提示 claude 命令找不到：常见于 Windows，npm 全局包目录没加到 PATH。解决方法：

npm config get prefix

把输出的路径（比如 C:\Users\你的用户名\AppData\Roaming\npm）加到系统的 PATH 环境变量里。加完重开终端再试。

---

第三步：API 认证——最容易卡新手的一关

这是大多数教程写得最含糊的地方，我们细说。

Claude Code 需要通过 Anthropic API 来调用模型。你有两种方式认证：

方式一：交互式登录（推荐新手）

直接在任意目录运行：

claude

第一次启动，它会引导你登录。按提示操作：

1. 选择"Sign in with Anthropic Console"。
2. 浏览器会自动打开 Anthropic Console 登录页，用你的账号登录。
3. 授权后，终端里会出现欢迎信息，进入 Claude Code 的交互界面（一个 > 提示符）。

方式二：直接设置 API Key（更灵活）

如果你有 API Key，可以设置环境变量：

# Linux / Mac
export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxxxxxx"

# Windows PowerShell
$env:ANTHROPIC_API_KEY = "sk-ant-xxxxxxxxxxxxxxxx"

然后运行 claude，它会自动使用这个 Key。

去哪里拿 API Key：登录 console.anthropic.com，进入"API Keys"页面创建。新账户需要充值才能调用，具体额度以官方文档为准（截稿 2026-06）。

你应该看到什么

认证成功后，终端出现类似：

✓ Logged in as your@email.com
Claude Code v1.x.x - AI pair programmer in your terminal
Type your task or question, or /help for commands
> 

看到这个 > 提示符，你正式进入 Claude Code 了。

---

第四步：进入你的第一个项目

Claude Code 最有价值的地方在于它能理解整个代码仓库的上下文。所以不要在空文件夹里用它——先 cd 进一个真实的项目目录。

如果你手边没有现成项目，用这个：

# 建一个最小的练习项目
mkdir my-first-claude && cd my-first-claude
git init
echo '{"name": "my-first-claude", "version": "1.0.0"}' > package.json
echo "# My First Claude Project" > README.md
git add .
git commit -m "init"

然后启动 Claude Code：

claude

Claude Code 启动时会自动扫描当前目录，读取 package.json、README.md、git 历史等信息，建立对这个项目的认知。

---

第五步：第一条真实对话——让它帮你写代码

在 > 提示符后，用自然语言说你要做什么：

> 帮我写一个 utils.js，里面有一个 add 函数，把两个数加起来，还有对应的测试

你应该看到什么：Claude Code 会先告诉你它计划怎么做，列出要创建的文件；然后征求你的确认，或者直接开始（取决于你的权限设置）。它会：

1. 创建 utils.js，里面有 add 函数。
2. 创建 utils.test.js，用 Node.js 内置的 assert 或者问你用哪个测试框架。
3. 自动安装需要的依赖（如果有）。

等它完成后，你的目录里会多出这几个文件。不要光看终端输出，去文件夹里看看它真的创建了什么——这个习惯很重要，帮你建立对 Claude Code 实际行为的真实感知。

---

第六步：跑测试，看到绿了

Claude Code 可以直接帮你跑命令。在对话里：

> 跑一下测试

它会根据项目配置（package.json 里的 scripts、是否有 Jest / Mocha 等）自动选合适的命令，然后展示给你看，比如：

I'll run the tests using Node.js built-in test runner:
$ node utils.test.js

按回车确认，它执行命令，把输出展示给你。如果测试通过，你会看到类似：

✓ add(1, 2) should return 3
✓ add(-1, 1) should return 0
All tests passed

如果有失败，直接告诉它"修一下这个报错"，它会读报错内容然后改代码，再让你重新跑。

---

第七步：改代码——真正的核心工作流

现在改一个功能，感受 Claude Code 处理真实需求的方式：

> 给 add 函数加参数校验，如果传入的不是数字就抛出一个有意义的错误，测试也要更新

关键点：它不只改 utils.js，还会同时更新测试。这就是"理解上下文"的实际体现——它知道测试和实现是配套的，改一个要带着另一个改。

改完后你可以这样查看 diff：

> 显示一下刚才改了什么

或者直接在终端用 git：

git diff

---

第八步：提 commit

确认改动没问题后：

> 帮我提一个 commit，信息写清楚刚才做了什么

Claude Code 会生成一条有意义的 commit 信息，比如：

feat: add input validation to add() with descriptive error on non-number inputs

展示给你确认，按回车执行 git commit。你可以让它改信息："commit 信息改成中文"，它会重新生成。

口诀：Claude Code 提 commit 的价值不在于省了敲几个字，而是它生成的信息质量比大多数人随手写的"fix bug"要好很多——它真的读了 diff 才写的。

---

常用命令速查

掌握这几条，覆盖 80% 的日常用法：

命令	作用
claude	在当前目录启动交互模式
claude "你的任务描述"	非交互模式，一次性执行一个任务
/help	显示帮助（在交互模式里输入）
/clear	清除当前会话上下文，重新开始
/status	查看当前认证状态和配置
Ctrl+C	中断 Claude Code 正在执行的操作
Ctrl+D	退出 Claude Code

---

故障排查表

症状	原因	解法
claude: command not found	npm 全局目录不在 PATH	npm config get prefix 取路径，加进 PATH，重开终端
认证时浏览器不弹出	浏览器被阻止或无头环境	手动复制终端里的 URL 到浏览器打开
Authentication failed / 401 错误	API Key 无效或环境变量没设对	检查 Key 是否完整（以 sk-ant- 开头）；echo $ANTHROPIC_API_KEY 确认值存在
Error: Node.js version xxx is not supported	Node 版本过低（低于 18）	升级到 Node.js LTS，官网下载覆盖安装
Claude Code 启动后一直转圈不响应	网络连接问题	确认能访问 api.anthropic.com；国内网络可能需要代理
文件改了但没看到预期效果	改的文件不对，或有缓存	/clear 重新开始对话；用 git diff 确认真实改动
提 commit 失败，提示没有 staged 内容	Claude Code 修改了文件但没 git add	在对话里说"帮我 add 所有改动后再 commit"

---

新手最容易踩的 3 个坑

1. 在错误的目录启动

Claude Code 的能力强烈依赖当前目录的上下文。如果你在家目录或者空文件夹里启动，它能做的事情很有限。养成习惯：先 cd 进项目目录，再启动 claude。

2. 把它当搜索引擎用

"Claude Code 是什么框架"这类问题问浏览器更快。Claude Code 的价值在于对你当前这个项目的理解和操作能力。问它"这个函数为什么报错"、"帮我加个功能"、"这段代码怎么重构"才是正确打开方式。

3. 不看它的操作计划就盲目确认

Claude Code 在执行文件修改或命令前会给你看计划。养成读一眼再确认的习惯，特别是它要删文件或者跑 rm、DROP TABLE 这类不可逆操作时。它很聪明，但不是每次都猜对你的意图。

---

下一步去哪

这一节覆盖了第一次跑通的全流程。真正的生产力提升在于学会给 Claude Code 喂好上下文——如何写任务描述、怎么拆需求、如何用 Skills 和 MCP 扩展它的能力，这些在后续节里会展开。

相关延伸：

• 想横向对比 Claude Code 和 Codex、Cursor 的实际差异，去看 2.3 和 2.4。
• 弄懂"上下文"为什么是 AI 编程工具最核心的概念，看 3.1 上下文是一切。
• 回到 AI 编程教程全景 确认自己在哪个位置。

---

常见问题

Q：Claude Code 要花钱吗？

使用 Claude Code 工具本身免费，但调用背后的模型会消耗 API 额度。具体计费方式和免费额度以 Anthropic 官方说明 为准（截稿 2026-06）。

Q：Claude Code 和 Claude 网页版有什么不同？

网页版每次对话都是独立的；Claude Code 持续运行在你的项目里，能直接读写文件、执行命令，是真正的"在你机器上干活"而不是"给你建议"。

Q：不会英文可以用吗？

完全可以。你用中文输入任务，它理解中文；它默认回复英文，但你可以直接说"用中文回复我"，它会切换。

Q：我可以让它帮我改别人的开源代码吗？

可以。git clone 下来，cd 进去，启动 Claude Code，和操作自己的项目一样。

Q：Claude Code 会不会把我的代码上传到外部？

你的代码内容会发送到 Anthropic 的服务器用于生成回复，这是它能"理解"你代码的原理。如果代码涉及敏感信息（密钥、私有算法），在问它之前需要自己权衡。具体隐私政策见官方文档。

---

👉 看看我们的 AI 编程实战体系课，或逛 AI 编程教程大全 把基本功打扎实。