项目简介与适用人群

什么是 Claude Code？

Claude Code 是一个智能编码工具，它直接运行在你的终端中，能够理解整个代码库，并通过自然语言命令帮助你更快地编写代码。它的核心能力包括：

• 执行日常任务：自动完成代码重构、文件操作、测试运行等重复性工作
• 解释复杂代码：快速理解不熟悉的代码片段或整个模块的逻辑
• 处理 Git 工作流：协助完成提交、分支管理、代码审查等版本控制操作
• 与 IDE 集成：在终端中使用，或通过 @claude 标签在 GitHub 上直接交互

简单来说，Claude Code 就像是你的终端里的 AI 编程助手，你只需要用自然语言描述需求，它就能帮你完成对应的编码工作。

核心特性

特性	说明
代码库理解	自动扫描并理解项目结构、依赖关系、代码逻辑
自然语言交互	用中文或英文直接描述需求，无需记忆复杂命令
任务自动化	支持批量文件操作、代码生成、测试执行等
Git 集成	内置 Git 工作流支持，可自动完成提交、合并等操作
插件扩展	支持自定义命令和插件，可扩展功能
跨平台	支持 macOS、Linux、Windows

适用人群

Claude Code 适合以下类型的开发者：

1. 全栈开发者

• 需要快速理解不熟悉的技术栈或遗留代码
• 经常进行代码重构、迁移或升级
• 希望自动化日常开发任务

2. 团队负责人 / Tech Lead

• 需要快速审查代码变更
• 希望自动化 Git 工作流（如自动生成提交信息、处理合并冲突）
• 需要为团队成员提供代码解释和文档

3. 独立开发者 / 自由职业者

• 需要提高编码效率，减少重复劳动
• 经常在多个项目之间切换，需要快速上手
• 希望减少手动操作，专注于核心逻辑

4. 学习型开发者

• 想通过自然语言交互理解代码逻辑
• 需要快速学习新框架或库的使用方式
• 希望获得代码优化建议和最佳实践

5. 运维 / DevOps 工程师

• 需要自动化脚本编写和调试
• 希望快速理解复杂的配置文件或部署脚本
• 需要处理大量重复性的文件操作

不适合的人群

• 完全不需要编码的用户：Claude Code 主要面向开发者，需要一定的编程基础
• 对终端操作不熟悉的用户：虽然交互是自然语言，但运行环境是终端
• 需要离线使用的用户：Claude Code 需要网络连接以调用 AI 服务

技术前提

使用 Claude Code 前，建议具备以下基础：

• 基本的终端/命令行操作能力
• 熟悉至少一种编程语言
• 了解 Git 基本概念（如提交、分支、合并）
• 拥有 Anthropic 账户（用于 API 认证）

支持的平台

平台	安装方式	推荐程度
macOS	脚本安装 / Homebrew	推荐
Linux	脚本安装 / Homebrew	推荐
Windows	脚本安装 / WinGet	推荐
跨平台	NPM（已弃用）	不推荐

注意：NPM 安装方式已被弃用，建议使用各平台推荐的安装方法。

数据与隐私

使用 Claude Code 时，系统会收集以下数据：

• 使用数据：代码接受/拒绝等操作记录
• 对话数据：与 AI 的交互内容
• 反馈数据：通过 /bug 命令提交的反馈

Anthropic 承诺：

• 有限的数据保留期限
• 严格限制对用户会话数据的访问
• 明确禁止将用户数据用于模型训练

详细政策请参阅 商业服务条款 和 隐私政策。

下一步

如果你符合上述适用人群，并且准备好开始使用，请进入下一章：安装与环境准备。

安装与环境准备

本章将指导你在不同操作系统上安装 Claude Code，并完成必要的环境配置。安装完成后，你将能够在终端中直接使用 claude 命令。

系统要求

在开始安装前，请确保你的系统满足以下基本要求：

• 操作系统：macOS 12+、Linux（主流发行版）、Windows 10/11
• 终端：支持现代终端特性（如 Unicode、256 色）
• 网络：能够访问 claude.ai 和 anthropic.com 相关域名
• Node.js（可选）：仅在使用 NPM 安装时需要，推荐使用 v18 或更高版本

安装 Claude Code

Claude Code 提供多种安装方式，推荐使用官方脚本或包管理器进行安装。

macOS / Linux 安装

方法一：官方安装脚本（推荐）

这是最简单快捷的方式，适用于大多数 macOS 和 Linux 系统：

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

该脚本会自动检测你的系统架构，下载对应二进制文件并添加到 PATH。

方法二：Homebrew（macOS / Linux）

如果你已安装 Homebrew，可以使用以下命令：

brew install --cask claude-code

安装完成后，Homebrew 会自动创建符号链接，使 claude 命令全局可用。

Windows 安装

方法一：官方安装脚本（推荐）

在 PowerShell（以管理员身份运行）中执行：

irm https://claude.ai/install.ps1 | iex

该脚本会自动处理路径配置，安装后即可在任意终端中使用 claude 命令。

方法二：WinGet

如果你使用 Windows 包管理器 WinGet，可以运行：

winget install Anthropic.ClaudeCode

其他安装方式

NPM 安装（已弃用）

⚠️ 注意：官方已弃用 NPM 安装方式，仅建议在特殊场景下使用。未来版本可能不再支持。

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

验证安装

安装完成后，打开一个新的终端窗口，运行以下命令验证是否安装成功：

claude --version

如果看到类似 claude-code/0.x.x 的版本号输出，说明安装成功。

首次启动与配置

首次运行 claude 命令时，需要进行身份验证：

1. 在终端中执行：

   claude

2. 系统会提示你登录 Anthropic 账户。按照终端中的指引，在浏览器中完成 OAuth 授权。

3. 授权成功后，Claude Code 会自动保存认证令牌，后续使用无需重复登录。

环境变量配置（可选）

你可以通过环境变量自定义 Claude Code 的行为：

# 设置代理（如果需要通过代理访问网络）
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080

# 设置自定义 API 端点（仅限企业用户）
export CLAUDE_API_BASE_URL=https://your-custom-endpoint.com

# 设置日志级别（debug/info/warn/error）
export CLAUDE_LOG_LEVEL=info

卸载 Claude Code

如果需要卸载，根据安装方式执行对应命令：

macOS / Linux（脚本安装）：

