如何利用 sub_filter 指令自动为全站资源链接追加版本号实现缓存刷新-Nginx-PHP中文网

Nginx原生sub_filter不支持正则，仅能做固定字符串替换（如/sub.css//sub.css?v=20241105），需配合sub_filter_once off实现多次匹配，且仅对text/html等显式声明的Content-Type响应生效，不处理JS/CSS内部链接或API请求。

如何利用 sub_filter 指令自动为全站资源链接追加版本号实现缓存刷新

使用 Nginx 的 sub_filter 指令为 HTML 中的静态资源链接自动添加版本号（如 ?v=20241105），是一种轻量、无需改源码的缓存刷新方案。但它仅适用于 HTML 响应体中的文本链接，不处理 JS/CSS 内部引用或 API 请求，且依赖正则匹配，需谨慎配置。

明确 sub_filter 的作用边界

sub_filter 是 Nginx 的输出过滤模块，只对响应体（response body）做字符串替换，且仅在 Content-Type 匹配指定类型（默认 text/html）时生效。它不会修改 HTTP 头、JS 文件内容或动态生成的 URL（如 Vue/React 客户端路由）。

✅ 适合：HTML 页面中硬编码的 <script src="js/app.js"></script>、
❌ 不适合：JS 文件里写的 fetch('/api/data')、CSS 中的 background: url(img/logo.png)、服务端渲染模板变量（如 {{ asset_url }}）
⚠️ 注意：必须开启 sub_filter_once off 才能替换多次出现的相同链接；默认只替换第一个

基础配置：为常见资源路径追加统一版本号

假设你希望所有以 /js/、/css/、/img/ 开头的资源链接都加上 ?v=20241105，可在 server 或 location 块中添加：

location / {
    sub_filter '<script src="'%20'<script%20src=" sub_filter href="'%20'<link%20href=" sub_filter_once off sub_filter_types text proxy_buffering on proxy_buffer_size proxy_buffers proxy_busy_buffers_size><p>但上面只是“锚点”，真正替换需配合正则式——Nginx 官方 <code>sub_filter 不支持正则，需启用 <code>ngx_http_substitutions_filter_module（第三方模块，需编译时加入）。若仅用原生模块，只能做固定字符串替换，例如：<pre class="brush:php;toolbar:false;">sub_filter '/js/app.js' '/js/app.js?v=20241105';
sub_filter '/css/main.css' '/css/main.css?v=20241105';</script>

这种方式维护成本高，不推荐用于多文件场景。

实用替代方案：用 map + add_header 实现更可靠版本控制

比起脆弱的 HTML 文本替换，更健壮的做法是结合 map 指令动态生成版本标识，并通过 add_header 或后端注入，让资源请求天然带参：

map $time_iso8601 $version {
    "~^(\d{4})-\d{2}-\d{2}" $1;
}
server {
    location ~* \.(js|css|png|jpg|gif|woff2?)$ {
        add_header Cache-Control "public, max-age=31536000";
        # 重写请求路径，将 /js/app.js → /js/app.js?v=2024
        rewrite ^(.*)\.(js|css|png|jpg|gif|woff2?)$ $1.$2?v=$version break;
        # 或直接返回 302 重定向（慎用，增加请求）
        # return 302 $scheme://$host$1.$2?v=$version;
    }
}

不过该方式本质是重写 URL，需确保后端或文件系统能正确响应（如忽略查询参数）。更通用的做法仍是构建时注入版本号（Webpack/Vite 的 assetPrefix），或使用 ETag/Last-Modified 配合强缓存。

调试与验证关键点

启用 sub_filter 后容易因缓冲、MIME 类型或替换顺序出错，建议按以下步骤验证：

用 curl -I 确认响应头含 Content-Type: text/html，且未被压缩（sub_filter 对 gzip 响应无效）
临时关闭 gzip：gzip off;，或启用 sub_filter 的 gzip 兼容模式（需 Nginx ≥ 1.17.3 + 编译选项）
在 HTML 中插入明显测试标记，如 <script src="/test.js"></script>，再检查响应是否被替换
查看 error log：tail -f /var/log/nginx/error.log，留意 sub_filter: buffer too small 类警告，及时调大 proxy_buffer_size