FORCE_PROMPT_CACHING_5M,Claude Code 缓存 TTL 的刹车踏板

FORCE_PROMPT_CACHING_5M,Claude Code 缓存 TTL 的刹车踏板

正在排查缓存时,最怕的不是 miss,而是搞不清为什么 miss

Claude Code 的 prompt caching 很容易被误解成一个简单的开关,打开以后就会变快,关闭以后就会变慢。真正落到工程现场,问题通常没有这么干净。一次请求有没有命中缓存,不只取决于缓存有没有开启,还取决于前缀是否一致,模型是否一致,认证方式是什么,provider 是否支持对应能力,cache breakpoint 放在哪里,TTL 是否已经过期。更麻烦的是,Claude Code 会根据认证方式自动选择 TTL,所以同一套项目、同一段历史、同一个命令,在 Claude subscription、API key、Bedrock、Vertex AI、Foundry 这些环境里,缓存表现可能并不完全一样。

这里的关键变量就是FORCE_PROMPT_CACHING_5M=1。它不是用来关闭 prompt caching 的,也不是用来让 Claude Code 忘掉已有上下文的。它的作用更像一块刹车踏板,当环境里已经存在 1 小时 TTL 的倾向时,把后续 prompt cache TTL 强行拉回 5 分钟。Claude Code 官方文档明确写到,设置FORCE_PROMPT_CACHING_5M=1后,会不管当前使用什么认证方式,都强制使用 5 分钟 prompt cache TTL,并且会覆盖ENABLE_PROMPT_CACHING_1H。这个变量适合调试缓存行为、对比两种 TTL,或者在 managed settings 已经设置ENABLE_PROMPT_CACHING_1H