本页目录6
要点速览
- 缓存按【前缀精确匹配】:前缀里任何改动都会重算其后的全部;系统提示层一变则整条失效。
- 让缓存失效:切模型(/model)、换 effort、开 fast mode、连/断 MCP(非 deferred 时)、改插件 MCP、deny 整个工具、/compact、升级 Claude Code。
- 保持缓存:改仓库文件、会话中改 CLAUDE.md(改了也不生效,需 /clear/重启)、换 output style、切权限模式、调用 skill/命令、/recap、/rewind。
- 模型与 effort 在会话开头定好,/compact 留到任务间隙;改动越少命中率越高。
- TTL:订阅默认 1 小时、API/三方默认 5 分钟(ENABLE_PROMPT_CACHING_1H=1 开 1h);statusline 看 cache_read/creation_input_tokens 判断命中。
本文是对官方 How Claude Code uses prompt caching 的中文要点整理,行为与变量名以原文为准。
为什么关心它
每次发消息,Claude Code 都发一次新 API 请求,并重发全部上下文(系统提示、项目上下文、所有历史消息与工具结果、你的新消息),新内容追加在末尾。prompt caching 让 API 复用已处理的部分,只对变化的部分做新计算——更快、更省。Claude Code 自动管理它,但有些操作会让缓存失效、导致下一轮变慢变贵,值得了解。
原理:前缀精确匹配
API 用请求的**开头(前缀)**去匹配最近处理过的内容。匹配是精确的:前缀里任何一处改动,都会重算其后的全部。没有按文件/按段的缓存。Claude Code 据此把"很少变的"排在前面:
| 层 | 内容 | 何时变 |
|---|---|---|
| 系统提示 | 核心指令、工具定义、输出风格 | 工具集变化、或 Claude Code 升级 |
| 项目上下文 | CLAUDE.md、auto memory、规则 | 会话开始,或 /clear / /compact 后 |
| 对话 | 你的消息、Claude 回应、工具结果 | 每一轮 |
改"对话层"不影响前两层缓存;改"系统提示层"则整条失效。此外 model 与 effort level 也是缓存 key 的一部分(各自独立缓存)。
会让缓存失效的操作
下一轮变慢变贵一次,之后新前缀被缓存:
- 切模型(
/model):每个模型独立缓存;opusplan进出 plan 模式即切模型;Fable 5 自动 fallback 也是切模型。 - 换 effort(
/effort):会弹确认框。 - 开 fast mode:加了请求头(属缓存 key);每会话首次开销一次。
- 连/断 MCP 服务器:工具载入前缀时失效;**deferred 工具(默认)**只追加、不动缓存。改 MCP 配置本身不失效,重启后连/断才触发。
- 启/禁插件:仅当插件提供 MCP 服务器时按上条规则;skills/commands/agents/hooks 等只追加、不失效。变更在
/reload-plugins或新会话后生效。 - deny 整个工具(裸
Bash/"*"等):内置工具定义在系统提示层 → 失效;带范围的Bash(rm *)及 allow/ask 规则不失效。 /compact:重写对话层(本就该失效);系统提示层复用,项目上下文从磁盘重载(CLAUDE.md/memory 未变才命中)。- 升级 Claude Code:首轮从头重建;auto-update 在下次启动才应用,不会会话中途突变。
恢复长会话升级后会无命中重读整段历史——回到长会话的首轮可能是最贵的请求。
保持缓存的操作
追加在末尾或根本不碰请求:改仓库文件、会话中改 CLAUDE.md(改了也不生效,需 /clear//compact/重启)、换 output style(同理不即时生效)、切权限模式(opusplan 例外)、调用 skill/命令、/recap、/rewind(截回已缓存的更早前缀)、起 subagent(子代理独立缓存,父会话前缀不受影响)。
缓存寿命(TTL)与命中率
- 命中会重置计时;久不动后首轮重算。API 提供 5 分钟与 1 小时两种 TTL。
- 订阅:自动用 1 小时(计入套餐、不额外收费;超额走 usage credits 时降到 5 分钟)。
- API key / Bedrock / Vertex 等:默认 5 分钟;
ENABLE_PROMPT_CACHING_1H=1开 1 小时。FORCE_PROMPT_CACHING_5M=1强制 5 分钟。 - 看命中率:用 statusline 读
current_usage的cache_read_input_tokens(约标准输入价 10%)与cache_creation_input_tokens(写入价)。读/写比高=缓存良好;若 creation 持续高,说明前缀总在变。
禁用(调试用)
设环境变量为 1:DISABLE_PROMPT_CACHING(全模型)或 DISABLE_PROMPT_CACHING_{HAIKU,SONNET,OPUS,FABLE}(按模型)。正常使用保持开启即可。