rm -f /usr/local/bin/claude
rm -rf ~/.claude

Homebrew：

brew uninstall --cask claude-code

Windows（脚本安装）：

Remove-Item "$env:LOCALAPPDATA\claude-code" -Recurse -Force
Remove-Item "$env:APPDATA\claude" -Recurse -Force

WinGet：

winget uninstall Anthropic.ClaudeCode

常见安装问题

问题：claude 命令找不到

• 确认安装脚本执行成功，没有报错
• 尝试重新打开终端窗口，或手动刷新 PATH：source ~/.bashrc（Linux/macOS）
• 检查安装目录是否在 PATH 中

问题：权限错误

• macOS/Linux：使用 sudo 执行安装脚本，或手动调整安装目录权限
• Windows：以管理员身份运行 PowerShell

问题：网络连接失败

• 检查防火墙或代理设置
• 尝试使用其他网络环境
• 确认可以访问 claude.ai 和 anthropic.com

下一步

安装完成后，请进入下一章「快速上手：启动与基本对话」，学习如何使用 Claude Code 进行首次交互。

3.1 启动 Claude Code

安装完成后，启动 Claude Code 非常简单。打开终端，进入你的项目目录，然后运行：

cd /path/to/your/project
claude

首次启动时，Claude Code 会进行初始化设置：

1. 登录验证：它会提示你登录 Anthropic 账户。如果尚未登录，终端会显示一个链接，在浏览器中打开并完成授权。
2. 项目扫描：登录成功后，Claude Code 会自动扫描当前项目目录，识别文件结构、编程语言、依赖管理等关键信息。
3. 初始化完成：扫描完成后，你会看到类似下面的提示，表示已进入交互模式：

Claude Code ready. How can I help you with your codebase?

注意：如果项目目录很大（如包含 node_modules、.git 等），Claude Code 会自动忽略这些目录以提升性能。你也可以通过 .claudeignore 文件自定义忽略规则。

3.2 基本对话

启动后，你就可以像与 Claude 聊天一样，用自然语言提出需求。Claude Code 会理解你的意图并执行相应操作。

示例对话：

你：这个项目的入口文件是哪个？
Claude Code：扫描项目结构后，发现入口文件是 src/index.js。需要我打开看看吗？

你：帮我解释一下 utils/helpers.js 里的 debounce 函数。
Claude Code：好的，我来分析这个函数...

基本交互规则：

• 直接提问：像聊天一样输入问题，Claude Code 会结合项目上下文回答。
• 多轮对话：可以连续提问，Claude Code 会记住之前的对话历史。
• 中断操作：按 Ctrl+C 可以中断当前正在执行的任务。
• 退出程序：输入 exit 或按 Ctrl+D 退出 Claude Code。

3.3 常用命令

在对话中，你可以使用一些特殊命令来快速完成常见操作：

命令	作用
/help	显示帮助信息，列出所有可用命令
/clear	清除当前对话历史
/bug	报告问题（会收集相关上下文发送给 Anthropic）
exit	退出 Claude Code

示例：

你：/help
Claude Code：以下是可用命令列表...

3.4 第一次实战：让 Claude Code 帮你理解代码

假设你刚接手一个 Node.js 项目，想快速了解项目结构。启动 Claude Code 后，可以这样操作：

你：这个项目是做什么的？列出主要功能模块。
Claude Code：根据 package.json 和项目结构，这是一个...

你：帮我画出核心数据流图。
Claude Code：我会分析代码调用关系，然后生成一个 ASCII 流程图...

你：main.js 里的那个 handleRequest 函数具体做了什么？
Claude Code：我来分析这个函数...

3.5 注意事项

• 首次启动较慢：因为需要扫描项目并加载模型，首次启动可能需要 10-30 秒。
• 网络要求：Claude Code 需要联网才能工作，所有处理都在云端完成。
• 对话上下文：Claude Code 会记住当前会话中的对话历史，但退出后历史会丢失。如果需要保存，可以手动复制对话内容。
• 不要输入敏感信息：不要在对话中输入密码、API Key 等敏感信息，因为数据会发送到 Anthropic 服务器。

3.6 常见问题

Q：启动后提示 "Authentication required"？ A：按照终端显示的链接，在浏览器中登录 Anthropic 账户并授权即可。

Q：启动后卡在 "Scanning project..."？ A：如果项目非常大，扫描时间会较长。可以按 Ctrl+C 中断，然后检查项目目录是否包含过多文件。你也可以创建一个 .claudeignore 文件来排除不需要扫描的目录。

Q：对话时出现 "Request failed" 错误？ A：检查网络连接是否正常，或者是否被防火墙/代理拦截。Claude Code 需要访问 api.anthropic.com。

Q：如何更新 Claude Code？ A：根据你的安装方式，运行相应的更新命令：

• MacOS/Linux（curl 安装）：重新运行安装脚本
• Homebrew：brew upgrade --cask claude-code
• Windows（PowerShell 安装）：重新运行安装脚本
• WinGet：winget upgrade Anthropic.ClaudeCode

现在你已经掌握了 Claude Code 的启动和基本对话方法，可以开始用它来加速你的开发工作了。下一章将深入讲解代码理解与解释功能。

4.1 理解代码库结构

Claude Code 能够自动扫描并理解你的项目结构。启动后，它会读取项目中的关键文件（如 package.json、requirements.txt、CMakeLists.txt 等），建立对代码库的整体认知。

操作步骤：

1. 在项目根目录启动 Claude Code：

   cd your-project
   claude

2. 询问项目结构概览：

   这个项目的整体架构是什么？主要目录和文件的作用是什么？

3. 查看特定模块的依赖关系：

   列出 src/utils 目录下的所有函数及其调用关系

注意事项：

• Claude Code 会自动忽略 .gitignore 中的文件和目录
• 大型项目首次扫描可能需要几秒钟
• 可以通过 /compact 命令手动触发重新扫描

4.2 代码解释与文档生成

4.2.1 逐行解释代码

选中或指定代码片段，要求 Claude 解释其工作原理：

