Claude Code 综合指南

本指南旨在为人类开发者和 AI 代理提供全面参考。所有功能均已根据官方文档进行验证。

[官方] 标签表示功能来源于 docs.claude.com。
[社区] 标签表示在实践中观察到的模式。
[实验性] 标签表示尚未完全验证的概念。

什么是 Claude Code？

Claude Code 是一款在终端中运行的 AI 编程助理。它能够理解您的代码库、直接编辑文件、运行命令，并通过自然语言对话帮助您更快地编程。

核心能力

💬 自然语言接口：在您的终端中直接对话。
📝 文件编辑与命令执行：直接修改文件和执行 Shell 命令。
🔍 项目全局上下文感知：理解整个项目的结构。
🔗 外部集成：通过 MCP (模型上下文协议) 连接外部数据源。
🤖 可扩展性：通过技能 (Skills)、钩子 (Hooks) 和插件 (Plugins) 进行扩展。
🛡️ 沙箱执行：为安全操作提供沙箱环境。

安装

通过 npm 全局安装：

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

验证安装：

claude --version

官方文档位于 docs.claude.com/en/docs/claude-code/overview。

快速参考

核心命令 `[官方]`

# 启动 Claude Code
claude                 # 启动交互式会话
claude -p "任务描述"    # 打印模式 (非交互式)
claude --continue      # 继续上一次的会话
claude --resume <id>   # 恢复指定的会话

# 会话管理
/help                  # 显示可用命令
/exit                  # 结束会话
/compact               # 减少上下文大小
/microcompact          # 智能上下文清理 [新功能]

# 后台任务
/bashes                # 列出后台进程
/kill <id>             # 停止指定的后台进程

# 发现
/commands              # 列出所有斜杠命令
/hooks                 # 显示已配置的钩子
/skills                # 列出可用的技能 (Skills) [新功能]
/plugin                # 管理插件

CLI 标志参考 `[官方]`

# 输出控制
claude -p, --print "任务"     # 打印模式：非交互式，打印结果后退出
claude --output-format json # 输出格式：json, markdown, 或 text
claude --no-color           # 禁用彩色输出

# 会话管理
claude --continue           # 从上一次会话继续
claude --resume <session-id># 通过 ID 恢复指定会话
claude --list-sessions      # 列出所有可用会话

# 调试与日志
claude --debug              # 启用调试模式，输出详细日志
claude --log-level <level>  # 设置日志级别：error, warn, info, debug, trace

# 模型与配置
claude --model <model-name> # 指定使用的模型
claude --config <path>      # 使用自定义配置文件

# 沙箱 (macOS/Linux)
claude --sandbox            # 启用沙箱模式以增强安全性
claude --no-sandbox         # 禁用沙箱模式

常用组合

# 执行一次性任务并以 JSON 格式输出
claude --print "分析这段代码" --output-format json

# 使用自定义配置启动调试会话
claude --debug --config .claude/custom-settings.json

# 使用特定模型恢复会话
claude --resume abc123 --model claude-opus-4

# 在 CI/CD 环境中非交互式运行，无颜色输出
claude --print "运行测试" --no-color --output-format json

核心概念

1. 工作原理 `[官方]`

Claude Code 通过终端中的对话界面工作：

# 你：描述需求
$ claude > "为 API 添加用户认证功能"

# Claude Code 的执行流程:
# 1. 分析你的代码库结构。
# 2. 规划实现步骤。
# 3. (首次操作时) 请求文件编辑权限。
# 4. 直接将代码写入相关文件。
# 5. 可运行测试并验证变更。
# 6. 如果需要，可以创建 Git 提交。

关键原则:

自然语言: 只需描述您的需求，无需特殊语法。
直接操作: 在获得您的许可后，直接编辑文件和运行命令。
上下文感知: 理解您的整个项目结构。
增量信任: 在需要执行新操作时会请求权限。
可脚本化: 可通过 SDK 实现自动化。

2. 权限模型 `[官方]`

Claude Code 使用增量权限系统以确保安全：

权限模式:

"ask": 每次使用前提示 (新操作的默认模式)。
"allow": 允许执行，不再询问。
"deny": 完全阻止。

需要权限的工具:

Bash (命令执行)
Write/Edit/NotebookEdit (文件修改)
WebFetch/WebSearch (网络访问)
SlashCommand (自定义命令)

无需权限的安全操作:

Read/NotebookRead (读取文件)
Grep/Glob (搜索)
TodoWrite (任务跟踪)
Task (子代理)

配置权限

在项目根目录创建 .claude/settings.json 或在用户主目录创建 ~/.claude/settings.json 进行全局配置：

{
  "permissions": {
    "defaultMode": "ask",
    "allow": {
      "Bash": [
        "git status",
        "git diff",
al"git log",
        "npm test",
        "npm run*"
      ],
      "Read": {},
      "Edit": {}
    },
    "deny": {
      "Write": ["*.env", ".env.*", ".git/*"],
      "Edit": ["*.env", ".env.*"]
    },
    "additionalDirectories": ["/path/to/other/project"]
  }
}

3. 项目上下文：CLAUDE.md `[社区]`

在项目根目录中创建一个 CLAUDE.md 文件，可以为 Claude Code 提供跨会话的持久上下文。

# 项目: My Application

## 🔴 核心上下文 (优先阅读)
- 语言: TypeScript + Node.js
- 框架: Express + React
- 数据库: PostgreSQL with Prisma ORM
- 测试: Jest + React Testing Library

