因为 html-webpack-plugin 默认只注入变量和生成 html，不解析 src/href 等属性中的静态资源路径，无法自动将 app.js 替换为 app.a1b2c3.js，导致构建后引用失效 404。
为什么直接用 Webpack 的 html-webpack-plugin 会漏掉内联资源
旧项目 HTML 里大量使用 <script src="js/app.js"></script> 或 <link rel="stylesheet" href="css/main.css">，甚至还有 <img src="logo.png"> 这类硬编码路径。Webpack 默认只处理 JS 模块依赖里的 import 和 require()，对 HTML 模板里的字符串路径完全无感——html-webpack-plugin 默认只做变量注入和基础替换，不会主动解析并重写这些 src/href 属性。
常见错误现象：构建后文件名带哈希（如 app.a1b2c3.js），但 HTML 里仍引用旧名 app.js，导致 404。
- 必须启用
html-webpack-plugin的hash: true仅给整个 HTML 加哈希，不解决内部引用问题 -
webpack-subresource-integrity或webpack-manifest-plugin生成映射表，但不自动改 HTML - 真正要的是“HTML 静态分析 + 资源路径重写”，不是打包入口逻辑
用 html-webpack-plugin 的 transform 钩子手动重写路径
这是最轻量、侵入性最小的方案，无需引入额外 loader 或重构 HTML 结构。关键在利用插件提供的 transform 函数，在 HTML 生成前遍历所有标签属性，匹配已知资源路径并替换为带哈希的版本。
示例逻辑（Webpack 配置片段）：
new HtmlWebpackPlugin({
template: './src/index.html',
transform: (html) => {
return html.replace(/(src|href)=["']([^"']*\.((js|css|png|jpg|gif|svg)))/g, (match, attr, path, ext) => {
const hashedPath = compilation.assets[path]?.name || path;
return `${attr}="${hashedPath}"`;
});
}
})
注意：compilation.assets 是 Webpack 内部资源对象，需确保该钩子在 emit 阶段之后执行；更稳妥做法是结合 compilation.hooks.emit.tapAsync 提前收集哈希映射表，再传入 transform。
- 正则必须覆盖所有可能扩展名，否则
favicon.ico或data.json会被跳过 - 路径含查询参数（如
style.css?v=1）时，正则需排除?后内容，否则哈希插入位置错乱 - 避免匹配非资源路径，例如
href="#section"或src="data:image/svg+xml,..."
用 gulp-rev + gulp-rev-collector 处理纯静态 HTML 项目
如果项目没用 Webpack，只是靠 Gulp 构建，gulp-rev 是更直接的选择：它先给文件加哈希重命名，再生成 rev-manifest.json，最后由 gulp-rev-collector 扫描 HTML 并按 manifest 替换路径。
典型流程：
gulp.src(['./src/js/*.js', './src/css/*.css'])
.pipe(rev())
.pipe(gulp.dest('./dist'))
.pipe(rev.manifest())
.pipe(gulp.dest('./dist'));
gulp.src(['./dist/rev-manifest.json', './src/*.html'])
.pipe(revCollector())
.pipe(gulp.dest('./dist'));
容易踩的坑：
-
rev-collector默认只替换href和src，不处理data-src（懒加载）、content（meta icon）等，需配置replaceReplacer手动扩展 - manifest 文件路径必须与 HTML 中引用路径严格对应，比如 HTML 里写
js/app.js，manifest 键就必须是"js/app.js"，不能是"app.js" - 多级目录（如
pages/home.html引用../css/base.css）会导致路径解析失败，建议统一以dist为根来写相对路径
要不要把 HTML 本身也哈希？
通常不建议。HTML 文件本身不参与缓存强依赖，且服务端常需动态生成或 A/B 测试，哈希后反而增加 CDN 缓存管理成本。真正需要哈希的是 JS/CSS/图片——它们体积大、复用率高、内容不变时应长期缓存。
例外场景只有两个：
- 全站静态托管（如 GitHub Pages），且 HTML 确实极少变动，可配
HtmlWebpackPlugin的filename: 'index.[contenthash:8].html' - 配合 Service Worker 精确控制缓存版本，此时需确保 HTML 哈希变化能触发 SW 更新逻辑
但绝大多数旧项目升级时，只处理资源文件哈希就足够了；强行哈希 HTML 容易引发 Nginx/Apache 路由 404，或 requireJS/AMD 加载器找不到入口模块。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
