哪些操作会让 prompt cache 失效

Claude Code 每一轮都把完整对话历史重发给 API,靠 prompt cache 才不用每次重新处理。知道哪些操作会打破缓存,就能避开那些「一次性变慢变贵」的坑。

一句话结论

结论 cache 按「请求前缀精确匹配」命中:凡是改动请求开头内容(系统提示、工具定义)或换了 cache key(模型、effort、fast mode)的操作,都会让下一轮全量重算。官方官方建议:模型和 effort 在会话开头定好,/compact 留到任务间隙,会话中改动越少命中率越高。

做法步骤

先理解命中机制。官方模型在请求之间没有记忆,Claude Code 每轮都重发全部上下文;API 按「前缀」精确匹配最近处理过的内容,正常轮次只有最新一问一答是新的,其余按缓存价(约标准输入价的 10%)重读。前缀任何一处变动,其后的内容全部重算——没有按文件、按片段的局部缓存。为此 Claude Code 把最少变动的内容排在最前:

请求按变动频率分层排序;cache 从变动点断开,之后全部按未缓存价重算。
记住 8 个会失效的操作。官方官方文档给出的完整清单:
- /model 切模型:每个模型有独立 cache,内容一样也全量重算;opusplan 设置下每次进出 plan mode 都是一次模型切换。
- /effort 改推理力度:cache key 含 effort,会话中改会先弹确认框。
- 开 fast mode:请求头进入 cache key,一次性成本;之后关掉、限流回退都不再失效。
- MCP server 连接/断开:仅当工具定义被加载进前缀时(tool search 被禁用、alwaysLoad 等场景);默认的 deferred 工具不受影响。详见 MCP 接多了更慢更贵。
- 启用/禁用带 MCP server 的插件:同上;只含 skills/hooks/commands 的插件从不打破 cache。
- deny 整个内置工具(如裸写 Bash):把该工具从系统提示里移除;Bash(rm *) 这类带范围的规则不影响。
- /compact:对话层换成摘要,必然失效;但趁 cache 还热时做,大头只是生成摘要,冷启动(休息超过 TTL 后)compact 最贵。
- 升级 Claude Code:新版本通常更新系统提示或工具定义,重启后第一轮重建 cache;升级后 --resume 一个长会话,第一轮可能是你发过最贵的请求。
分清「不失效」的操作,别白担心。官方改仓库文件、会话中改 CLAUDE.md(注意:也不生效,要等 /clear 或重启才加载)、改 output style(同前)、切权限模式、调用 skill 和命令、/recap、/rewind、开 subagent——这些要么只在对话末尾追加内容,要么根本不动请求。其中 /rewind 回到的是已缓存的前缀,想放弃一条路时比 /compact 更省。
核实自己的命中率。官方API 每次响应带两个字段:cache_read_input_tokens(命中,约 10% 价)和 cache_creation_input_tokens(写入)。用 statusline 脚本读 current_usage 实时看:read 高 creation 低是健康状态;creation 每轮都高,说明前缀一直在变,对照上面的清单排查。
注意 TTL,别把过期当失效。官方缓存闲置会过期:订阅默认 1 小时,API key 和云厂商默认 5 分钟(可设 ENABLE_PROMPT_CACHING_1H=1 换 1 小时)。离开太久后第一条消息必然全量重算,这不是你操作出了错。机制细节可回看 D2 · 上下文窗口与 prompt caching。

可直接抄的 prompt

帮我检查这个会话的 prompt cache 健康度:
1. 给我配置一个 statusline 脚本,显示 current_usage 里的
   cache_read_input_tokens 和 cache_creation_input_tokens,
   写入我的 Claude Code statusline 配置(先展示脚本内容让我确认);
2. 解释这两个数怎么读:什么样算命中良好,什么样说明前缀在被反复破坏;
3. 对照官方「会破坏 cache 的操作」清单(切模型、改 effort、开 fast mode、
   MCP server 连断、deny 整个内置工具、/compact、升级后 resume),
   给我一份「会话中途尽量别做」的操作备忘。

来源与最后核实日期

官方code.claude.com/docs/en/prompt-caching.md(缓存分层、失效/不失效清单、TTL、cache 指标),抓取于 2026-08-05。
本站观点「用 /rewind 替代 /compact 放弃错误路径更省」为官方 Tip 的转述与编排;statusline 排查步骤为本站整理。
最后核实:2026-08-05 · volatility:high(绑定 Claude Code 当前行为,官方文档水位 v2.1.222,需定期复核)。