Appearance
Claude Code CLI 使用教程
最后更新：2026-08-11
Claude Code 是 Anthropic 推出的终端 AI 编程 Agent，不是简单的代码补全工具。它能理解整个代码库，根据自然语言指令自主规划步骤、编辑文件、运行命令、执行测试、管理 Git，像一个真正的协作者一样生活在你的终端里。
一、安装
前置条件
| 系统 | 要求 |
|---|---|
| macOS | 10.15+ |
| Linux | Ubuntu 20.04+ / Debian 10+ |
| Windows | 需通过 WSL2 |
安装步骤
bash
# 1. 确保 Node.js ≥ 18
node --version
# 2. 全局安装（不要用 sudo！）
npm install -g @anthropic-ai/claude-code
# 3. 验证安装
claude --version不要用
sudo npm install -g，会导致权限问题。如果碰到 EACCES 错误：bashnpm config set prefix '~/.npm-global' export PATH=~/.npm-global/bin:$PATH
首次认证
bash
claude # 首次运行会引导你完成 OAuth 认证支持四种认证方式：
| 方式 | 适用场景 |
|---|---|
| Anthropic Console（默认） | 在 console.anthropic.com 开通计费，OAuth 登录 |
| Claude Pro/Max 订阅 | 使用 claude.ai 账户统一订阅 |
| API Key | export ANTHROPIC_API_KEY=your-key |
| 企业平台 | Amazon Bedrock / Google Vertex AI |
二、三种交互模式
Claude Code 支持三种运行模式，覆盖从"快速问答"到"深度协作"的完整场景：
2.1 打印模式（Print Mode）—— 一次性问答
bash
# 最简用法
claude -p "解释这个错误：Segmentation fault (core dumped)"
# 管道输入
cat error.log | claude -p "分析这些错误日志"
# JSON 输出（适合脚本集成）
claude -p "生成一个 Node.js Express 脚手架" --output-format json
# 流式 JSON
claude -p "重构 utils.js" --output-format stream-json打印模式的特点是执行完即退出，不进入交互式终端，非常适合脚本自动化和 CI/CD 流水线。
2.2 交互模式（Interactive Mode）—— 日常开发主场
bash
claude # 当前目录启动
claude /path/to/project # 指定项目目录
claude --resume # 恢复上一次对话
claude -r <会话ID> # 恢复特定历史会话
claude "请帮我梳理项目结构" # 带初始提示词启动2.3 计划模式（Plan Mode）—— 零风险探索
按 Shift + Tab 切换到计划模式。此模式下 Claude 只分析和规划，不会执行任何修改操作。推荐在以下场景使用：
- 初次接触陌生项目，先让 Claude 梳理结构
- 复杂的重构方案，先让 Claude 出计划、你审阅后再执行
- 不确定改动范围时，先摸底
三、键盘快捷键
随时按
Ctrl + Shift + ?查看完整快捷键列表。
| 分类 | 快捷键 | 功能 |
|---|---|---|
| 会话 | Enter | 发送消息 |
| 会话 | Esc | 中断当前生成 |
| 会话 | Ctrl + C | 打开功能菜单 |
| 会话 | Ctrl + D | 退出 Claude Code |
| 模式 | Shift + Tab | 循环切换权限模式（普通→自动接受→计划） |
| 模式 | Shift + F | 打开模型选择器 |
| 模式 | Shift + T | 切换"扩展思考"(Extended Thinking) |
| 编辑 | Ctrl + R | 搜索历史命令 |
| 编辑 | Ctrl + L | 切换工具列表/清屏 |
| 编辑 | Ctrl + K | 删除光标后所有内容 |
| 编辑 | ↑ / ↓ | 浏览历史输入 |
| 编辑 | Tab | 自动补全/切换选项 |
| 编辑 | Ctrl + A / Ctrl + E | 光标到行首/行尾 |
| 工具 | Ctrl + J | 粘贴图片 |
| 工具 | Ctrl + * | 切换侧边面板 |
| 工具 | Ctrl + O | 查看 Claude 的思考过程 |
| 回溯 | Esc Esc | 打开回溯菜单（还原对话/代码） |
四、斜杠命令速查
斜杠命令是交互模式下最高频的操作入口。输入 / 即可看到自动补全列表。
会话控制
| 命令 | 功能 |
|---|---|
/clear | 清空当前对话历史 |
/compact [说明] | 压缩对话历史以节省 Token |
/resume | 恢复上次中断的对话 |
/reset [说明] | 回退到上一个锚点 |
/cost | 显示 Token 消耗和费用估算 |
/context | 查看当前上下文占用 |
/model | 切换 AI 模型（Sonnet/Opus/Haiku） |
/exit 或 /quit | 退出 |
项目与配置
| 命令 | 功能 |
|---|---|
/init | 创建项目 CLAUDE.md 记忆文件（新项目首选） |
/memory | 查看和编辑 CLAUDE.md 项目记忆 |
/config | 打开设置面板 |
/permissions | 查看和更新工具权限 |
/terminal-setup | 配置终端行为（如 Shift+Enter 换行） |
/vim | 切换 Vim 键位模式 |
/keyboardshortcuts | 查看/编辑快捷键 |
代码与分析
| 命令 | 功能 |
|---|---|
/review | 对代码进行审查分析 |
/pr_comments | 查看 GitHub PR 反馈 |
/doctor | 运行环境检测与健康检查 |
/bug | 引导式报告 Bug |
扩展与集成
| 命令 | 功能 |
|---|---|
/agents | 管理子代理 |
/mcp | 管理 MCP 服务器 |
/hooks | 管理自动化钩子 |
/ide | 从外部终端连接到 IDE |
/install-github-app | 配置 GitHub 自动化 PR 审查 |
/help | 查看所有可用命令 |
五、CLAUDE.md —— 项目记忆
CLAUDE.md 是 Claude Code 最核心的概念之一。它是项目的"记忆文件"，Claude 在每次会话中自动读取，用于理解项目架构、编码规范和常用命令。
两种类型
| 文件路径 | 作用域 |
|---|---|
./CLAUDE.md（项目根目录） | 项目级记忆，建议纳入 Git |
~/.claude/CLAUDE.md | 个人全局记忆，对所有项目生效 |
创建与使用
bash
# 方法一：在 Claude Code 中运行
claude # 进入项目目录后启动
/init # 让 Claude 分析项目并生成 CLAUDE.md
# 方法二：手动编写
vim CLAUDE.md推荐内容结构
markdown
# 项目上下文
## 架构概览
- 前端: React + TypeScript
- 后端: Node.js + Express
- 数据库: PostgreSQL + Prisma
## 开发命令
- npm install # 安装依赖
- npm run dev # 启动开发服务器
- npm test # 运行测试
- npm run lint # 代码检查
## 编码规范
- 使用 ESLint + Prettier
- 遵循 conventional commits
- 组件使用函数式 + Hooks
## 重要约定
- API 路由统一加 /api/v1 前缀
- 错误处理必须返回标准格式 { code, message, data }CLAUDE.md 越长越好吗？不是。精炼、准确比全面更重要。优先写 Claude 容易误判的内容（特殊命名约定、非标准目录结构、独有的命令），通用知识不用写。
六、配置文件与权限管理
配置文件层级（优先级从高到低）
配置命令
bash
config list # 显示所有生效配置
config get <key> # 读取某配置项
config set <key> <value> # 修改某配置项
config add <key> <value> # 向列表追加值
config remove <key> <value> # 从列表删除值权限管理
Claude Code 的权限模型让你精确控制它能做什么、不能做什么：
json
// .claude/settings.json
{
"permissions": {
"allow": [
"Bash(npm run lint)",
"Bash(npm run test:*)", // 通配符匹配
"Read(~/.zshrc)",
"Write(src/**)"
],
"deny": [
"Bash(curl:*)", // 禁止网络请求
"Bash(rm -rf:*)", // 禁止危险删除
"Write(/etc/*)" // 禁止操作系统文件
]
}
}也可以在交互式终端中用 /permissions 命令进行可视化配置。
七、权限模式（Permission Modes）
三种模式用于不同的工作阶段，通过 Shift + Tab 快速切换：
| 模式 | 行为 | 适用场景 |
|---|---|---|
| 普通模式 | 执行操作前请求确认 | 日常开发，安全可控 |
| 自动接受 | 直接执行，无需确认 | 充分信任的操作（如已配 allow 列表） |
| 计划模式 | 只规划不执行 | 理解陌生项目、评审方案、零风险探索 |
推荐工作流：先计划模式让 Claude 分析 → 审阅方案 → 切换到普通/自动接受模式执行。
八、内置工具（Tools）
Claude Code 通过以下内置工具与你的环境交互：
| 工具 | 能力 |
|---|---|
| Read | 读取文件内容 |
| Write | 创建/编辑文件 |
| Edit | 精确替换文件中的代码片段 |
| Bash | 执行 Shell 命令（npm、git、make 等） |
| Glob | 按模式搜索文件名 |
| Grep | 在代码中搜索文本/正则 |
| Task | 启动子代理处理复杂多步骤任务 |
| WebFetch | 获取网页内容 |
| WebSearch | 网络搜索 |
九、钩子（Hooks）—— 事件驱动自动化
钩子让你在 Claude Code 的关键行为节点插入自动化脚本，实现 Lint 校验、格式化、自动提交等。
可用事件
| 事件 | 触发时机 |
|---|---|
PreToolUse | 工具使用前（可做校验、阻止） |
PostToolUse | 工具调用成功后（可做格式化、自动 commit） |
Notification | 发送通知时 |
SessionStart | 会话开始时 |
SessionEnd | 会话正常结束时 |
PreCompact | 执行 /compact 压缩前 |
Stop | 停止响应前 |
配置示例
json
{
"hooks": {
"PostToolUse": [{
"matcher": "Write",
"hooks": [{
"type": "command",
"command": "npx prettier --write $CLAUDE_TOOL_INPUT"
}]
}],
"PreToolUse": [{
"matcher": "Bash(git commit:*)",
"hooks": [{
"type": "command",
"command": "npm run lint && npm test"
}]
}]
}
}十、MCP（模型上下文协议）
MCP 让 Claude Code 连接外部工具和数据源——数据库、API、文件系统等。
添加 MCP 服务器
bash
# 本地命令行服务器
claude mcp add my-tool -e API_KEY=xxx -- /path/to/server arg1
# HTTP/SSE 服务器
claude mcp add --transport sse my-api https://api.example.com/mcp
# 项目级（团队共享，存入 .mcp.json）
claude mcp add --scope project db-tool -- /path/to/db-server三个作用域
| 作用域 | 存储位置 | 可见范围 |
|---|---|---|
local（默认） | 仅当前项目、当前用户 | 个人 |
project | .mcp.json，纳入 Git | 团队共享 |
user | 全局配置 | 所有项目通用 |
推荐搭配：CodeGraph 是最常用的 Claude Code MCP 扩展之一——给代码库预构建语义知识图谱，让 Agent 探索代码时工具调用 ↓88%、Token ↓62%。详见 CodeGraph 完整教程。
十一、Agent（子代理）与 Skill（技能）
本章是快速参考。深入概念辨析、三向对比、决策树、协同模式，见 Agent 与 Skill 深度解析。
11.1 概念全景
11.2 Agent（子代理 / Subagent）—— "派一个人去干活"
本质：一个被 Claude Code 主会话委派出去的独立 AI，拥有自己的上下文窗口、自己的工具权限、自己的模型选择。
核心特征：
| 特征 | 说明 |
|---|---|
| 上下文隔离 | 过程的文件读取、推理完全不进入主对话 |
| 独立工具权限 | 可限制只给 Read/Grep/Glob，不给 Write/Edit |
| 独立模型 | 探索任务用便宜的 Haiku，深度分析用 Sonnet |
| 并行执行 | 多个 Agent 可同时运行（最多 5 层嵌套） |
| 自动委派 | Claude 根据 description 自动判断 |
创建 Agent：在 .claude/agents/ 下创建 .md 文件：
yaml
---
name: code-reviewer
description: "审查代码质量、安全性和最佳实践。当用户要求 review、audit 或检查代码质量时调用。"
tools: Read, Grep, Glob
disallowedTools: Write, Edit
model: sonnet
maxTurns: 50
---
你是一个资深代码审查专家。分析代码并提供可执行的反馈。
## 审查清单
1. 安全性：SQL 注入、XSS、硬编码密钥
2. 性能：N+1 查询、循环内大对象创建
3. 可维护性：方法不超过 30 行、命名自解释
## 输出格式
按 Critical / Major / Minor 三级组织，每项附带具体代码位置和修复建议。内置 Agent（无需创建，开箱即用）：
| Agent | 模型 | 工具 | 用途 |
|---|---|---|---|
| Explore | Haiku | 只读 | 快速搜索、探索代码库结构 |
| Plan | 继承主对话 | 只读 | 复杂任务规划、方案研究 |
| general-purpose | 继承主对话 | 全部 | 复杂多步任务 |
11.3 Skill（技能）—— "给一本操作手册"
本质：一个 Markdown 文件（SKILL.md），描述某类任务怎么做。采用渐进式披露机制。
创建 Skill：在 .claude/skills/<name>/ 下创建 SKILL.md：
yaml
---
name: code-review
description: "按团队规范执行 Code Review。触发词：review、审查、audit。"
argument-hint: "[file-or-pr]"
allowed-tools: Read, Grep, Glob, Bash(git *)
model: sonnet
---
## Code Review 清单
### 1. 安全检查
- SQL 注入风险、XSS 风险、硬编码密钥
### 2. 性能检查
- N+1 查询、循环内大对象创建、不必要的深拷贝
### 3. 可读性
- 方法不超过 30 行、变量命名自解释、复杂条件提取为命名布尔变量
$ARGUMENTS 指定要 review 的文件或 PR。Skill 关键 frontmatter 字段：
| 字段 | 作用 |
|---|---|
description | 最重要——Claude 靠它自动判断是否加载此 Skill |
context: fork | 在隔离的子代理中运行（类似 Agent 的效果） |
disable-model-invocation: true | 只能用户手动调用，Claude 不会自动匹配 |
model: haiku | 用更便宜的模型执行此 Skill |
allowed-tools | 限制此 Skill 可用的工具 |
十二、IDE 集成
| IDE | 方式 |
|---|---|
| VS Code | 安装 "Claude Code" 扩展，在集成终端运行 claude |
| JetBrains | 安装插件，在终端运行或 /ide 连接 |
| Cursor / Windsurf | 同 VS Code |
| 外部终端 | 运行 claude 后 /ide 连接 IDE |
VS Code 快捷键：Cmd+Option+K (Mac) / Alt+Ctrl+K (Linux/Windows) 快速引用文件。
十三、实战工作流
工作流 1：新项目初始化
bash
cd my-new-project
claude # 启动
/init # 让 Claude 分析并生成 CLAUDE.md
# 然后说："帮我搭建一个 Express + TypeScript 的项目脚手架"工作流 2：理解陌生项目
bash
cd unknown-project
claude
Shift+Tab # 切到计划模式
# 说："梳理项目结构，画一张模块依赖图"
# 审阅输出后 → Shift+Tab 切回普通模式继续开发工作流 3：Bug 修复
bash
claude -p "分析这个错误并给出修复方案：$(cat error.log)"
# 或直接粘贴
claude
# "这个函数在处理空数组时 crash 了，帮我修复：function process(arr) { return arr[0].name; }"工作流 4：代码审查
bash
git diff main | claude -p "review this PR diff, focus on security and performance"工作流 5：CI/CD 集成
bash
npm test 2>&1 | claude -p "修复这些失败的测试"十四、输入技巧
| 技巧 | 说明 |
|---|---|
@文件名 或 #文件名 | 直接引用文件内容 |
| 粘贴图片 | 截图、原型图可直接粘贴到终端 |
| 拖拽文件 | CSV / JSON / 代码文件直接拖入 |
| 管道输入 | cat error.log | claude -p "分析这些错误" |
@目录/ | 引用整个目录 |
@postgres:users_table | 引用 MCP 资源 |
十五、故障排除
| 问题 | 解决方案 |
|---|---|
| 权限错误 (EACCES) | 不要用 sudo；设 npm config set prefix '~/.npm-global' |
| 认证过期 | rm -rf ~/.claude/auth 然后重新 claude |
| 大项目慢 | 创建 .claudeignore 排除 node_modules、dist 等 |
| 重复请求确认 | 用 /permissions 配置 allow 列表 |
| 代理环境 | export HTTPS_PROXY='https://proxy:8080' |
.claudeignore 示例
node_modules/
dist/
build/
.git/
*.log
coverage/十六、文件结构速查
项目根目录/
├── CLAUDE.md # 项目记忆文件（建议纳入 Git）
├── .claude/
│ ├── settings.json # 项目级配置（团队共享）
│ ├── settings.local.json # 个人本地配置（Git 忽略）
│ ├── commands/ # 自定义斜杠命令（.md 文件）
│ ├── agents/ # 项目子代理（.md 文件，YAML frontmatter + Markdown）
│ │ └── code-reviewer.md
│ └── skills/ # 项目技能（目录 + SKILL.md）
│ └── code-review/
│ └── SKILL.md
└── .mcp.json # 项目级 MCP 服务器配置（团队共享）
全局 (~/.claude/)
├── CLAUDE.md # 个人全局记忆
├── settings.json # 用户全局设置
├── commands/ # 全局自定义命令
├── agents/ # 全局子代理（所有项目可用）
├── skills/ # 全局技能（所有项目可用）
└── keystroke.json # 自定义快捷键一句话总结
Claude Code 是一个住在终端里的 AI 协作者：用
/init让他了解你的项目，用自然语言下指令，通过权限系统控制他能做什么——它不是替代你的工具，而是放大你能力的杠杆。
延伸阅读
- AI 编程工具总纲 —— 工具选型、四级演化、场景矩阵
- Agent 与 Skill 深度解析 —— 概念辨析、三向对比、决策树、协同模式
- CodeGraph 完整教程 —— 本地代码知识图谱，与 Claude Code 协作
- Anthropic 官方文档