Cache-Control 加了却不生效?Apache 官方:always 不是 onsuccess 的超集
一、先看 Apache 给的完整语法,里面藏着三个坑
想给静态资源加缓存头,多数人抄一句 Header set Cache-Control "max-age=3600" 就完事,但 Apache 官方 mod_headers 文档把这条指令的语法写得很密,坑都在这三行里:
Description: Configure HTTP response headers
Syntax: Header [ condition ] add|append|echo|edit|edit*|merge|set|setifempty|unset|note
header [[expr=] value [ replacement ] ]
[ early | env=[!] varname | expr= expression ]
Context: server config, virtual host, directory, .htaccess
Override: FileInfo
Status: Extension
Module: mod_headers
Compatibility: SetIfEmpty available in 2.4.7 and later, expr=value available in 2.4.10 and later
三处关键:condition 是可选参数(不写就是 onsuccess,这是后面所有误配的起点);动作词有 10 个(add/append/echo/edit/edit*/merge/set/setifempty/unset/note),set 与 merge 的差别直接决定头的值长什么样;以及版本门槛 —— SetIfEmpty 需要 2.4.7+,expr=value 写法需要 2.4.10+,在旧版上用了就是 400/500 启动失败。
官方还写了这条指令的作用时机:头是在 content handler 与输出过滤器都跑完之后才被修改的("The header is modified just after the content handler and output filters are run"),因此可以修改即将发出的响应头。这句话解释了为什么 mod_headers 能看到 PHP/CGI 自己设置的那些头。

