Nginx 中如何实现静态资源版本自动升级更新

Nginx 实现静态资源版本自动升级依赖构建流程生成内容哈希文件名、Nginx 配置匹配哈希路径并启用 immutable 长期缓存、HTML 短缓存确保加载最新链接，三者协同实现更新即生效。

在 Nginx 中实现静态资源版本自动升级更新，核心不是让 Nginx 自动修改文件或生成版本号，而是通过构建流程 + URL 版本化 + Nginx 缓存控制协同完成。Nginx 本身不参与版本生成，但能高效支持带哈希的静态资源路径和强缓存策略，从而实现“更新即生效、旧资源仍可用”的效果。

构建时生成带内容哈希的文件名

这是版本自动升级的前提。前端构建工具（如 Webpack、Vite、Rollup）可在打包时将文件内容哈希嵌入文件名，例如：
main.a2b3c4d5.js → main.1a8f9e22.js
这样，只要文件内容变化，文件名就变，URL 自然不同，彻底规避浏览器缓存问题。

• Webpack 示例：配置 output.filename: '[name].[contenthash:8].js'
• Vite 示例：默认开启 build.rollupOptions.output.entryFileNames 带 hash，无需额外配置
• 确保 HTML 中引用的 JS/CSS 路径由构建工具自动注入（如 HtmlWebpackPlugin 或 Vite 的 index.html 处理）

Nginx 配置匹配哈希文件并启用长期缓存

利用正则匹配带哈希的静态资源路径，对它们设置超长缓存时间（如 1 年），同时禁用 ETag（避免协商缓存干扰）：

• 在 server 或 location 块中添加：

location ~* .(js|css|png|jpg|jpeg|gif|ico|svg|woff2?|ttf|eot)$ {
    expires 1y;
    add_header Cache-Control "public, immutable";
    add_header Last-Modified "";
    etag off;
}

其中 immutable 告诉浏览器该资源不会变更，可跳过后续条件请求；etag off 避免 Nginx 基于文件修改时间生成 ETag，干扰哈希语义。

HTML 文件不缓存或短缓存，确保加载最新资源链接

HTML 是入口，必须每次请求都获取最新版本，否则会引用旧哈希文件：

• 单独配置 HTML 缓存策略：

location = /index.html {
    add_header Cache-Control "no-cache, no-store, must-revalidate";
    add_header Pragma "no-cache";
    add_header Expires "0";
}

也可用 max-age=0 或后端动态渲染 HTML（如 SSR），关键是保证用户访问时拿到的是包含新哈希链接的 HTML。

可选：Nginx 重写规则兼容无哈希旧请求（平滑过渡）

上线初期若存在外部链接或书签指向旧哈希文件，可加一层 fallback 重定向（非必需，但提升容错）：

• 例如把 /static/app.js 重写为最新哈希文件（需配合构建输出 manifest.json 或脚本生成映射）
• 更常用做法是：构建时生成 asset-manifest.json，由后端或 CDN 动态查表重写，Nginx 本身不推荐做复杂映射逻辑