一次 Claude-Code 缓存崩溃的完整溯源深度解读

背景

在开发实践中，开发者常利用 Claude Code 对接支持 Anthropic API 兼容接口的模型（如 DeepSeek V4）以优化成本或提升推理速度。然而，在实际使用中，部分用户观察到一种异常现象：在单次对话会话中，API 调用的缓存命中率（Cache Hit Rate）会出现“脉冲式”的剧烈波动。具体表现为，缓存命中率在某一时刻从 99% 以上的高位突然暴跌至接近 0%，但在下一轮对话中又自动恢复至高位。这种不稳定的缓存行为不仅增加了 API 调用成本，也影响了开发体验。为了查明这一现象的根本原因，需要对 Claude Code 的内部机制、Prompt 构建逻辑以及底层缓存匹配算法进行深入的源码级溯源。

核心内容

本次溯源揭示了缓存命中率暴跌的根本原因在于 Anthropic 及其兼容接口（如 DeepSeek）采用的 Byte-Exact Prefix Match（字节精确前缀匹配）机制，与 Claude Code 动态注入 Git 状态快照 之间的冲突。

1. 缓存失效机制：字节级精确匹配

Anthropic 的 Prompt Cache 机制要求请求的前缀必须从第 0 字节开始逐位完全一致。任何前缀的微小变化（哪怕只是一个字节的差异）都会导致后续所有的 KV Cache 失效。这意味着，如果 System Prompt 或消息历史中的任何部分发生变化，整个缓存链条都会断裂。

2. 触发源：动态变化的 git status

Claude Code 在构建 System Prompt 时，会嵌入一个 git status 快照，以便模型了解当前项目的文件变更情况。该快照包含当前分支、文件状态（如 M 修改、?? 未跟踪）以及最近的提交记录。

• 现象：当开发者在会话中创建、修改或删除文件时，git status 的输出内容会发生变化。
• 后果：由于 git status 被嵌入在 System Prompt 的特定位置，其内容的任何变动都会导致整个 Prompt 的字节序列发生改变。即使变化仅涉及几行文本（例如新增一个 ?? temp_debug.json 文件），也会导致后续数十万个 Token 的缓存全部作废。

3. 源码级根因分析

通过追踪 Claude Code 的源码，发现以下关键逻辑链条：

• 缓存劫持与惰性更新： getGitStatus 和 getSystemContext 函数使用了 lodash 的 memoize 进行缓存。该缓存基于 Map，且没有设置 TTL（生存时间），意味着它永远不会自动过期。

  • 在正常的 REPL 逐轮对话中，getGitStatus 仅在会话开始时执行一次，后续调用均返回会话开始时的 Git 状态快照。因此，缓存是稳定的。
  • 然而，当执行 --resume（恢复会话）或 /clear 等命令时，会触发 clearSessionCaches()，强制清除 memoize 缓存。此时，getGitStatus 会重新执行 git status --short，读取磁盘上当前的文件状态。
  • 如果此时磁盘文件状态与上一轮会话结束时不同（例如用户在此期间修改了文件），新生成的 git status 字符串将与之前的缓存前缀不同，导致缓存重建，命中率瞬间跌至 0%。

• Token Diff 验证： 使用 DeepSeek tokenizer 对相邻两次请求进行逐 Token 对比，发现分叉点正好落在 gitStatus 段。例如，若两次请求的 Token 总量约为 36 万，而分叉点在第 1490 个 Token 处，则前缀命中率仅为 0.41%，这与 API 报告的极低命中率（如 0.45%）高度吻合。

• 自动恢复机制： 暴跌发生后，新的前缀被写入缓存。只要后续对话不再触发 --resume 或文件状态不再变化，前缀将保持一致，缓存命中率随即恢复至 99% 以上。这解释了为何会出现“脉冲式”突变：每次状态重置（如 --resume）都是一次脉冲。

关键要点

• 缓存失效原理：Anthropic 兼容接口的缓存基于字节精确前缀匹配，任何前缀变化均导致全量缓存失效。
• 直接诱因：Claude Code 将动态的 git status 注入 System Prompt，文件变更导致 Prompt 内容变化，进而破坏缓存前缀。
• 根本机制：getGitStatus 使用无 TTL 的 memoize 缓存。正常对话中缓存稳定；但 --resume 或 /clear 会强制刷新缓存，若此时磁盘文件状态已变，则生成新的前缀，导致缓存命中率暴跌。
• 恢复逻辑：暴跌后，新前缀被缓存。只要不再重置会话或改变文件状态，后续请求即可命中缓存，形成“高-低-高”的脉冲模式。
• 解决方案：
  • 禁用 Git 状态注入：设置环境变量 export CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS=1，彻底消除因文件变化导致的缓存失效，代价是模型无法自动感知 Git 状态。
  • 其他优化建议：
    • 设置 export CLAUDE_CODE_ATTRIBUTION_HEADER=0 禁用计费 Header。
    • 避免在对话中途修改 CLAUDE.md 或 MEMORY.md，这些文件通过 prependUserContext() 注入，内容变化会破坏缓存。
    • 避免在对话中途增删 MCP 服务器，工具列表变化会改变 System Prompt。
    • 减少使用 --resume，因其会触发全量缓存刷新。
    • 将临时文件加入 .gitignore，减少 git status 内容的波动频率。

意义与影响

此次溯源不仅解决了一个具体的性能问题，更揭示了大型语言模型应用开发中缓存优化的几个重要原则：

1. 缓存前缀的稳定性至关重要：在使用基于前缀匹配的缓存机制时，必须确保输入 Prompt 的静态部分绝对不变。任何动态注入的内容（如时间戳、状态快照、环境变量）都可能导致缓存失效，抵消缓存带来的性能红利。
2. 理解底层 API 语义：Anthropic 的 cache_control 和字节匹配机制与传统的 Token 级缓存不同，对前缀的敏感性极高。开发者在对接兼容接口时，需充分理解其底层匹配逻辑，避免因细微的 Prompt 差异导致成本激增。
3. 工具链集成的权衡：Claude Code 等 AI 编程助手将 Git 状态等上下文信息嵌入 Prompt 以提升模型理解能力，但这与缓存优化存在内在冲突。开发者需根据实际需求（如是否需要模型感知最新文件状态 vs. 是否需要极致缓存命中率）进行权衡，并通过环境变量灵活配置。
4. 调试方法论：面对复杂的缓存异常，通过源码级追踪（如定位 memoize 缓存逻辑）、Token 级 Diff 分析（确定分叉点）以及控制变量实验（如对比 --resume 前后的行为），是高效定位和解决问题的有效路径。

综上所述，通过禁用动态 Git 状态注入或优化会话管理策略，开发者可以在保持模型上下文感知能力的同时，显著提升 API 调用的缓存命中率，降低使用成本。