Claude Code 中文操作手册
完整的 Claude Code 使用指南，涵盖安装、配置、核心功能和高级技巧
目录
- [快速入门](#快速入门)
- [安装与配置](#安装与配置)
- [交互模式详解](#交互模式详解)
- [键盘快捷键完整列表](#键盘快捷键完整列表)
- [三种模式详解](#三种模式详解)
- [Plan 模式使用指南](#plan-模式使用指南)
- [斜杠命令大全](#斜杠命令大全)
- [Vim 编辑模式](#vim-编辑模式)
- [常见问题与故障排除](#常见问题与故障排除)
- [最佳实践](#最佳实践)
快速入门
什么是 Claude Code？
Claude Code 是 Anthropic 官方推出的 AI 编程助手，通过命令行界面与你交互，帮助你：
- 编写和修改代码
- 搜索和理解代码库
- 调试和修复问题
- 执行 bash 命令
- 规划复杂功能的实现
核心特性
- 智能对话: 自然语言交互，无需记忆复杂命令
- 代码库理解: 自动分析项目结构和代码
- 安全操作: 需要你确认后才执行重要操作
- 多模式切换: 支持 Plan 模式、自动接受模式等
- Vim 支持: 内置 Vim 编辑模式
- 扩展性: 支持自定义技能、MCP 服务器等
安装与配置
系统要求
- Node.js: 18.0 或更高版本（如果使用 npm 安装）
- 操作系统: Windows、macOS、Linux
- 内存: 建议 4GB 以上
- 网络: 需要互联网连接
安装方法
方法一：原生安装（推荐）
macOS、Linux、WSL:
# 安装稳定版本（默认）curl -fsSL https://claude.ai/install.sh | bash# 安装最新版本curl -fsSL https://claude.ai/install.sh | bash -s latest# 安装特定版本curl -fsSL https://claude.ai/install.sh | bash -s 2.0.70Windows PowerShell:
# 安装稳定版本（默认）irm https://claude.ai/install.ps1 | iex# 安装最新版本& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) latest# 安装特定版本& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 2.0.70方法二：npm安装
npm install -g @anthropic-ai/claude-code验证安装
# 检查安装状态claude doctor# 启动 Claude Codeclaude首次启动与认证
- 运行 claude 命令
- 按照提示完成认证（会打开浏览器）
- 授权成功后即可使用
交互模式详解
Claude Code 启动后进入交互模式，这是主要的使用界面。
基本操作
- 输入消息: 直接输入文字与 Claude 对话
- 多行输入: 使用 `\` + `Enter` 或 `Shift+Enter`（部分终端）
- 取消操作: 按 `Ctrl+C`
- 退出程序: 按 `Ctrl+D`
输入模式
1. 普通对话模式
直接输入你的问题或需求：
帮我看一下这个函数有什么问题2. Bash 模式（使用`!` 前缀）
直接执行 bash 命令：
! git status! npm install特点:
- 命令和输出都会添加到对话上下文
- 支持后台运行（Ctrl+B）
- 不需要 Claude 解析或批准
3. 文件提及（使用`@`）
提及特定文件：
请帮我分析 @src/components/Header.tsx 这个文件输入 @ 后会触发文件路径自动补全。
历史记录
- 上下箭头: 浏览之前的命令
- Ctrl+R: 反向搜索历史记录
- /clear: 清除当前会话历史
键盘快捷键完整列表
通用控制
快捷键 | 功能 | 说明 |
Ctrl+C | 取消当前输入或生成 | 标准中断信号 |
Ctrl+D | 退出 Claude Code | EOF 信号 |
Ctrl+L | 清屏 | 保留对话历史 |
Ctrl+O | 切换详细输出 | 显示详细的工具使用和执行信息 |
Ctrl+R | 反向搜索历史 | 交互式搜索之前的命令 |
Ctrl+V (macOS)<br>Alt+V (Windows) | 粘贴剪贴板图片 | 粘贴图片或图片文件路径 |
Ctrl+B | 后台运行任务 | 后台运行 bash 命令和代理（Tmux 用户需按两次） |
Esc + Esc | 回退代码/对话 | 将代码和/或对话恢复到之前的状态 |
| `Shift+Tab` | 切换权限模式 | 在三种模式间循环切换 |
| Alt+M | 切换权限模式（部分配置）| Windows 备用快捷键 |
| Option+P (macOS)<br>Alt+P (Windows/Linux) | 切换模型 | 在不清除提示的情况下切换模型 |
| Option+T (macOS)<br>Alt+T (Windows/Linux) | 切换扩展思考 | 启用/禁用扩展思考模式（需先运行 /terminal-setup） |
文本编辑
快捷键 | 功能 | 说明 |
Ctrl+K | 删除到行尾 | 删除的文本可粘贴 |
Ctrl+U | 删除整行 | 删除的文本可粘贴 |
Ctrl+Y | 粘贴删除的文本 | 粘贴用 Ctrl+K 或 Ctrl+U 删除的文本 |
Alt+Y | 循环粘贴历史 | 在粘贴后循环浏览之前删除的文本（macOS 需 Option 作为 Meta） |
Alt+B | 光标后移一个单词 | 单词导航（macOS 需 Option 作为 Meta） |
Alt+F | 光标前移一个单词 | 单词导航（macOS 需 Option 作为 Meta） |
多行输入
方法 | 快捷键 | 适用环境 |
快速转义 | \ + Enter | 所有终端 |
macOS 默认 | Option+Enter | macOS |
Shift+Enter | Shift+Enter | iTerm2、WezTerm、Ghostty、Kitty |
控制序列 | Ctrl+J | 多行换行符 |
粘贴模式 | 直接粘贴 | 代码块、日志 |
快速命令
前缀 | 功能 | 说明 |
/ | 斜杠命令 | 见斜杠命令章节 |
! | Bash 模式 | 直接运行 shell 命令 |
@ | 文件路径提及 | 触发文件路径自动补全 |
三种模式详解
Claude Code 有三种权限模式，通过 **`Shift+Tab`** 循环切换：
1. 普通模式（Normal Mode）- ⚠️ 需要确认
特点:
- 每个操作都需要你手动确认
- 最安全的模式
- 适合学习 Claude Code 的功能
适用场景:
- 不确定 Claude 会做什么操作时
- 需要审查每个修改时
- 学习阶段
2. 自动接受模式（Auto-Accept Mode）- ✅ 自动执行
特点:
- Claude 自动执行所有操作
- 不需要确认
- 提高工作效率
适用场景:
- 信任 Claude 的判断
- 简单重复的任务
- 已经熟悉项目结构
⚠️ 注意:
- 使用 /permissions 命令可以精细控制哪些工具可以自动运行
3. Plan 模式（Plan Mode）- 仅读取
特点:
- Claude 只有 Read 工具权限
- 无法修改文件、运行命令等
- 专注于规划和分析
适用场景:
- 实现功能前的规划阶段
- 理解代码库结构
- 讨论技术方案
工作流程:
- 在 Plan 模式下讨论需求
- Claude 分析代码并提出方案
- 你确认理解方案后
- 切换到普通模式开始编码
Plan 模式使用指南
为什么 Plan 模式最重要？
Plan 模式是 Claude Code 最重要的功能——在编写任何代码之前必须使用。
很多人让 Claude 直接写代码，结果产生难以维护的混乱代码，最终不得不重做。这样的例子太多了。
如何启用 Plan 模式
- macOS: `Shift + Tab`（按两次）
- Windows: `Alt + M`（但有 bug，建议用 `Shift+Tab`）
正确的工作流程
第一步：清晰描述需求
不要只说"帮我写一个注册功能"，要具体：
- 需要邮箱验证吗？
- 密码要求是什么？
- 需要第三方登录支持吗？
第二步：讨论解决方案
让 Claude 提出实现方案，并持续追问：
- 为什么选择这个技术栈？
- 还有其他选择吗？
- 可能会遇到什么问题？
第三步：确认理解
只有当你完全理解方案后，才退出 Plan 模式开始编码。
惨痛教训
我之前犯过这个错误——不懂装懂，接受 Claude 说的任何东西。结果是一堆完全看不懂的代码，出问题时完全不知道如何修复。
后来我学聪明了，在 Plan 模式下对所有不懂的问题进行提问，让 Claude 用生活实例解释，直到我完全理解。
记住一个原则：你必须清楚地理解 AI 要做什么，否则最终会得到一堆无法维护的垃圾代码。
实际例子
比如要构建用户注册功能，Plan 模式下的对话应该像这样：
你: 我想构建带邮箱验证的用户注册AI: 好的，我建议这样实现...你: 为什么选择 JWT 而不是 Session？AI: 因为你的应用是前后端分离的...你: 如何存储邮箱验证码？有效期多久？AI: 我推荐使用 Redis 存储，10 分钟过期...这看起来更慢，但实际上节省了大量返工时间。而且你对整个系统的理解会非常深刻，后期维护也更容易。
斜杠命令大全
斜杠命令让你可以快速执行特定操作。
基本命令
命令 | 功能 | 示例 |
/help | 显示帮助信息 | 查看所有可用命令 |
/clear | 清除对话历史 | 清空当前会话 |
/exit 或 /quit | 退出 Claude Code | 关闭程序 |
/compact | 压缩上下文 | 减少对话历史以节省 token |
配置命令
命令 | 功能 | 说明 |
/config | 打开配置编辑 | 修改用户设置 |
/settings | 查看当前设置 | 显示配置信息 |
/theme | 更换主题 | 选择代码高亮主题 |
/vim | 切换 Vim 模式 | 启用/禁用 Vim 编辑模式 |
/permissions | 权限管理 | 配置自动接受的工具 |
模型相关
命令 | 功能 | 说明 |
/model | 查看当前模型 | 显示正在使用的模型 |
/switch-model | 切换模型 | 切换到其他 AI 模型 |
开发命令
命令 | 功能 | 说明 |
/git | Git 操作 | 快速 Git 命令 |
/test | 运行测试 | 执行项目测试 |
/build | 构建项目 | 运行构建脚本 |
/run | 运行项目 | 启动开发服务器 |
技能和代理
命令 | 功能 | 说明 |
/skills | 管理技能 | 查看、安装、管理技能 |
/agents | 管理代理 | 配置自定义代理 |
/terminal-setup | 终端设置 | 配置终端快捷键和功能 |
诊断和帮助
命令 | 功能 | 说明 |
/doctor | 健康检查 | 检查安装和配置状态 |
/bug | 报告问题 | 向 Anthropic 提交 bug 报告 |
/logout | 退出登录 | 清除认证信息 |
记忆和上下文
命令 | 功能 | 说明 |
/memory | 查看项目记忆 | 显示 CLAUDE.md 内容 |
/save | 保存对话 | 保存当前对话到文件 |
Vim 编辑模式
Claude Code 内置完整的 Vim 编辑模式，适合 Vim 用户。
启用 Vim 模式
临时启用:
/vim永久启用:
/config在配置文件中设置 vim: true
模式切换
命令 | 功能 | 从模式 |
Esc | 进入 NORMAL 模式 | INSERT |
i | 在光标前插入 | NORMAL |
I | 在行首插入 | NORMAL |
a | 在光标后插入 | NORMAL |
A | 在行尾插入 | NORMAL |
o | 在下方新行插入 | NORMAL |
O | 在上方新行插入 | NORMAL |
导航（NORMAL 模式）
命令 | 功能 |
h/j/k/l | 左/下/上/右移动 |
w | 下一个单词 |
e | 单词末尾 |
b | 上一个单词 |
0 | 行首 |
$ | 行尾 |
^ | 第一个非空字符 |
gg | 输入开头 |
G | 输入末尾 |
f{char} | 跳转到下一个字符出现处 |
F{char} | 跳转到上一个字符出现处 |
t{char} | 跳转到下一个字符前 |
T{char} | 跳转到上一个字符后 |
; | 重复上次 f/F/t/T |
, | 反向重复上次 f/F/t/T |
编辑（NORMAL 模式）
命令 | 功能 |
x | 删除字符 |
dd | 删除行 |
D | 删除到行尾 |
dw/de/db | 删除单词/到末尾/到开头 |
cc | 修改行 |
C | 修改到行尾 |
cw/ce/cb | 修改单词/到末尾/到开头 |
yy/Y | 复制行 |
yw/ye/yb | 复制单词/到末尾/到开头 |
p | 在光标后粘贴 |
P | 在光标前粘贴 |
>> | 增加缩进 |
<< | 减少缩进 |
J | 合并行 |
. | 重复上次修改 |
文本对象（NORMAL 模式）
文本对象可与 d、c、y 等操作符结合：
命令 | 功能 |
iw/aw | 内部/周围单词 |
iW/aW | 内部/周围 WORD（空格分隔） |
i"/a" | 内部/周围双引号 |
i'/a' | 内部/周围单引号 |
i(/a( | 内部/周围圆括号 |
i[/a[ | 内部/周围方括号 |
i{/a{ | 内部/周围花括号 |
使用示例:
- ci" - 修改引号内的内容
- da{ - 删除花括号及其内容
- yiw - 复制一个单词
常见问题与故障排除
Windows 安装问题
问题：WSL 中的错误
OS/平台检测问题:
# 安装前运行npm config set os linux# 然后安装npm install -g @anthropic-ai/claude-code --force --no-os-check找不到 Node 错误:
# 检查 node 和 npm 路径which npmwhich node# 应该指向 Linux 路径（/usr/开头），而不是 Windows 路径（/mnt/c/开头）问题：需要 Git Bash
错误信息: "Claude Code on Windows requires git-bash"
解决方案:
- 安装 Git for Windows（包含 Git Bash）
- 如果未检测到，在 PowerShell 中设置路径：
$env:CLAUDE_CODE_GIT_BASH_PATH="C:\Program Files\Git\bin\bash.exe"- 或添加到系统环境变量
权限和认证问题
反复提示权限
使用 /permissions 命令配置自动接受特定工具。
认证问题
# 完全退出/logout# 删除认证信息rm -rf ~/.config/claude-code/auth.json# 重新启动claude性能和稳定性
CPU 或内存占用高
- 定期使用 /compact 压缩上下文
- 重大任务之间重启 Claude Code
- 将大型构建目录添加到 .gitignore
命令挂起或冻结
- 按 Ctrl+C 尝试取消
- 无响应时关闭终端并重启
搜索和发现问题
搜索工具不工作
安装系统 ripgrep:
macOS (Homebrew):
brew install ripgrepWindows (winget):
winget install BurntSushi.ripgrep.MSVCUbuntu/Debian:
sudo apt install ripgrep然后设置环境变量：
export USE_BUILTIN_RIPGREP=0WSL 搜索结果慢或不完整
解决方案:
- 提交更具体的搜索（指定目录或文件类型）
- 将项目移到 Linux 文件系统（/home/）而非 Windows 文件系统（/mnt/c/）
- 使用原生 Windows 而非 WSL
IDE 集成问题
JetBrains IDE 未检测到（WSL2）
问题: WSL2 的 NAT 网络或防火墙阻止连接
方案 1: 配置 Windows 防火墙（推荐）
# 1. 获取 WSL2 IP 地址wsl hostname -I# 2. 在 PowerShell（管理员）中创建防火墙规则New-NetFirewallRule -DisplayName "Allow WSL2 Internal Traffic" -Direction Inbound -Protocol TCP -Action Allow -RemoteAddress 172.21.0.0/16 -LocalAddress 172.21.0.0/16# 3. 重启 IDE 和 Claude Code方案 2: 切换到镜像网络
在用户目录的 .wslconfig 中添加：
[wsl2]networkingMode=mirrored然后重启 WSL：
wsl --shutdownJetBrains 终端中 Esc 键不工作
问题: JetBrains 快捷键冲突
解决方案:
- 设置 → 工具 → 终端
- 取消勾选"使用 Escape 将焦点移至编辑器"
- 或点击"配置终端键绑定"并删除"将焦点切换到编辑器"快捷键
Markdown 格式问题
代码块缺少语言标签
问题:
```function example() { return "hello";}```解决方案:
- 要求 Claude 添加语言标签
- 设置后处理钩子自动添加
- 手动验证并修正
配置文件位置
文件 | 用途 |
~/.claude/settings.json | 用户设置（权限、钩子、模型覆盖） |
.claude/settings.json | 项目设置（提交到源码管理） |
.claude/settings.local.json | 本地项目设置（不提交） |
~/.claude.json | 全局状态（主题、OAuth、MCP 服务器） |
.mcp.json | 项目 MCP 服务器 |
**Windows 上 `~` 指向用户主目录，如 `C:\Users\你的名字`**
重置配置
# 重置所有用户设置rm ~/.claude.jsonrm -rf ~/.claude/# 重置项目设置rm -rf .claude/rm .mcp.json最佳实践
1. 始终使用 Plan 模式规划
在写代码之前，先在 Plan 模式下：
- 讨论需求
- 理解技术方案
- 确认实现细节
2. 定期压缩上下文
使用 /compact 命令定期清理对话历史，保持响应速度。
3. 利用项目记忆
在项目根目录创建 CLAUDE.md 文件，记录：
- 项目架构
- 编码规范
- 重要约定
- 常用命令
4. 精细化权限控制
使用 /permissions 配置：
- 哪些工具可以自动运行
- 哪些需要确认
- 减少重复提示
5. 善用斜杠命令
- /vim - 启用 Vim 模式提高编辑效率
- /theme - 选择舒适的代码主题
- /doctor - 定期检查健康状态
6. 模式切换技巧
- 学习阶段: 使用普通模式，了解每个操作
- 简单任务: 切换到自动接受模式
- 规划阶段: 始终使用 Plan 模式
7. 上下文管理
- 重要任务完成后重启 Claude Code
- 大型项目定期使用 /compact
- 将构建产物添加到 .gitignore
8. 快捷键熟练度
重点掌握：
- Shift+Tab - 模式切换
- Ctrl+R - 历史搜索
- Ctrl+L - 清屏
- Ctrl+B - 后台任务
- Esc + Esc - 回退操作
9. 文件提及技巧
使用 @ 提及特定文件：
分析 @src/utils/auth.ts 的安全性10. Bash 模式使用
对于快速 shell 操作：
! git status! npm run test11. 错误处理
遇到问题时：
- 使用 /doctor 检查状态
- 查看 Troubleshooting 文档
- 使用 /bug 报告问题
12. 保持更新
# 检查更新claude doctor# 重新安装最新版本curl -fsSL https://claude.ai/install.sh | bash -s latest附录
环境变量
变量 | 功能 |
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS | 禁用后台任务（设为 1） |
USE_BUILTIN_RIPGREP | 使用内置 ripgrep（设为 0 使用系统版本） |
CLAUDE_CODE_GIT_BASH_PATH | Windows Git Bash 路径 |
有用的链接
- 官方文档: https://code.claude.com/docs
- GitHub 仓库: https://github.com/anthropics/claude-code
- 问题反馈: https://github.com/anthropics/claude-code/issues
- 中文教程: https://www.claudecode101.com
版本历史
查看最新更新：
claude --version
