本文详解 Webpack 5 下通过 html-bundler-webpack-plugin 实现 HTML 中 的静态图片自动解析与打包，替代过时的 html-loader + url-loader 组合，支持路径自动重写、哈希命名与资源内联/输出分离。
本文详解 Webpack 5 下通过 `html-bundler-webpack-plugin` 实现 HTML 中 `
在 webpack 5+ 项目中，直接在 html 模板中使用相对路径（如 
）无法被默认识别并处理——这是因为 html-loader 仅负责解析 html 内容，但不主动解析和重写 、、<script> 等标签中的 src/href 属性值</script>，尤其当这些路径指向本地静态资源时。你当前配置中虽启用了 html-loader 和 url-loader，但二者职责分离且缺乏联动：html-loader 不会触发图片规则匹配，导致图片路径未被解析、未被拷贝或转为 base64，最终浏览器请求 /src/assets/images/pic.png（404）而非构建后的产物路径。
✅ 正确解法：改用 html-bundler-webpack-plugin —— 它专为 HTML 模板设计，能深度扫描 HTML 中所有资源引用（src、href、poster、icon 等），自动匹配 Webpack 资源规则，并将原始路径替换为最终输出的带哈希的文件名。
✅ 推荐配置（Webpack 5.88.2 兼容）
首先安装依赖：
npm install --save-dev html-bundler-webpack-plugin
更新 webpack.config.js：
const HtmlBundlerPlugin = require('html-bundler-webpack-plugin');
<p>module.exports = {
plugins: [
new HtmlBundlerPlugin({
entry: {
index: './src/index.html', // ✅ 关键：声明 HTML 为入口
},
js: { filename: 'js/[name].[contenthash:8].js' },
css: { filename: 'css/[name].[contenthash:8].css' },
// 可选：自动注入 CSS/JS，无需手动写 <link>/<script>
// inject: true,
}),
],</script></p><p>module: {
rules: [
// ✅ 处理 SCSS/CSS（如需）
{
test: /.(scss|css)$/,
use: ['css-loader', 'sass-loader'],
},
// ✅ 统一处理图片资源（推荐 Webpack 5 原生 asset 模块）
{
test: /.(png|jpe?g|gif|ico|svg)$/i,
type: 'asset/resource', // 输出为独立文件（非 base64）
generator: {
filename: 'img/[name].[hash:8][ext]', // 输出到 dist/img/
},
},
// ✅ 音频等其他静态资源
{
test: /.mp3$/,
type: 'asset/resource',
generator: {
filename: 'media/[name].[hash:8][ext]',
},
},
],
},
};</p>
同时，修改你的 src/index.html 中的图片路径为相对于 HTML 文件的相对路径（非绝对路径 /src/...）：
<!-- ✅ 正确：使用 ./ 开头的相对路径 --> <img src="./assets/images/pic.png" alt="示例图"><p><!-- ❌ 错误：/src/... 是开发时路径，Webpack 不解析绝对 URL --> <!-- <img src="/src/assets/images/pic.png"> --></p>
? 提示：html-bundler-webpack-plugin 支持 Webpack 别名（如 @/assets/...），只需在 resolve.alias 中配置即可。
✅ 构建后效果
输入 HTML：
<img src="./assets/images/pic.png">
输出 HTML（自动重写）：
<img src="img/pic.a1b2c3d4.png">
对应文件输出至 dist/img/pic.a1b2c3d4.png，浏览器可正常加载。
⚠️ 注意事项与常见问题
- 不要混用 html-loader：html-bundler-webpack-plugin 已内置 HTML 解析逻辑，保留 html-loader 可能引发重复处理或冲突，建议移除。
- 路径必须是相对路径：./assets/... 或 ../images/...，不能是 /src/... 或 http://...；若需别名，配置 resolve.alias 并在 HTML 中使用 @/assets/...。
-
type: 'asset/resource' vs asset/inline：
- asset/resource → 输出为独立文件（推荐用于图片，利于缓存）；
- asset/inline → 转为 base64 内联（适合极小图标，但增大 HTML 体积）。
- 确保 HtmlWebpackPlugin 已移除：html-bundler-webpack-plugin 是其现代替代方案，两者不可共存。
✅ 总结
Webpack 5 中 HTML 内图片加载失败的根本原因，是传统 loader 链缺乏对 HTML 属性路径的主动解析能力。html-bundler-webpack-plugin 以“HTML 为入口”的理念重构了构建流程，真正实现模板即入口、资源即依赖。它不仅解决图片问题，还统一管理 CSS、JS、字体、图标等所有 HTML 引用资源，大幅提升配置一致性与可维护性。升级至此方案，即可告别路径 404，拥抱自动化资源管理。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
