关键在于构建阶段生成带内容哈希的文件名并自动更新html引用，nginx对哈希资源启用immutable长期缓存，html则需短缓存或不缓存以确保入口始终获取最新链接。

浏览器缓存与 CI/CD 自动化协同的关键，不在于让 Nginx “生成”版本号，而在于构建阶段产出带内容哈希的文件名，再由 Nginx 精准识别、长期缓存这些唯一路径，同时确保 HTML 入口始终获取最新链接。

构建时自动嵌入内容哈希

这是整个机制的起点。前端工具在打包时把文件内容摘要写进文件名，使内容变则 URL 变：

• Webpack：配置 output.filename: '[name].[contenthash:8].js'
• Vite：默认启用 build.rollupOptions.output.entryFileNames，含 hash
• 必须由构建工具自动更新 HTML 中的 script/link 标签引用，避免手动维护

Nginx 对哈希路径启用 immutable 长期缓存

匹配所有带哈希特征的静态资源后缀，用正则 location 统一设置强缓存策略：

page-agent 浏览器控制（CDP）

使用 page-agent CLI（CDP）控制浏览器；CLI只能通过 GitHub Release 的 .tgz 安装，npm 官方包暂未发布。

下载

• 使用 location ~* \.(js|css|png|jpg|gif|woff2?|ttf|eot)$ 捕获真实资源路径
• expires 1y + add_header Cache-Control "public, immutable"
• etag off 和 add_header Last-Modified "" 关闭协商缓存干扰
• immutable 告诉浏览器“此 URL 永远不会变”，跳过后续条件请求（如 If-None-Match）

HTML 必须短缓存或不缓存

HTML 是入口，它决定了用户加载哪个哈希资源。若 HTML 被缓存，就会持续引用旧文件：

• 对 location = /index.html 设置：Cache-Control "no-cache, must-revalidate"
• 或更严格地用 max-age=0，强制每次向服务器验证
• 服务端渲染（SSR）或动态注入版本路径也是可行替代方案

可选：平滑兼容旧链接（上线初期）

若存在外部书签、邮件链接指向旧哈希文件，可加一层 fallback 映射：

• 通过构建输出 manifest.json 或脚本生成哈希映射表
• Nginx 用 map 或 try_files 将缺失的旧路径重定向到当前最新哈希文件
• 该能力非必需，但能提升上线容错性