Nginx原生sub_filter不支持正则，仅能做固定字符串替换（如/sub.css//sub.css?v=20241105），需配合sub_filter_once off实现多次匹配，且仅对text/html等显式声明的Content-Type响应生效，不处理JS/CSS内部链接或API请求。
使用 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>、<link href="css/style.css"> - ❌ 不适合：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="' '<script src="';
sub_filter '<link href="' '<link href="';
sub_filter '<img src="' '<img src="';
sub_filter_once off;
sub_filter_types text/html;
# 启用缓冲，确保完整响应体可被扫描
proxy_buffering on;
proxy_buffer_size 128k;
proxy_buffers 4 256k;
proxy_busy_buffers_size 256k;
}但上面只是“锚点”，真正替换需配合正则式——Nginx 官方 sub_filter 不支持正则，需启用 ngx_http_substitutions_filter_module（第三方模块，需编译时加入）。若仅用原生模块，只能做固定字符串替换，例如：
sub_filter '/js/app.js' '/js/app.js?v=20241105'; sub_filter '/css/main.css' '/css/main.css?v=20241105';
这种方式维护成本高，不推荐用于多文件场景。
实用替代方案：用 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
不复杂但容易忽略：sub_filter 是“最后防线”，优先考虑构建时打版本戳或用 Cache-Control 精细控制。真要用它，务必搭配完整缓冲和类型校验，避免页面局部失效或白屏。