二、always 不是 onsuccess 的超集 —— 官方原文点名了三场景
这是全文最反直觉的一条。官方说明:condition 决定这条指令作用于哪一张内部响应头表,取值是 onsuccess(默认、可省略)或 always。两者差别在于后者包含的头即使在错误响应中也会被加入,并且会跨内部重定向保留(例如 ErrorDocument 处理程序)。
紧接着原文给出关键警告:在两种条件下重复写同一条指令在某些场景是有必要的,因为就"已有头"而言 always 并不是 onsuccess 的超集。官方列举了三种情况:
- 你在给本地生成的非成功(非 2xx)响应加头,例如一个重定向 —— 此时最终响应里只使用 always 对应的那张表;
- 你在修改或删除由 CGI 脚本或 mod_proxy_fcgi 生成的头 —— 这些脚本的头位于 always 对应的表里,而不是默认表;
- 你在修改或删除服务器某部分生成的头,而该头没有被默认的 onsuccess 条件命中。
官方进一步解释成因:这种 onsuccess 与 always 之间的差异是 httpd 内部如何存储 HTTP 响应头的结果,因为它不提供任何"规范化"的单一头列表。而如果不把这个概念记在心上,写配置时最可能出的问题是某些响应里同一个头被重复写入两份(原文:some HTTP responses might end up with the same header duplicated,这会困惑用户,有时甚至困惑 HTTP 客户端)。
对做 CDN/缓存的实践含义很直接:只写在 onsuccess 里的 Cache-Control,在 304/4xx/5xx、以及经 ErrorDocument 内部重定向的响应上可能根本不出现;而反过来给 CGI/FastCGI 场景只写 onsuccess,则可能改不到真正存在 always 表里的那个头。
三、merge 与 append 的差别:官方用同一个例子演示了两种结果
想给已有的 Cache-Control 追加一个指令,选错动作词会直接得到畸形值。官方给的对照示例是这样的:配置两条
Header merge Cache-Control no-cache env=CGI
Header merge Cache-Control no-store env=NO_CACHE
用 merge 时,响应头是
Cache-Control: no-cache, no-store
而如果把 merge 换成 append,同一条配置得到的却是
Cache-Control: no-cache, no-cache, no-store
差别就在 merge 会做合并去重、append 是机械拼接。这就是"Cache-Control 里出现两份 no-cache"这类怪值的来源,而且这类重复值不只是难看:no-cache 与 no-store 语义不同,某些中间代理遇到冲突列表会退化成最保守的 no-store(全不缓存),表现为"明明加了缓存头却一点没命中"。
四、顺序决定成败:官方举的那个 MirrorID 例子
mod_headers 的 *Order of Processing* 一节强调:指令的处理顺序既受配置文件里的先后影响,也受所处配置 section 影响。官方用一对顺序相反的指令演示:
RequestHeader append MirrorID "mirror 12"
RequestHeader unset MirrorID
原文结论:按这个顺序,MirrorID 头不会被设置(This way round, the MirrorID header is not set);把两行颠倒过来,MirrorID 就会被设为 "mirror 12"。也就是说"先加后删"和"先删后加"是两个完全不同的结果,把 unset 与 set/append 混在同一段配置里时,必须逐行核对先后。
五、early 是调试用的,生产必须用 late
官方 *Early and Late Processing* 一节说得很硬:mod_headers 可以作用于请求处理的早期或晚期。正常模式是 late —— 请求头在内容生成器运行之前设置,响应头在数据发往网络线路时(just as the response is sent down the wire)设置;并且给出一句命令式建议:在生产服务器上请始终使用 Late 模式(Always use Late mode in an operational server)。
至于 early:它被设计为面向开发者的测试/调试辅助,用 early 关键字定义的指令会在处理请求的最开始就设置,因此可以用来模拟不同请求、构造测试用例,但也意味着这些头会被后续处理覆盖或改写。把 early 写进生产配置,正是"本地测试正常、上线后头不见了"的一个典型原因。
六、按条件设置:官方给的两个 expr 写法
手册示例区有两条特别实用的写法,分别解决"客户端没带 Cookie 才种"和"只给 200 加缓存":
# 当且仅当客户端没有发送 Cookie 时,设置一个测试 Cookie
Header set Set-Cookie testcookie "expr=-z %{req:Cookie}"
只为 HTTP 状态码为 200 的响应追加一个缓存头
Header append Cache-Control s-maxage=600 “expr=%{REQUEST_STATUS} == 200”
两条都依赖 expr= 表达式(需要 2.4.10+)。第一条用 -z 判空,%{req:Cookie} 读取请求头;第二条用 %{REQUEST_STATUS} 判响应状态 —— 后者正好绕开了第二节那个问题:既然错误响应可能只走 always 表,那就在源头把条件收紧到 200。
七、可直接用于静态资源的配置
综合以上规则,给带指纹的静态资源加长期缓存时,稳妥写法是"两个条件都写 + 用 merge + 明确 200"
<FilesMatch "\.(js|css|png|jpg|woff2)$">
Header set Cache-Control "public, max-age=31536000, immutable" env=HTTPS
Header merge Cache-Control s-maxage=31536000 "expr=%{REQUEST_STATUS} == 200"
</FilesMatch>
错误页不缓存:这类头只能靠 always 才能在 4xx/5xx 上出现
Header always set Cache-Control “no-store” “expr=%{REQUEST_STATUS} >= 400”
另外别忘了 Override: FileInfo —— 想在 .htaccess 里放 Header 指令,所在目录的 AllowOverride 必须包含 FileInfo(或 All),否则整份 .htaccess 被忽略,症状与"Cache-Control 没生效"完全一样。这跟 RewriteBase 那条是同一个前置检查项。
八、常见问题
Q:为什么我的 Cache-Control 在 304 上消失了?
A:因为默认 condition 是 onsuccess,而 304 属于非成功响应,官方明确说这种情况"只使用 always 对应的那张表"。解决是把需要恒定存在的头用 always 再写一份。
Q:set 和 add 有什么区别?
A:set 会替换同名头的先前值;add/append 是在已有值上追加(append 不合并、可能出现重复项,官方用 no-cache 的示例演示过)。要"追加但去重"就用 merge。
Q:我写了 Header set Set-Cookie 两行,但浏览器只收到一个 Cookie。
A:因为 set 会替换同名的前一个头。多个 Cookie 必须用 add/append,或在 PHP/CGI 侧设置(同时注意官方那句:这些脚本生成的头位于 always 表,用 onsuccess 条件去 unset 它可能无效)。
