Claude Code 入门教程

Claude Code 是 Anthropic 推出的命令行编程助手，让你直接在终端中通过自然语言与 Claude 对话，完成代码编写、调试、重构和审查等任务。与网页端聊天界面不同，它是安装在本地开发环境中的 CLI（命令行界面）工具，能直接读写你的项目文件、运行命令并管理 Git 操作。

💡 新手提示：Claude Code 属于 Anthropic 生态系统。如果你对 Claude 还不熟悉，建议先阅读 Claude 入门指南 了解基础概念。

下一步：请求与响应格式 入门教程、请求与响应格式 实用技巧

---

核心差异：Claude Code vs Claude.ai 网页版

特性	Claude Code (CLI)	Claude.ai 网页版
访问方式	终端命令 claude	浏览器
文件读写	✅ 直接读写项目文件	❌ 需手动复制粘贴
Git 操作	✅ 自动创建 commit、PR	❌ 不支持
执行命令	✅ 可运行测试、构建	❌ 不支持
上下文容量	项目级，可扫描整个仓库	对话级，受限于粘贴内容
适用场景	日常开发、大型项目	快速问答、代码片段解释

新手最易混淆的点：Claude Code 不是 IDE 插件。它不集成在 VS Code 或 JetBrains 中运行，而是一个独立的终端程序。你需在项目根目录启动它，然后在命令行窗口用自然语言下达指令。

---

开始之前：环境准备与版本检查

前置清单

• Node.js 18+ — Claude Code 依赖 Node.js 运行时。运行 node --version 确认版本，低于 18 的请先升级。
• npm 或 yarn — 用于安装 Claude Code npm 包。
• 有效的 Anthropic API Key — 在 console.anthropic.com 创建 API Key。注意选择正确的计费方案（按 token 付费，目前每百万输入 token 约 $3，输出约 $15）。
• Git 2.23+ — 虽非强制，但大部分文件操作依赖 Git 上下文。运行 git --version 检查。
• 项目代码 — 建议先在非生产环境的小项目或代码仓库中试用，避免误操作。

关键版本提示

Claude Code 功能迭代较快，当前（截至 2025 年中）版本为 0.x。安装前请查看 Anthropic 官方文档或 GitHub Release 页面确认最新版本号，避免参考过时的教程。

新手常见错误：直接复制网上的安装命令，却未检查当前 Node.js 版本。如果 Node.js 版本低于 12，npm 会报 ERR! code EBADENGINE，提示不支持。此时需先升级 Node.js，而不是强行安装。

---

详细操作步骤

第一步：安装 Claude Code

在终端执行：

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

⏱ 安装时间：过程通常需要 30-60 秒。如果卡在某个依赖包上，请检查网络是否能正常访问 npm 源，或尝试切换为 yarn 安装。

安装完成后验证：

claude --version

输出应显示版本号（如 0.2.5）。如果显示 command not found，请检查 npm 全局安装路径是否在 PATH 环境变量中。

第二步：配置 API Key

export ANTHROPIC_API_KEY="sk-ant-..."

⚠️ 安全提醒：不要在公共环境或分享的终端窗口中直接粘贴 API Key。建议将其写入项目的 .env 文件并加入 .gitignore，或使用密码管理工具保存。如果你使用多个 Anthropic 项目，不同 API Key 对应不同计费账户和配额，务必确认使用的是正确的 Key。

第三步：启动 Claude Code

进入你的项目根目录：

cd /path/to/your/project
claude

启动成功后，终端会出现一个 > 提示符，表示 Claude Code 已就绪，等待你输入自然语言指令。

第四步：下达第一个指令

示例对话：

> 帮我看看这个项目里有哪些 Python 代码文件？列出每个文件的行数和主要功能。

Claude Code 会扫描当前目录（以及 Git 管理的文件），然后返回结果。此时你无需手动输入特定命令格式——直接用自然语言描述需求即可。

---

完整工作示例：重构一个函数

假设你的项目中有个 Python 文件 utils.py，里面有一个函数需要优化。以下是在 Claude Code 中执行重构的完整流程：

原始场景

utils.py 中包含：

def process_data(items):
    results = []
    for i in range(len(items)):
        if items[i] > 0:
            results.append(items[i] * 2)
    return results

在 Claude Code 中的对话

> 在 utils.py 里有个 process_data 函数，我想把它改得更加 Pythonic，添加类型注解和 docstring，并且处理空列表的边界情况。

预期输出

Claude Code 会读取 utils.py，然后返回修改建议。你可以：

1. 审阅修改：Claude Code 会以 diff 格式展示即将做的更改：

   + from typing import List
   + def process_data(items: List[int]) -> List[int]:
   +     """Filter positive numbers and double them.
   +     
   +     Args:
   +         items: A list of integers.
   +     Returns:
   +         A list where each positive input is doubled.
   +     """
   +     return [item * 2 for item in items if item > 0]
   

2. 确认应用：输入 y 确认修改，或 n 拒绝。

3. 验证结果：运行测试命令确认修改没有破坏逻辑：

   > 在终端运行 pytest tests/test_utils.py，看看测试是否通过
   

边缘情况处理

注意一个边界场景：如果 items 参数不是列表而是 None，上面的重构版本会抛出 TypeError。通过 Claude Code 进一步优化：

> 在上次修改的基础上，添加对 None 值的处理，让函数在传入 None 时返回空列表而不是报错。

Claude Code 会读取当前文件状态并再次生成 diff。

---

操作检查清单

执行任何修改操作前后，建议做以下检查：

• 启动前确认环境：node --version 和 claude --version 都正常输出
• 确认 API Key 已设置：运行 echo $ANTHROPIC_API_KEY 应看到以 sk-ant- 开头的字符串
• 确认项目已纳入 Git 管理：运行 git status 确保不误操作未跟踪的文件
• 审查每次修改的 diff：Claude Code 每次修改前都会展示变更内容，仔细阅读再确认
• 运行测试确认无损坏：修改后立即运行项目的单元测试或 lint 检查

---

常见问题与排查

1. 启动时报错 "Cannot find module '...'"

原因：Node.js 版本太低，或 npm 全局安装路径未正确配置。

检查步骤：

1. node --version — 确认 ≥18
2. which claude — 确认可执行文件路径在 PATH 中
3. 如果出现模块错误，尝试重新安装：npm install -g @anthropic-ai/claude-code

2. Claude Code 无法读取项目文件

原因：可能未在正确的项目根目录启动，或项目未初始化 Git。

解决方法：

• 确认你在项目根目录（包含 package.json、pyproject.toml 等标志文件）运行 claude
• 如果项目没有 .git 目录，Claude Code 仍可工作但上下文理解会受限，建议运行 git init 初始化

3. 修改后代码变慢或出错

不要立即回滚。先通过 Claude Code 询问修改了哪些文件：

> 列出你刚才修改过的所有文件以及每个文件的变更摘要

如果确认改动有问题，让 Claude Code 撤销：

> 撤销刚才对 utils.py 的修改，恢复到修改前的状态

或手动通过 Git 操作 git checkout -- <file> 回滚。

4. API Key 限制或配额问题

如果你遇到以下错误：

• 401 Unauthorized — API Key 无效或已过期
• 429 Too Many Requests — 短时间内请求过多

处理方法：

• 重新生成 API Key 并更新环境变量
• 暂停 10-60 秒再继续操作
• 检查 Anthropic Console 中的使用量配额

5. 何时停止操作

• 当你对 Claude Code 正在修改的文件内容没有完全理解时
• 当项目中包含敏感信息（密码、Token、密钥）且尚未确认 .gitignore 配置是否正确时
• 当你的