静态资源指纹注入需构建、CDN、部署等五环节协同，contenthash必须嵌入文件名而非查询参数，HTML须构建时生成并原子发布，多实例需共享manifest，Service Worker仅作降级兜底。
静态资源指纹注入不是“往 HTML 里塞个 hash 字符串”就能解决版本冲突的，它必须和构建产物、CDN 缓存、多实例部署策略对齐；否则极易出现新 HTML 引用旧 JS、或多个节点返回不一致哈希路径的问题。
Webpack 中 contenthash 必须绑定到真实输出文件名，不能只靠 html-webpack-plugin 的 hash 参数
很多人开启 hash: true 后发现资源 URL 变成了 main.js?v=abc123，但这只是查询参数，CDN 和浏览器可能忽略它做缓存——真正的 contenthash 必须出现在文件名里，比如 main.a1b2c3d4.js。
- 确保
output.filename包含[contenthash]，例如'js/[name].[contenthash:8].js'；CSS 同理，MiniCssExtractPlugin的filename也要配对 -
html-webpack-plugin的hash: true仅用于加?v=，应关闭，改用templateParameters把真实文件名传入模板 - 模板需支持插值（如
.ejs），否则变量不会展开：<script src="<%= mainJs %>"></script> - 若用 Vite，对应配置是
build.rollupOptions.output.entryFileNames和assetFileNames，且需启用build.manifest生成manifest.json
多实例部署时，HTML 模板必须由构建阶段生成，不能运行时拼接
常见错误是后端模板引擎（如 Thymeleaf、EJS）在请求时读取本地 manifest.json 并渲染 script 标签——这会导致不同服务器节点读到的 manifest.json 版本不一致，A 节点返回的 HTML 引用 app.x1y2z3.js，B 节点却返回 app.a4b5c6.js，用户刷新就报 404。
- 所有 HTML 文件必须随构建产物一起产出并部署，不能动态生成
- 若必须后端渲染（如 SSR），则
manifest.json需作为构建产物上传至共享存储（如 S3/MinIO），后端启动时加载一次并缓存，禁止每次请求都读盘 - CI/CD 流程中，HTML + JS/CSS + manifest.json 必须原子性发布，避免中间状态被 CDN 缓存
- 检查 Nginx 或 CDN 是否对
.html设置了过长缓存（如Cache-Control: public, max-age=31536000），这会锁死旧 HTML，导致永远拉不到新资源
Service Worker + localStorage 指纹校验只能作为降级手段，不能替代构建时注入
有人想绕过构建流程，直接让 SW 在 install 阶段 fetch manifest.json、比对哈希、再 cache.put()——这看似灵活，但会引入严重时序问题：HTML 已加载并执行，但 SW 还没完成预加载，脚本执行报错；或者 SW 更新了缓存，但 HTML 仍引用旧路径，造成 mismatch。
立即学习“前端免费学习笔记（深入）”；
- SW 的作用是静默更新非关键资源（如图片、字体）、兜底离线场景，不是主版本控制机制
- localStorage 存的指纹必须和服务端
buildId对齐，每次发布生成唯一buildId，写入 HTML 的<meta name="build-id" content="20260619.1">，JS 初始化时比对，不一致则清空旧指纹 - 不要在
window.onload或DOMContentLoaded里触发指纹校验，应提前到<head>内联脚本中执行，避免阻塞资源发现 - 若使用微前端，主应用需统一管理指纹，子应用禁止自行操作
localStorage或注册 SW，否则跨子应用缓存混乱
真正难的不是算 hash，而是让 hash 在构建、部署、CDN、浏览器、SW 这五个环节保持语义一致——任何一个环节脱节，都会表现为“页面白屏”“资源 404”“样式错乱”，而错误日志往往只显示最终结果，不暴露链路断点。
