260216-Claude Code 快速入门指南及示例

Claude Code 完全使用指南

Claude Code 是 Anthropic 推出的智能编程 CLI 工具，能够阅读代码库、编辑文件、执行命令，并与开发工具深度集成。

一、安装
二、基本使用
三、斜杠命令
四、键盘快捷键
[五、CLI 参数与选项](#五、CLI 参数与选项)
六、配置体系
[七、CLAUDE.md 项目记忆](#七、CLAUDE.md 项目记忆)
八、权限管理
[九、MCP 服务器](#九、MCP 服务器)
[十、Hooks 钩子](#十、Hooks 钩子)
[十一、IDE 集成](#十一、IDE 集成)
十二、实战示例
十三、高级功能
十四、常见问题排查

一、安装

原生安装（推荐，支持自动更新）

bash 复制代码

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

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

# Windows CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

其他方式

bash 复制代码

# Homebrew (macOS)
brew install --cask claude-code

# WinGet (Windows)
winget install Anthropic.ClaudeCode

系统要求

项目	要求
操作系统	macOS 13.0+ / Windows 10 1809+ / Ubuntu 20.04+
内存	4GB 以上
网络	必须联网
Shell	Bash 或 Zsh 效果最佳

认证方式

个人用户：Claude Pro 或 Max 订阅，或 Anthropic API 密钥
团队/企业：Claude Teams / Enterprise，或 AWS Bedrock、Google Vertex AI

二、基本使用

启动方式

bash 复制代码

# 交互式会话
claude

# 带初始提示启动
claude "解释一下这个项目"

# 非交互模式（查询后退出）
claude -p "查找所有安全问题"

# 继续上一次会话
claude -c

# 恢复指定会话
claude -r "session-name"

工作循环

Claude Code 以三阶段循环工作：

收集上下文 → 读取文件、搜索代码、理解需求
执行操作 → 编辑文件、运行命令、创建提交
验证结果 → 运行测试、检查输出、迭代修正

你可以在任何时刻中断并调整方向。

快速上手

bash 复制代码

cd your-project
claude

复制代码

> 给我一个项目概览
> 解释一下主要架构
> 帮我修复 login 页面的 bug

三、斜杠命令

在 Claude Code 中输入 / 即可查看。主要命令：

命令	功能
`/help`	显示帮助信息
`/clear`	清除对话历史
`/compact [指示]`	压缩对话上下文，可指定保留重点
`/config`	打开设置界面
`/context`	可视化上下文窗口占用情况
`/cost`	显示 token 使用统计
`/debug [描述]`	调试当前会话
`/doctor`	检查安装健康状态
`/exit`	退出 Claude Code
`/export [文件名]`	导出对话到文件或剪贴板
`/init`	初始化项目，生成 CLAUDE.md
`/mcp`	管理 MCP 服务器连接
`/memory`	编辑 CLAUDE.md 记忆文件
`/model`	切换 AI 模型
`/permissions`	查看或修改权限
`/plan`	进入计划模式
`/rename <名称>`	重命名当前会话
`/resume [会话]`	恢复指定会话
`/rewind`	回退对话和/或代码变更
`/stats`	可视化每日使用统计
`/status`	显示版本、模型、账户信息
`/copy`	复制最近回复到剪贴板
`/tasks`	列出和管理后台任务
`/theme`	更改颜色主题
`/vim`	启用 vim 风格编辑
`/usage`	显示计划使用量和速率限制

四、键盘快捷键

通用操作

快捷键	功能
`Ctrl+C`	取消当前输入或生成
`Ctrl+D`	退出会话
`Ctrl+G`	在默认编辑器中打开提示词
`Ctrl+L`	清屏
`Ctrl+O`	切换详细输出
`Ctrl+R`	反向搜索命令历史
`Ctrl+V` / `Cmd+V`	粘贴图片（iTerm2）
`Ctrl+B`	后台运行任务
`Ctrl+T`	切换任务列表
`Shift+Tab` / `Alt+M`	切换权限模式
`Option+P` / `Alt+P`	切换模型
`Option+T` / `Alt+T`	切换扩展思考
`Esc` + `Esc`	回退或总结
`?`	显示可用快捷键

多行输入

方式	快捷键
快速换行	`\` + `Enter`
macOS 默认	`Option+Enter`
Shift+Enter	在 iTerm2/WezTerm/Ghostty/Kitty 中
控制序列	`Ctrl+J`

快捷前缀

前缀	功能
`/`	执行斜杠命令或技能
`!`	Bash 模式（直接执行 shell 命令）
`@`	引用文件路径

五、CLI 参数与选项

核心命令

bash 复制代码

claude                          # 启动交互式 REPL
claude "查询内容"                # 带初始提示启动
claude -p "查询内容"             # 非交互查询后退出
cat file | claude -p "查询"      # 管道输入
claude -c                       # 继续最近对话
claude -r "会话名" "查询"        # 恢复指定会话
claude update                   # 更新到最新版本
claude mcp                      # 配置 MCP 服务器

常用参数

参数	说明	示例
`--add-dir`	添加额外工作目录	`claude --add-dir ../apps ../lib`
`--model`	指定模型	`claude --model sonnet`
`--continue` / `-c`	继续最近对话	`claude -c`
`--resume` / `-r`	恢复指定会话	`claude -r auth-refactor`
`--print` / `-p`	非交互模式输出	`claude -p "查询"`
`--verbose`	详细日志	`claude --verbose`
`--version` / `-v`	显示版本号	`claude -v`
`--debug`	启用调试模式	`claude --debug "api,hooks"`
`--permission-mode`	指定权限模式	`claude --permission-mode plan`
`--tools`	限制可用工具	`claude --tools "Bash,Edit,Read"`
`--dangerously-skip-permissions`	跳过所有权限提示（慎用）	用于 CI/CD 自动化

系统提示词参数

参数	行为	适用模式
`--system-prompt`	替换默认系统提示	交互 + 非交互
`--system-prompt-file`	从文件替换系统提示	仅非交互
`--append-system-prompt`	追加到默认提示	交互 + 非交互
`--append-system-prompt-file`	从文件追加	仅非交互

六、配置体系

配置优先级（从高到低）

托管设置（系统级，IT 部署）
命令行参数
本地项目设置 .claude/settings.local.json
共享项目设置 .claude/settings.json
用户设置 ~/.claude/settings.json

配置文件

文件	位置	说明
用户设置	`~/.claude/settings.json`	个人全局配置，不提交到 git
项目共享设置	`.claude/settings.json`	团队共享，提交到 git
项目本地设置	`.claude/settings.local.json`	个人项目覆盖，自动 gitignore

配置示例

json 复制代码

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "claude-sonnet-4-5-20250929",
  "permissions": {
    "allow": ["Bash(npm run lint)", "Read(~/.zshrc)"],
    "deny": ["Bash(curl *)", "Read(./.env)"]
  },
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1"
  }
}

常用环境变量

变量	用途
`ANTHROPIC_API_KEY`	API 认证密钥
`ANTHROPIC_MODEL`	覆盖模型选择
`CLAUDE_CODE_MAX_OUTPUT_TOKENS`	Token 输出上限
`DISABLE_AUTOUPDATER`	禁用自动更新
`DISABLE_TELEMETRY`	关闭遥测

七、CLAUDE.md 项目记忆

CLAUDE.md 是会话启动时自动加载的指令文件，可以在不同层级创建：

层级	路径	用途
用户级	`~/.claude/CLAUDE.md`	所有项目通用
项目级	`CLAUDE.md` 或 `.claude/CLAUDE.md`	当前项目专用
本地级	`.claude/CLAUDE.local.md`	个人在当前项目的偏好

示例

markdown 复制代码

# 项目规范

## 技术栈
- React 18 + TypeScript
- Node.js 20+
- PostgreSQL 15

## 代码约定
- 使用函数式组件 + Hooks
- 组件命名使用 PascalCase
- Props 接口使用 I 前缀（如 IButtonProps）

## 测试
- Jest 单元测试
- Cypress E2E 测试
- 覆盖率目标 80%+

## 命令
- `npm run dev` --- 启动开发服务器
- `npm test` --- 运行测试
- `npm run lint` --- 代码检查

八、权限管理

权限规则语法

json 复制代码

{
  "permissions": {
    "allow": [
      "Bash",                      // 所有 bash 命令
      "Bash(npm run *)",           // npm run 开头的命令
      "Read(./.env)"               // 读取特定文件
    ],
    "deny": [
      "Bash(curl *)",              // 阻止 curl
      "Read(./secrets/**)"         // 阻止读取 secrets 目录
    ]
  }
}

权限模式

通过 Shift+Tab 快速切换：

默认模式：编辑和命令都需确认
自动接受编辑：跳过文件编辑确认
计划模式：只读分析，先出方案再执行

九、MCP 服务器

MCP（Model Context Protocol）是连接 Claude Code 与外部工具的开放标准。

安装 MCP 服务器

bash 复制代码

# 远程 HTTP 服务器（推荐）
claude mcp add --transport http notion https://mcp.notion.com/mcp

# 带认证的服务器
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

# 本地 stdio 服务器
claude mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable \
  -- npx -y airtable-mcp-server

管理命令

bash 复制代码

claude mcp list              # 列出所有已配置服务器
claude mcp get github        # 查看特定服务器详情
claude mcp remove github     # 移除服务器

在会话中使用 /mcp 检查连接状态。

安装作用域

作用域	说明
Local（默认）	仅当前项目，存在 `~/.claude.json`
Project	团队共享，通过 `.mcp.json` 提交到 git
User	所有项目可用

常用 MCP 服务器

GitHub --- PR 审查、Issue 管理
Sentry --- 生产错误监控
Slack --- 读写消息
Notion --- 访问 Notion 数据库
PostgreSQL --- 数据库查询

十、Hooks 钩子

Hooks 在 Claude Code 生命周期的特定时刻自动执行 shell 命令。

钩子事件

事件	触发时机	典型用途
`SessionStart`	会话启动/恢复	注入上下文、环境初始化
`UserPromptSubmit`	提交提示词时	验证提示内容
`PreToolUse`	工具调用前	验证/阻止命令
`PostToolUse`	工具调用成功后	自动格式化、运行 linter
`PostToolUseFailure`	工具调用失败后	记录失败日志
`Notification`	Claude 需要输入时	桌面通知
`Stop`	Claude 完成响应时	验证任务完成

配置示例

macOS 桌面通知：

json 复制代码

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude 需要你的输入\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

编辑后自动格式化（Prettier）：

json 复制代码

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

退出码含义

退出码	行为
`0`	操作继续，stdout 内容加入上下文
`2`	操作被阻止，stderr 作为反馈
其他	操作继续，stderr 仅在 verbose 模式记录

十一、IDE 集成

VS Code

安装：扩展商店搜索 "Claude Code"（Cmd+Shift+X）

核心快捷键：

快捷键	功能
`Cmd+Esc` / `Ctrl+Esc`	切换编辑器与 Claude 焦点
`Cmd+Shift+Esc` / `Ctrl+Shift+Esc`	在新标签页打开
`Option+K` / `Alt+K`	插入 @文件引用
`Cmd+N` / `Ctrl+N`	新对话

功能特色：内联 diff 对比、@引用文件/文件夹、计划审查、多标签对话

JetBrains

支持 IntelliJ IDEA、PyCharm、WebStorm、GoLand、Android Studio 等。

安装：JetBrains 插件市场搜索 "Claude Code"

核心快捷键：

快捷键	功能
`Cmd+Esc` / `Ctrl+Esc`	快速启动
`Cmd+Option+K` / `Alt+Ctrl+K`	文件引用

桌面应用

可从 claude.ai 下载 macOS / Windows 版本。支持可视化 diff、多会话并行、集成终端。

网页版

访问 https://claude.ai/code，无需本地安装，支持长时间运行任务和并行操作。

十二、实战示例

示例 1：了解新项目

bash 复制代码

cd /path/to/new-project
claude

> 给我一个项目概览
> 用了哪些技术？
> 解释主要架构模式
> 认证是在哪里实现的？

示例 2：修复 Bug

bash 复制代码

claude

> 用户上传文件时出现 500 错误，帮我排查
# Claude 自动读取相关文件、运行测试、定位问题

> 运行测试确认修复正确
> 提交这个修复

示例 3：重构代码

bash 复制代码

claude

> 找出所有使用废弃 API 的地方
> 将 utils.js 重构为 ES2024 语法
> 运行测试确保没有破坏功能
> 为这次重构创建 PR

示例 4：添加新功能（计划模式）

bash 复制代码

claude

> 我需要添加 OAuth 登录支持
# Claude 进入计划模式分析

> /plan
# 审查方案，提出问题

> 方案可行，开始实现

示例 5：CI/CD 自动化

bash 复制代码

# 代码审查
claude -p "审查这些变更的安全问题" --output-format json > analysis.json

# 自动化翻译
claude -p "将新增字符串翻译成法语" --dangerously-skip-permissions

# 日志监控
tail -f app.log | claude -p "发现严重错误时报警"

示例 6：自定义技能

创建 ~/.claude/skills/deploy/SKILL.md：

yaml 复制代码

---
name: deploy
description: 部署应用到生产环境
disable-model-invocation: true
---

部署流程：
1. 运行测试套件
2. 构建生产包
3. 推送到生产服务器
4. 验证部署状态

使用：在 Claude Code 中输入 /deploy

示例 7：Git 工作树并行开发

bash 复制代码

# 创建工作树
git worktree add ../project-feature -b feature-a

# 在不同终端并行运行 Claude
cd ../project-feature && claude    # 终端 1
cd ../project-bugfix && claude     # 终端 2

十三、高级功能

子代理（Subagents）

在隔离上下文中执行专门任务的代理：

yaml 复制代码

---
name: code-reviewer
description: 代码质量与安全审查
tools: Read, Grep, Glob, Bash
model: sonnet
---

你是代码审查员，检查：
- 代码清晰度
- 安全问题
- 性能问题
- 测试覆盖率

扩展思考

Claude 在复杂问题上先推理再回答：

通过 Option+T / Alt+T 切换
在 /config 中配置
可调整 Opus 4.6 的思考深度

会话管理

bash 复制代码

claude -c                         # 继续最近会话
claude -r auth-refactor           # 按名称恢复
claude -r                         # 交互式选择
claude -c --fork-session          # 分叉会话

命名会话：/rename auth-refactor

上下文管理

/context --- 查看上下文占用
/compact --- 压缩上下文（可指定保留重点）
将持久指令放入 CLAUDE.md
用子代理处理大量输出的操作

十四、常见问题排查

问题	解决方案
Claude 无响应	检查网络，验证 API 密钥，尝试新对话
权限错误	运行 `claude doctor`，检查 settings.json 语法
MCP 连接失败	`/mcp` 检查状态，验证认证信息
上下文占用过高	`/context` 查看，`/compact` 压缩
响应缓慢	切换到 Sonnet/Haiku 模型，关闭扩展思考
安装异常	`claude doctor` 全面诊断

最佳实践总结

项目初始化 ：用 /init 创建 CLAUDE.md，写明技术栈、约定和命令
明确提示：提供具体需求，给出验证条件
权限配置：在 settings.json 中预设常用命令的允许/拒绝规则
善用计划模式 ：复杂任务先 /plan 再动手
管理上下文 ：大型操作委托给子代理，定期 /compact
安全意识 ：不对不信任的代码使用 --dangerously-skip-permissions

本文档基于 Claude Code 官方文档整理，最后更新：2026 年 2 月