## 可用命令
```bash
npm run dev      # 启动开发服务器 (端口 3000)
npm test         # 运行所有测试
npm run lint     # ESLint 检查
npm run typecheck# TypeScript 类型校验
npm run db:migrate # 运行 Prisma 数据库迁移

重要模式

所有 API 路由位于 /src/routes，遵循 RESTful 结构。
数据库查询使用 Prisma Client。
认证使用 JWT (实现位于 /src/auth)。
前端组件位于 /src/components，使用函数式组件和 Hooks。
API 响应格式: {success: boolean, data: any, error?: string}

⚠️ 注意事项 & 禁忌

不要修改 /generated 目录 (由 Prisma 自动生成)。
不要提交 .env 文件 (使用 .env.example 作为模板)。
拉取 schema 变更后，务必运行 npm run db:migrate。
不要在 TypeScript 中使用 any 类型，请使用恰当的类型定义。
Redis 连接需要重试逻辑 (详见 src/redis.ts)。

文件结构模式

/src /routes # Express API 路由 /services # 业务逻辑 /models # 类型定义 /middleware # Express 中间件 /utils # 共享工具函数 /auth # 认证逻辑

近期学习

[2025-01-15] Stripe 的支付 Webhook 需要原始请求体解析器进行验证。
[2025-01-10] Redis 连接池应使用 {maxRetriesPerRequest: 3}。
[2025-01-05] 通过 useMemo 修复了因昂贵计算导致的 React 组件重复渲染问题。


**`CLAUDE.md` 的优势:**

*   ✅ 在会话开始时立即提供上下文。
*   ✅ 减少重复解释项目结构的需要。
*   ✅ 存储项目特定的模式和约定。
*   ✅ 记录有效（和无效）的操作。
*   ✅ 可通过 Git 与团队共享。
*   ✅ 格式经过优化，便于 Claude 快速理解。

**注意**：虽然 `CLAUDE.md` 不是官方功能，但它是一个被广泛采用的社区实践。如果项目根目录存在此文件，Claude Code 会自动读取它。

## 核心工具参考 `[官方]`

### Read 工具

**用途**: 读取和分析文件。

```bash
# 示例
Read file_path="/src/app.ts"
Read file_path="/docs/screenshot.png" # 可以读取图片！
Read file_path="/docs/guide.pdf"      # 可以读取 PDF！[新功能]

能力:

读取任何文本文件（代码、配置、日志等）。
处理图片（截图、图表、架构图）。
处理 PDF，提取文本和视觉内容。
解析 Jupyter Notebook (.ipynb 文件)。
返回带行号的内容（类似 cat -n 格式）。
可通过 offset 和 limit 参数读取大文件。

Write 工具

用途: 创建新文件。

Write file_path="/src/newFile.ts" content="export const config = {...}"

行为:

使用指定内容创建新文件。
如果文件已存在，会覆盖它（对于已存在的文件，应使用 Edit 工具）。
在每个会话中首次使用时需要权限。
如果父目录不存在，会自动创建。

最佳实践: 使用 Edit 工具修改现有文件，仅在创建全新文件时使用 Write 工具。

Edit 工具

用途: 通过精确的字符串替换来修改现有文件。

Edit file_path="/src/app.ts" old_string="const port = 3000" new_string="const port = process.env.PORT || 3000"

要点:

需要精确匹配字符串，包括空格和缩进。
如果 old_string 在文件中不唯一，操作会失败（此时应使用更大的上下文或 replace_all）。
使用 replace_all=true 可以替换所有匹配项（常用于重命名）。
在编辑前必须先读取文件。

通用模式:

# 1. 读取文件以查看确切内容
Read file_path="/src/app.ts"

# 2. 使用精确字符串进行编辑
Edit file_path="/src/app.ts" old_string="function login() { return 'TODO'; }" new_string="function login() { return authenticateUser(); }"

Bash 工具

用途: 执行 Shell 命令。

Bash command="npm test"
Bash command="git status"
Bash command="find . -name '*.test.ts'"

特性:

可以运行任何 Shell 命令。
支持后台执行 (run_in_background=true)。
可配置超时（默认 2 分钟，最长 10 分钟）。
常用于 Git 操作（status, diff, log, commit, push）。

安全:

需要权限。
可在设置中通过模式进行限制。
在 macOS/Linux 上可使用沙箱。

常用 Git 模式:

# 检查状态
Bash command="git status"

# 查看变更
Bash command="git diff"

# 创建提交
Bash command='git add . && git commit -m "feat: add authentication"'

# 查看历史
Bash command="git log --oneline -10"

Grep 工具

用途: 使用正则表达式搜索文件内容。

# 查找函数
Grep pattern="function.*auth" path="src/" output_mode="content"

# 查找 TODO 并显示上下文
Grep pattern="TODO" output_mode="content" -C=3

# 统计出现次数
Grep pattern="import.*from" output_mode="count"

# 不区分大小写搜索
Grep pattern="error" -i=true output_mode="files_with_matches"

参数:

pattern: 正则表达式模式 (ripgrep 语法)。
path: 要搜索的目录或文件。

👉 如果你需要 ChatGPT 代充 / Claude / Claude Code / 镜像 / 中转 API：

购买 / 了解更多：ai4.plus
备用入口：kk4099.com

什么是 Claude Code？#

核心能力#

安装#

快速参考#

核心命令 [官方]#

CLI 标志参考 [官方]#

常用组合#

核心概念#

1. 工作原理 [官方]#

2. 权限模型 [官方]#

配置权限#

3. 项目上下文：CLAUDE.md [社区]#

重要模式#

⚠️ 注意事项 & 禁忌#

文件结构模式#

近期学习#

Write 工具#

Edit 工具#

Bash 工具#

Grep 工具#