自学教程

Claude Code 检查点

Claude Code 教程

简介

检查点（Checkpoints）是 Claude Code 的会话快照功能，可以保存项目当前文件变更状态、会话上下文，随时回滚到历史状态。
当连续做大量代码修改时，可以手动创建检查点；一旦改崩、需求变更，不用手动还原文件，一键恢复到保存快照时的项目状态。

区分概念

  • 会话上下文：对话历史，/clear 清空。
  • Checkpoint（检查点）：文件系统变更快照，记录文件修改，独立于对话上下文。
  • Git：完整版本管理；检查点是轻量临时快照，适合会话内快速回滚，一般不替代Git提交。

工作原理

  1. 创建检查点时，Claude Code 扫描项目当前已修改文件，生成快照并分配唯一ID。
  2. 快照只记录本次会话内产生的文件改动，不会复制整个项目源码。
  3. 可以随时列出、查看、恢复、删除检查点。
  4. 会话关闭后，检查点默认会被清理（可配置持久保留）。

检查点斜杠命令

/checkpoint create [名称]    # 创建检查点，自定义名称，例：/checkpoint create before-refactor
/checkpoint list             # 列出当前会话所有检查点
/checkpoint restore [id]     # 恢复到指定检查点，还原文件状态
/checkpoint describe [id]    # 查看某个检查点详情：变更文件清单
/checkpoint delete [id]      # 删除指定检查点
/checkpoint clear            # 清空当前会话全部检查点

使用示例

# 重构前，创建快照
/checkpoint create before-user-module-refactor执行代码重构任务
将用户模块接口迁移至新目录，拆分TS类型
如果改动出现问题，回滚
/checkpoint restore before-user-module-refactor

自动检查点配置

可以在项目 settings.json 开启自动创建检查点，在高危操作前自动快照。

{
  "checkpoints": {
    "autoCreate": true,
    "autoCreateOnFileWrite": true,
    "maxCount": 10
  }
}
  • autoCreate：开启自动检查点
  • autoCreateOnFileWrite：文件写入前自动生成快照
  • maxCount：会话最多保留检查点数量，超出自动清理旧快照

修改配置后 /clear 新建会话生效。

典型使用场景

✅ 推荐场景

  • 大型重构、批量文件重命名、大量代码迁移
  • 高风险代码修改，不确定效果，先打快照，方便一键回滚
  • 尝试多种实现方案，来回切换对比不同修改版本
  • 执行脚本、批量替换前，保存文件状态

❌ 不推荐场景

  • 长期版本管理：正式版本记录优先使用Git，检查点仅会话内临时快照
  • 极小改动，单文件几行修改，没必要创建检查点

检查点与权限、模式关系

  1. 创建/恢复检查点操作，遵循当前会话模式（Manual模式下，恢复文件变更需要审批）
  2. 受 .claude/rules 权限管控，不能恢复被全局规则禁止修改的文件
  3. 恢复检查点不会改变会话对话历史，只还原磁盘上文件内容

最佳实践

  1. 高风险操作前手动命名检查点，命名清晰，方便识别用途
  2. 控制检查点数量，不用的快照及时删除，减少磁盘占用
  3. 即使使用检查点，重要变更仍然建议先Git提交，双重保障
  4. 多人协作：检查点保存在本地会话，不会提交到Git仓库

常见问题

  1. 恢复检查点后，文件没有变回预期状态
  • 确认检查点ID正确；
  • 检查是否有外部编辑器手动修改文件（外部改动不会被快照管理）；
  • Manual模式下，恢复文件变更需要点击批准。
  1. 会话关闭，检查点消失
    默认检查点绑定当前会话，会话销毁自动清理；如需持久化，在settings.json开启持久选项。
  2. 检查点能恢复终端命令执行结果吗？
    不能。检查点仅记录文件内容快照，无法回滚数据库变更、外部系统状态。

安全提示

  • 检查点仅用于本地开发临时快照，不可作为备份方案
  • 恢复检查点会覆盖当前文件改动，恢复前确认当前未保存变更已妥善处理
  • 生产项目，恢复检查点的文件变更依然建议人工审阅
标签：

0 条笔记