解释下面这段代码的功能和逻辑：
```python
def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n-1) + fibonacci(n-2)

Claude 会返回：

• 函数目的
• 算法复杂度分析
• 潜在问题（如递归深度限制）
• 优化建议

4.2.2 生成文档注释

为现有代码生成 JSDoc、Docstring 或其他格式的文档：

为 src/database/connection.py 中的所有函数生成 Google 风格的 Docstring

4.2.3 理解复杂算法

解释这个排序算法的时间复杂度和空间复杂度，并用通俗语言描述其工作原理：
[粘贴代码]

4.3 代码搜索与定位

4.3.1 按功能搜索

找到项目中所有处理用户认证的代码

4.3.2 查找特定模式

搜索所有使用了 fetch API 的地方，并列出它们的 URL 参数

4.3.3 定位错误来源

在 error.log 中看到 "TypeError: Cannot read property 'id' of undefined"，帮我找到可能引发这个错误的代码位置

4.4 代码质量分析

4.4.1 代码审查

审查 src/auth/login.ts 的代码质量，指出：
- 潜在的安全漏洞
- 性能瓶颈
- 不符合最佳实践的地方
- 改进建议

4.4.2 检测反模式

检查项目中是否存在常见的反模式，如：
- 硬编码的密钥或密码
- 过长的函数
- 重复代码块
- 未处理的 Promise

4.4.3 类型与接口分析

列出 src/types 目录下所有接口，并检查它们是否被正确实现

4.5 依赖关系分析

4.5.1 查看依赖树

显示项目的完整依赖树，并标记出过时的包

4.5.2 分析未使用的依赖

检查 package.json 中哪些依赖没有被实际使用

4.5.3 安全漏洞扫描

检查项目的依赖是否存在已知的安全漏洞，并给出修复建议

4.6 跨文件理解

Claude Code 能够关联多个文件，理解代码间的调用关系：

从用户点击"提交"按钮开始，追踪整个请求处理流程，直到数据库写入完成。列出涉及的所有文件和函数

示例输出：

1. src/components/Form.tsx → handleSubmit() 函数
2. src/api/submit.ts → POST /api/submit 路由
3. src/controllers/submission.ts → processSubmission() 控制器
4. src/services/validation.ts → validateFormData() 验证服务
5. src/models/Submission.ts → save() 数据库模型

4.7 交互式调试辅助

4.7.1 理解运行时状态

我在调试时遇到这个错误堆栈：
[粘贴错误信息]
帮我分析可能的原因，并建议如何修复

4.7.2 添加调试日志

在 src/checkout/payment.ts 的 processPayment 函数中添加详细的调试日志，帮助追踪支付流程

4.7.3 模拟代码执行

假设输入参数为 { userId: 123, amount: 50 }，手动模拟 calculateDiscount 函数的执行过程，输出每一步的中间变量值

4.8 最佳实践

1. 明确上下文：在提问时尽量指定文件路径或代码范围，避免模糊描述
2. 分步提问：对于复杂代码，先问整体结构，再深入细节
3. 利用对话历史：Claude Code 会记住之前的对话，可以基于之前的分析继续提问
4. 验证结果：对于生成的文档或分析，建议手动验证关键部分

示例完整对话流程：

你: 这个项目的核心业务逻辑是什么？
Claude: [分析项目结构并回答]

你: 聚焦 src/billing 目录，解释其中的计费流程
Claude: [详细解释计费模块]

你: 在 calculateInvoice 函数中添加错误处理
Claude: [生成修改后的代码并解释改动]

通过以上功能，Claude Code 能够帮助你快速理解陌生代码库、定位问题、生成文档，大幅提升代码阅读和维护效率。

5.1 任务执行基础

Claude Code 不仅能理解代码，还能直接在你的终端中执行命令、运行脚本、管理文件系统。这是它作为“代理式编码工具”的核心能力之一。

5.1.1 执行 Shell 命令

你可以用自然语言让 Claude Code 执行几乎任何终端命令。它会自动判断命令是否安全，并在执行前请求你的确认。

示例：

> 帮我查看当前目录下最大的5个文件

Claude Code 会分析后执行类似 du -sh * | sort -rh | head -5 的命令，并展示结果。

直接执行命令：

你也可以在对话中直接嵌入命令，Claude Code 会识别并执行：

> 运行 npm run build，然后告诉我是否有错误

注意事项：

• Claude Code 在执行可能造成破坏的命令（如 rm -rf、git push --force）前会要求你确认。
• 你可以使用 --yes 或 -y 标志跳过确认（谨慎使用）。

5.1.2 文件操作

Claude Code 可以读取、创建、修改和删除文件。这是自动化任务的基础。

读取文件：

> 读取 src/config.js 文件，告诉我数据库配置部分

创建文件：

> 在当前目录创建一个名为 deploy.sh 的脚本，内容为部署流程

修改文件：

> 将 package.json 中的版本号从 1.0.0 改为 1.1.0

批量操作：

> 将所有 .txt 文件重命名为 .md 文件

5.2 自动化工作流

Claude Code 可以串联多个步骤，形成自动化工作流。你可以通过自然语言描述整个流程，它会逐步执行。

5.2.1 构建与测试自动化

示例：自动构建并运行测试

> 帮我执行完整的 CI 流程：先安装依赖，然后运行 lint，再执行单元测试，最后构建项目

Claude Code 会依次执行：

1. npm install（或对应包管理器命令）
2. npm run lint
3. npm test
4. npm run build

每一步的结果都会反馈给你，如果某一步失败，它会报告错误并停止。

5.2.2 代码格式化与清理

> 清理项目中的所有 console.log 语句，但保留 warn 和 error

Claude Code 会扫描所有源文件，找到 console.log 调用并移除它们，同时保留 console.warn 和 console.error。

更复杂的清理任务：

> 删除所有未使用的 import 语句，并按照标准排序剩余的 import

5.2.3 批量重构

示例：重命名函数

> 将项目中所有名为 fetchData 的函数重命名为 getData，并更新所有调用处

Claude Code 会：

1. 搜索所有包含 fetchData 的文件
2. 修改函数定义
3. 更新所有引用该函数的地方
4. 确认没有遗漏

示例：迁移 API 调用

> 将项目中所有从 /api/v1 的请求改为 /api/v2，并更新对应的请求头

5.3 使用插件扩展自动化能力

Claude Code 支持插件系统，可以扩展自定义命令和自动化能力。插件位于项目的 plugins/ 目录下。

5.3.1 查看可用插件

> 列出所有可用的插件

Claude Code 会扫描 plugins/ 目录并显示每个插件的名称和描述。

5.3.2 启用插件

插件通常通过配置文件启用。你可以在项目根目录创建或编辑 .claude.json 文件：

{
  "plugins": ["plugin-name"]
}

5.3.3 使用插件命令

启用插件后，你可以使用插件提供的自定义命令。例如，某个部署插件可能提供：

> /deploy --env production

5.4 高级自动化技巧

5.4.1 条件执行

你可以让 Claude Code 根据条件决定是否执行某个步骤：

> 如果 package.json 中有 eslint 依赖，则运行 lint；否则跳过

5.4.2 循环与批量处理

> 遍历 src/components 目录下的所有 .vue 文件，为每个文件添加一个简单的单元测试文件

5.4.3 错误处理与回滚

> 先备份当前分支，然后尝试升级所有 npm 包到最新版本。如果升级后测试失败，自动回滚到备份

5.5 安全注意事项

• 敏感操作确认：Claude Code 在执行删除、覆盖、推送等操作前会请求确认。不要使用 --yes 标志跳过这些确认，除非你完全清楚后果。
• 环境变量：避免在对话中直接输入密码或 API 密钥。Claude Code 可以读取 .env 文件，但不会记录或分享这些信息。
• 命令审计：你可以随时要求 Claude Code 显示它将要执行的命令，而不实际执行：

> 显示你将要执行的所有命令，但不要执行

5.6 实战示例：完整的自动化部署流程

以下是一个完整的自动化部署示例，展示了 Claude Code 如何串联多个任务：

用户输入：

> 帮我完成部署流程：
1. 从 main 分支创建一个 release/v2.1 分支
2. 更新 package.json 版本号到 2.1.0
3. 运行测试确保一切正常
4. 构建生产版本
5. 将 release 分支推送到远程仓库
6. 在 GitHub 上创建一个 Pull Request 到 main 分支

Claude Code 执行过程：

1. 创建分支：git checkout -b release/v2.1 main
2. 更新版本：修改 package.json 中的 version 字段
3. 运行测试：npm test（等待结果）
4. 构建：npm run build
5. 推送：git push origin release/v2.1
6. 创建 PR：使用 GitHub CLI 或 API 创建 Pull Request

每一步完成后，Claude Code 都会报告状态，如果某一步失败，它会询问你是否要继续或修复问题。

5.7 常见问题

Q: Claude Code 执行命令时卡住了怎么办？ A: 你可以按 Ctrl+C 中断当前命令，然后重新描述你的需求。

Q: 如何让 Claude Code 不执行命令，只给出建议？ A: 在请求中明确说明“只给出命令，不要执行”或“模拟执行”。

Q: 可以限制 Claude Code 只能执行某些命令吗？ A: 目前不支持命令白名单，但你可以通过 .claude.json 配置文件禁用某些插件或功能。

6.1 Git 工作流集成概述

Claude Code 深度集成了 Git 工作流，让你可以通过自然语言指令完成常见的 Git 操作。无论是创建分支、提交代码、处理合并冲突，还是查看历史记录，Claude Code 都能理解你的意图并自动执行相应的 Git 命令。

核心能力

• 智能提交：自动生成有意义的提交信息
• 分支管理：创建、切换、合并分支
• 冲突解决：分析并解决合并冲突
• 历史查询：查看提交历史、差异对比
• 代码审查：自动审查变更并生成报告

6.2 基本 Git 操作

6.2.1 查看仓库状态

在 Claude Code 中，你可以直接询问当前仓库的状态：

# 查看当前状态
claude "检查当前 Git 仓库状态"

# 查看未暂存的更改
claude "显示所有未提交的更改"

Claude Code 会执行 git status 和 git diff 命令，并以清晰的方式展示结果。

6.2.2 暂存与提交

# 暂存所有更改并提交
claude "暂存所有更改并提交，提交信息为'修复登录页面的样式问题'"

# 只暂存特定文件
claude "只暂存 src/utils.js 和 tests/test_utils.js 这两个文件，然后提交"

Claude Code 会执行以下步骤：

1. git add <files> 暂存文件
2. git commit -m "提交信息" 创建提交

6.2.3 自动生成提交信息

如果你不想手动编写提交信息，可以让 Claude Code 根据更改内容自动生成：

# 暂存所有更改，并让 Claude 自动生成提交信息
claude "暂存所有更改并提交，提交信息根据更改内容自动生成"

# 查看 Claude 生成的提交信息示例
# 输出可能类似：
# feat(auth): 修复登录页面在移动设备上的样式兼容性问题
# 
# - 调整按钮在窄屏下的宽度
# - 修复输入框在 iOS 上的圆角显示
# - 优化表单验证提示的布局

注意：自动生成的提交信息遵循 Conventional Commits 规范，包含类型（feat/fix/docs 等）、作用域和描述。

6.3 分支管理

6.3.1 创建与切换分支

# 创建新分支并切换过去
claude "创建一个名为 feature/user-profile 的新分支，并切换过去"

# 基于当前更改创建分支
claude "将当前未提交的更改移到新分支 feature/experiment 上"

6.3.2 合并分支

# 合并其他分支到当前分支
claude "将 feature/user-profile 分支合并到当前分支"

# 合并并保留分支历史
claude "将 develop 分支合并到 main，使用 --no-ff 选项"

6.3.3 处理合并冲突

当合并出现冲突时，Claude Code 可以帮你分析并解决：

# 合并后出现冲突，让 Claude 帮助解决
claude "合并 main 分支时出现了冲突，帮我分析并解决"

# Claude 会：
# 1. 显示冲突文件列表
# 2. 分析每个冲突的上下文
# 3. 提出解决方案（保留哪部分代码）
# 4. 执行 git add 标记已解决
# 5. 完成合并提交

注意：对于复杂的冲突，建议先让 Claude 展示冲突内容，确认解决方案后再执行。

6.4 历史查询与差异对比

6.4.1 查看提交历史

# 查看最近 5 条提交
claude "显示最近 5 次提交记录"

# 按作者筛选
claude "查看张三最近一周的所有提交"

# 按文件筛选
claude "查看 src/components 目录下的所有提交历史"

6.4.2 差异对比

# 查看工作区与暂存区的差异
claude "显示当前未暂存的更改"

# 查看两个分支的差异
claude "比较 main 分支和 develop 分支的差异"

# 查看特定提交的更改
claude "显示提交 abc123 中更改了哪些文件"

6.5 撤销与回退

# 撤销工作区的更改
claude "撤销 src/utils.js 的所有未暂存更改"

# 取消暂存
claude "取消暂存所有文件"

# 回退到上一个提交（保留更改在工作区）
claude "回退最近一次提交，但保留更改在工作区"

# 硬重置到指定提交
claude "硬重置到提交 abc123，丢弃所有未提交的更改"

注意：硬重置操作会丢失未提交的更改，Claude Code 在执行前会要求你确认。

6.6 代码审查

6.6.1 审查未提交的更改

# 审查当前所有更改
claude "审查我当前的所有更改，指出潜在问题"

# 审查特定文件的更改
claude "审查 src/api.js 的更改，重点关注安全性问题"

6.6.2 审查 Pull Request

# 审查某个分支相对于 main 的更改
claude "审查 feature/new-feature 分支相对于 main 的所有更改"

# 生成审查报告
claude "为 feature/new-feature 分支生成代码审查报告，包括：
- 变更概述
- 潜在问题
- 改进建议
- 测试覆盖情况"

6.7 高级 Git 工作流

6.7.1 交互式变基

# 交互式变基最近 3 个提交
claude "对最近 3 个提交执行交互式变基，合并提交信息为'实现用户认证功能'"

# 自动压缩提交
claude "将最近 5 个提交压缩成一个提交，提交信息自动生成"

6.7.2 Cherry-pick

# 将特定提交应用到当前分支
claude "将提交 abc123 和 def456 应用到当前分支"

# 从其他分支挑选提交
claude "从 feature/user-profile 分支挑选最近 2 个提交到当前分支"

6.7.3 Stash 操作

# 暂存当前更改
claude "暂存当前所有更改，标签为'临时保存的样式调整'"

# 恢复暂存
claude "恢复最近一次暂存的更改"

# 查看所有暂存
claude "显示所有暂存记录"

6.8 实用工作流示例

示例 1：完整的功能开发流程

# 1. 从 main 创建功能分支
claude "从 main 创建并切换到 feature/add-search"

# 2. 进行开发...（修改文件）

# 3. 查看更改
claude "显示所有更改"

# 4. 提交更改
claude "暂存所有更改并提交，自动生成提交信息"

# 5. 推送到远程
claude "将当前分支推送到远程"

# 6. 创建 Pull Request
claude "在 GitHub 上为当前分支创建 Pull Request，标题为'添加搜索功能'"

示例 2：紧急修复流程

# 1. 保存当前工作
claude "暂存当前所有更改"

# 2. 创建修复分支
claude "从 main 创建并切换到 hotfix/critical-bug"

# 3. 修复问题...（修改文件）

# 4. 提交并推送
claude "暂存所有更改，提交信息为'修复生产环境中的关键错误'，然后推送到远程"

# 5. 恢复之前的工作
claude "恢复之前暂存的更改"

6.9 注意事项

1. 确认操作：对于可能造成数据丢失的操作（如硬重置、强制推送），Claude Code 会要求你确认。

2. 远程仓库：Claude Code 支持 GitHub、GitLab、Bitbucket 等主流 Git 托管平台。

3. 权限要求：执行推送、创建 PR 等操作需要相应的远程仓库权限。

4. 大仓库性能：对于大型仓库，建议在查询历史或差异时指定范围，避免性能问题。

5. 自定义 Git 配置：Claude Code 会尊重你的 Git 全局配置（如用户名、邮箱、编辑器等）。

通过本章的学习，你应该能够熟练使用 Claude Code 完成日常的 Git 工作流操作，从基本的提交到复杂的分支管理，都能通过自然语言指令高效完成。

7.1 理解自定义命令机制

Claude Code 支持通过插件系统扩展自定义命令。插件本质上是遵循特定目录结构的脚本集合，可以注册新的斜杠命令（如 /my-command）或自定义行为。本章将带你从零创建、安装和使用自定义命令与插件。

7.2 插件目录结构

一个标准的 Claude Code 插件包含以下结构：

my-plugin/
├── README.md          # 插件说明文档（可选）
├── package.json       # 插件元数据（必需）
└── commands/          # 命令目录（可选）
    ├── my-command.js
    └── another-command.js

7.2.1 创建 package.json

在插件根目录创建 package.json，定义插件基本信息：

{
  "name": "my-custom-plugin",
  "version": "1.0.0",
  "description": "我的自定义插件",
  "claude-code": {
    "commands": [
      {
        "name": "hello",
        "description": "向用户问好",
        "script": "./commands/hello.js"
      }
    ]
  }
}

关键字段说明：

• name：插件名称，需唯一
• claude-code.commands：注册的命令列表
• 每个命令需指定 name（斜杠后的命令名）、description（帮助信息）、script（执行脚本路径）

7.3 编写第一个自定义命令

7.3.1 创建命令脚本

在 commands/hello.js 中编写命令逻辑：

// commands/hello.js
module.exports = {
  async execute(args, context) {
    const name = args[0] || 'World';
    return `Hello, ${name}! 欢迎使用自定义命令。`;
  }
};

脚本必须导出一个包含 execute 方法的对象：

• args：用户输入的命令参数数组（如 /hello Claude 中 args 为 ['Claude']）
• context：包含当前会话上下文的对象（如项目路径、文件系统等）

7.3.2 安装插件

将插件目录放置到 Claude Code 的插件搜索路径中。默认搜索路径为：

• 全局插件目录：~/.claude/plugins/
• 项目级插件目录：项目根目录下的 .claude/plugins/

安装方式：

# 复制插件到全局目录
cp -r my-plugin ~/.claude/plugins/

# 或复制到项目级目录
cp -r my-plugin .claude/plugins/

7.3.3 验证安装

启动 Claude Code 后，输入 / 查看可用命令列表，应能看到新注册的 /hello 命令：

claude

在对话中输入：

/hello Claude

预期输出：

Hello, Claude! 欢迎使用自定义命令。

7.4 高级命令：访问文件系统

7.4.1 创建文件统计命令

创建一个统计当前项目文件数量的命令：

// commands/file-count.js
const fs = require('fs');
const path = require('path');

module.exports = {
  async execute(args, context) {
    const targetDir = args[0] || '.';
    const absolutePath = path.resolve(context.projectRoot, targetDir);
    
    try {
      const files = fs.readdirSync(absolutePath);
      const fileCount = files.filter(f => fs.statSync(path.join(absolutePath, f)).isFile()).length;
      const dirCount = files.filter(f => fs.statSync(path.join(absolutePath, f)).isDirectory()).length;
      
      return `目录 "${targetDir}" 包含 ${fileCount} 个文件和 ${dirCount} 个子目录。`;
    } catch (error) {
      return `错误：无法读取目录 "${targetDir}" - ${error.message}`;
    }
  }
};

更新 package.json 注册新命令：

{
  "name": "my-custom-plugin",
  "version": "1.0.0",
  "description": "我的自定义插件",
  "claude-code": {
    "commands": [
      {
        "name": "hello",
        "description": "向用户问好",
        "script": "./commands/hello.js"
      },
      {
        "name": "file-count",
        "description": "统计目录中的文件和子目录数量",
        "script": "./commands/file-count.js"
      }
    ]
  }
}

7.4.2 使用文件统计命令

# 统计当前目录
/file-count

# 统计 src 目录
/file-count src

7.5 使用内置插件

Claude Code 官方提供了一些预置插件，位于项目仓库的 plugins/ 目录。你可以直接启用它们。

7.5.1 启用官方插件

从 Claude Code 仓库 克隆或下载插件目录：

# 克隆仓库（如果尚未克隆）
git clone https://github.com/anthropics/claude-code.git

# 复制所需插件到项目目录
cp -r claude-code/plugins/my-plugin .claude/plugins/

7.5.2 常用官方插件示例

插件名称	功能描述
code-review	自动审查代码变更
test-runner	运行测试并报告结果
deploy-helper	简化部署流程

启用后，在 Claude Code 中使用对应命令：

/code-review
/test-runner
/deploy-helper

7.6 自定义命令与上下文交互

7.6.1 获取当前会话信息

命令脚本可以通过 context 对象访问会话上下文：

// commands/session-info.js
module.exports = {
  async execute(args, context) {
    return `
当前会话信息：
- 项目根目录：${context.projectRoot}
- 当前工作目录：${context.cwd}
- 会话 ID：${context.sessionId}
- 已执行命令数：${context.commandCount}
    `.trim();
  }
};

7.6.2 调用其他命令

在命令中调用其他已注册命令：

// commands/chain.js
module.exports = {
  async execute(args, context) {
    // 调用 /hello 命令
    const helloResult = await context.executeCommand('hello', ['Claude']);
    // 调用 /file-count 命令
    const countResult = await context.executeCommand('file-count', []);
    
    return `${helloResult}\n${countResult}`;
  }
};

7.7 调试自定义命令

7.7.1 启用调试日志

在启动 Claude Code 时设置环境变量：

DEBUG=claude-code:plugins claude

7.7.2 常见错误排查

错误现象	可能原因	解决方法
命令未显示在列表中	插件未正确安装	检查插件目录是否在搜索路径中
执行时报错 "Module not found"	脚本路径错误	检查 package.json 中的 script 路径
命令无响应	脚本语法错误	使用 node -c 检查脚本语法
返回空结果	未正确返回字符串	确保 execute 方法返回字符串或 Promise<string>

7.8 发布与分享插件

7.8.1 打包插件

将插件目录打包为可分享的格式：

# 创建插件包
tar -czf my-plugin.tar.gz my-plugin/

# 或使用 npm pack（如果有 package.json）
cd my-plugin && npm pack

7.8.2 安装他人分享的插件

# 从压缩包安装
tar -xzf my-plugin.tar.gz -C ~/.claude/plugins/

# 从 Git 仓库安装
git clone https://github.com/user/my-plugin.git ~/.claude/plugins/my-plugin

7.9 最佳实践

1. 命名规范：命令名使用小写字母和连字符（如 code-review）
2. 错误处理：始终捕获异常并返回友好的错误信息
3. 参数验证：检查参数有效性，提供默认值
4. 文档完善：在 README.md 中说明命令用法和示例
5. 版本管理：使用语义化版本号（SemVer）管理插件更新
6. 测试覆盖：为命令脚本编写单元测试

7.10 完整示例：TODO 管理插件

创建一个完整的 TODO 管理插件，展示自定义命令的完整开发流程。

7.10.1 目录结构

todo-plugin/
├── package.json
└── commands/
    ├── todo-add.js
    ├── todo-list.js
    └── todo-done.js

7.10.2 package.json

{
  "name": "todo-plugin",
  "version": "1.0.0",
  "description": "简单的 TODO 管理插件",
  "claude-code": {
    "commands": [
      {
        "name": "todo-add",
        "description": "添加新的 TODO 项",
        "script": "./commands/todo-add.js"
      },
      {
        "name": "todo-list",
        "description": "列出所有 TODO 项",
        "script": "./commands/todo-list.js"
      },
      {
        "name": "todo-done",
        "description": "标记 TODO 项为完成",
        "script": "./commands/todo-done.js"
      }
    ]
  }
}

7.10.3 命令脚本

// commands/todo-add.js
const fs = require('fs');
const path = require('path');

module.exports =

8.1 安装与启动问题

8.1.1 安装脚本执行失败

现象：运行 curl -fsSL https://claude.ai/install.sh | bash 后出现网络错误或权限不足。

解决方案：

1. 检查网络连接：确保终端可以访问 claude.ai。可尝试：

   curl -I https://claude.ai

   若返回非 200 状态码，请检查代理或防火墙设置。

2. 手动下载安装脚本：

   curl -O https://claude.ai/install.sh
   chmod +x install.sh
   ./install.sh

3. 使用 Homebrew 替代（macOS/Linux）：

   brew install --cask claude-code

4. 权限问题：若提示 Permission denied，尝试：

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

8.1.2 Windows 安装失败

现象：PowerShell 脚本执行报错或 winget 找不到包。

解决方案：

1. 启用 PowerShell 执行策略：

   Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

2. 手动下载安装包：访问 Claude Code 官方下载页 获取 .exe 安装程序。

3. 使用 WinGet 时指定源：

   winget install Anthropic.ClaudeCode --source winget

8.1.3 命令 claude 未找到

现象：安装成功后，在终端输入 claude 提示命令不存在。

解决方案：

1. 检查安装路径：

   which claude

   若无输出，说明未添加到 PATH。

2. 手动添加 PATH（macOS/Linux）：

   export PATH="$HOME/.local/bin:$PATH"

   将上述命令添加到 ~/.bashrc 或 ~/.zshrc 中永久生效。

3. 重新加载 shell 配置：

   source ~/.zshrc  # 或 source ~/.bashrc

4. Windows 用户：检查 %USERPROFILE%\AppData\Local\Programs\Claude Code 是否在 PATH 中。

8.2 运行时错误

8.2.1 API 认证失败

现象：启动后提示 Authentication failed 或 Invalid API key。

解决方案：

1. 检查 API 密钥：确保已设置有效的 Anthropic API 密钥。

   echo $ANTHROPIC_API_KEY

   若为空，设置密钥：

   export ANTHROPIC_API_KEY="your-api-key-here"

2. 验证密钥有效性：使用 curl 测试：

   curl -H "x-api-key: $ANTHROPIC_API_KEY" https://api.anthropic.com/v1/messages

3. 检查密钥权限：确认密钥未过期且具有 Claude Code 使用权限。

4. 重新登录：运行 claude logout 后再次 claude login。

8.2.2 内存不足

现象：处理大型代码库时出现 Out of memory 或进程被系统杀死。

解决方案：

1. 限制上下文大小：启动时指定较小的上下文窗口：

   claude --max-tokens 4096

2. 分步处理：不要一次性加载整个项目，使用 cd 进入子目录后再启动 Claude Code。

3. 增加系统交换空间（Linux）：

   sudo fallocate -l 4G /swapfile
   sudo chmod 600 /swapfile
   sudo mkswap /swapfile
   sudo swapon /swapfile

4. 关闭其他内存密集型应用。

8.2.3 网络超时

现象：请求长时间无响应，最终提示 Timeout。

解决方案：

1. 检查网络稳定性：运行 ping api.anthropic.com 查看延迟。

2. 设置超时时间：

   claude --timeout 120  # 将超时设为 120 秒

3. 使用代理（如公司网络）：

   export HTTP_PROXY=http://proxy.example.com:8080
   export HTTPS_PROXY=http://proxy.example.com:8080
   claude

4. 切换 API 端点：若使用自定义端点，确保 URL 正确。

8.3 功能使用问题

8.3.1 代码理解不准确

现象：Claude Code 对代码的解释或修改不符合预期。

解决方案：

1. 提供更多上下文：明确指定文件路径或函数名。

   # 不好的提问
   解释这段代码
   
   # 好的提问
   解释 src/utils/parser.ts 中的 parseConfig 函数

2. 使用 /context 命令：手动添加相关文件到上下文。

   /context add src/main.ts src/utils/helper.ts

3. 检查项目结构：确保 Claude Code 能访问所有相关文件。

   ls -la  # 确认文件存在且可读

4. 重新索引项目：运行 claude --reindex 刷新代码库索引。

8.3.2 Git 操作失败

现象：执行 Git 相关命令（如提交、分支切换）时出错。

解决方案：

1. 检查 Git 状态：

   git status

2. 解决冲突：若有未解决的合并冲突，先手动解决：

   git merge --abort  # 取消合并

3. 确保 Git 配置完整：

   git config --global user.name "Your Name"
   git config --global user.email "your.email@example.com"

4. 使用 /git 命令手动控制：

   /git status
   /git commit -m "fix: resolve merge conflict"

8.3.3 插件加载失败

现象：安装插件后无法使用自定义命令。

解决方案：

1. 检查插件目录：确保插件放在正确的路径。

   ls ~/.claude/plugins/

2. 验证插件格式：插件应为 .js 或 .mjs 文件，且导出符合规范。

3. 查看错误日志：

   claude --verbose  # 启动时显示详细日志

4. 重新加载插件：

   /plugins reload

8.4 性能与稳定性

8.4.1 响应速度慢

现象：每次提问后等待时间过长。

优化建议：

1. 减少上下文大小：使用 --max-tokens 限制输出长度。

2. 使用本地模型（如适用）：配置本地推理端点以减少网络延迟。

3. 分批次提问：将复杂任务拆分为多个简单问题。

4. 升级网络带宽：确保上传/下载速度不低于 10 Mbps。

8.4.2 进程崩溃或卡死

现象：Claude Code 无响应，无法输入命令。

解决方案：

1. 强制退出：

   pkill -f claude

2. 清理缓存：

   rm -rf ~/.claude/cache

3. 更新到最新版本：

   claude update

4. 检查系统资源：使用 top 或 htop 查看 CPU/内存占用。

8.5 数据与隐私问题

8.5.1 如何清除对话历史

操作步骤：

1. 在 Claude Code 中运行：

   /clear

2. 手动删除历史文件：

   rm -rf ~/.claude/sessions/*

3. 禁用历史记录（启动时）：

   claude --no-history

8.5.2 如何报告 Bug

方法一：使用内置命令 在 Claude Code 中运行：

/bug

按照提示描述问题，系统会自动收集日志并提交。

方法二：提交 GitHub Issue 访问 GitHub Issues 页面，提供以下信息：

• 操作系统与版本
• Claude Code 版本（运行 claude --version）
• 复现步骤
• 完整错误日志

8.6 常见错误代码速查

错误代码	含义	解决方案
E001	API 密钥无效	检查并重新设置 ANTHROPIC_API_KEY
E002	请求超时	增加 --timeout 值或检查网络
E003	内存不足	减少上下文或增加系统内存
E004	文件权限不足	使用 chmod 或 sudo 运行
E005	Git 仓库未初始化	运行 git init 或切换到 Git 项目
E006	插件加载失败	检查插件格式和路径
E007	无效命令	使用 /help 查看可用命令列表

8.7 获取帮助

若以上方法均无法解决问题，可通过以下渠道获取支持

官方文档与资源

• 官方文档：code.claude.com/docs — 最权威的入门指南、配置说明、命令参考和最佳实践。
• GitHub 仓库：github.com/anthropics/claude-code — 查看源码、提交 Issue、了解最新更新。
• NPM 包：@anthropic-ai/claude-code — 可通过 npm info @anthropic-ai/claude-code 查看版本和依赖。

社区交流

• Discord 社区：anthropic.com/discord — 加入 Claude 开发者 Discord，与其他用户交流使用经验、分享技巧、提问求助。
• GitHub Issues：在仓库中提交 Bug 报告或功能建议。也可在 Claude Code 内直接使用 /bug 命令反馈问题。

插件生态

Claude Code 支持通过插件扩展功能。官方仓库的 plugins/ 目录下提供了多个示例插件，涵盖自定义命令和专用代理。详情见 plugins/README.md。

安装插件示例

# 克隆仓库后，进入插件目录
cd plugins/example-plugin
# 按照插件文档进行安装和配置

数据与隐私

使用 Claude Code 时，系统会收集以下反馈数据：

• 使用数据（如代码接受/拒绝行为）
• 关联的对话内容
• 通过 /bug 命令提交的用户反馈

详细的数据使用政策请参阅 官方数据使用文档。隐私保护措施包括：

• 敏感信息的有限保留期限
• 用户会话数据的访问限制
• 明确禁止将反馈数据用于模型训练

完整条款请查阅 商业服务条款 和 隐私政策。

学习路径建议

1. 新手：先阅读官方文档的“快速开始”部分，完成安装和首次对话。
2. 日常使用：熟悉核心命令（/explain、/test、/review 等），掌握 Git 工作流集成。
3. 进阶：探索插件系统，编写自定义命令；参与 Discord 社区讨论，学习他人实践。
4. 贡献：在 GitHub 上提交 Issue 或 Pull Request，帮助改进项目。

常见问题速查

问题	解决方式
安装失败	检查网络环境，尝试使用代理；参考 安装文档
命令不生效	确认已进入项目目录，且 claude 命令在 PATH 中
输出乱码	检查终端编码设置，推荐 UTF-8
需要帮助	在 Discord 中提问，或使用 /bug 提交反馈

问题：安装时提示 curl: command not found 或 irm: command not recognized 怎么办？

这通常是因为你的系统缺少 curl（macOS/Linux）或 PowerShell 版本过低（Windows）。

• macOS/Linux：先安装 curl（如 brew install curl 或 apt install curl），再重新运行安装脚本。
• Windows：确保使用 PowerShell 5.1+ 或 PowerShell Core 7+，并以管理员身份运行。如果 irm 仍失败，改用 WinGet 方式：winget install Anthropic.ClaudeCode。

---

问题：安装后运行 claude 提示“command not found”或“不是内部或外部命令”

• macOS/Linux：检查是否将安装路径（通常是 ~/.local/bin 或 /usr/local/bin）添加到了 PATH 环境变量中。运行 echo $PATH 查看，若缺失则手动添加：export PATH="$HOME/.local/bin:$PATH"（可写入 ~/.bashrc 或 ~/.zshrc）。
• Windows：WinGet 安装后需重启终端或手动将 %LOCALAPPDATA%\Anthropic\ClaudeCode 加入 PATH。
• NPM 方式（已弃用）：若之前通过 npm 安装，请先卸载旧版本：npm uninstall -g @anthropic-ai/claude-code，再使用推荐方式安装。

---

问题：运行 claude 后提示“需要登录”或“API 密钥无效”

Claude Code 需要有效的 Anthropic 账户和 API 密钥。

1. 访问 console.anthropic.com 创建或获取 API 密钥。
2. 首次运行 claude 时，按提示输入密钥，或通过环境变量设置：export ANTHROPIC_API_KEY=你的密钥。
3. 若密钥已过期或权限不足，请检查账户订阅状态（免费版可能受限）。

---

问题：Claude Code 无法理解我的项目结构或代码

Claude Code 默认会分析当前目录下的文件（支持常见语言和框架）。如果它忽略某些文件或目录：

• 检查项目根目录是否有 .claudeignore 文件（类似 .gitignore），确保未错误排除关键代码。
• 对于大型项目，首次使用建议先运行 claude 并输入“分析项目结构”，它会自动扫描并建立上下文。
• 若文件编码非 UTF-8 或格式特殊（如二进制文件），可能无法解析。确保代码文件为纯文本格式。

---

问题：Claude Code 与 GitHub Copilot、Cursor 等工具有什么区别？

特性	Claude Code	GitHub Copilot / Cursor
运行环境	终端（CLI）	IDE 插件或独立编辑器
交互方式	自然语言对话、命令	代码补全、内联建议
核心能力	理解整个代码库、执行 Git 操作、自动化任务	代码生成、补全、重构
适用场景	复杂工作流、调试、代码审查	快速编码、补全片段

Claude Code 更侧重“代理式”任务执行（如“重构这个模块并提交 PR”），而 Copilot 更擅长“逐行补全”。两者可互补使用。

---

问题：如何卸载 Claude Code？

• macOS/Linux（脚本安装）：运行 curl -fsSL https://claude.ai/uninstall.sh | bash。
• Homebrew：brew uninstall --cask claude-code。
• Windows（PowerShell 脚本）：irm https://claude.ai/uninstall.ps1 | iex。
• WinGet：winget uninstall Anthropic.ClaudeCode。
• NPM（已弃用）：npm uninstall -g @anthropic-ai/claude-code。
  卸载后建议删除残留的配置文件（如 ~/.claude 目录）。

---

问题：使用 Claude Code 时，我的代码数据会被上传到 Anthropic 吗？

是的，Claude Code 会收集使用数据（如代码接受/拒绝、对话内容）以改进服务。但 Anthropic 承诺：

• 不会将你的代码用于模型训练（除非你主动提交 /bug 报告）。
• 敏感数据（如 API 密钥）有短期保留限制。
• 详细政策见 数据使用文档。
  若需完全离线使用，目前 Claude Code 不支持本地模型，建议在敏感项目中谨慎使用。

---

问题：在 Windows 上安装后，claude 命令无法在 Git Bash 或 WSL 中使用

• Git Bash：Claude Code 的 Windows 安装脚本默认将可执行文件放在 %LOCALAPPDATA%\Anthropic\ClaudeCode，Git Bash 可能无法识别。解决方法：在 Git Bash 中手动添加路径：export PATH="$PATH:/c/Users/你的用户名/AppData/Local/Anthropic/ClaudeCode"。
• WSL：建议在 WSL 内使用 Linux 安装方式（curl 脚本），而非 Windows 原生版本，以避免路径和权限问题。