在 CSS 样式里写下 background-image: url('./a.png') 却发现图片无法正常显示——这是开发者经常遇到的棘手问题，尤其是在从 Webpack 4 迁移到 Webpack 5 或初次搭建项目时。很多人第一反应是 “base64 转换失败”，但实际原因往往更为简单直接。
Webpack 5 原生支持 CSS 中的 url(...) 图片引用，只需正确配置 asset 模块类型规则，无需额外 loader
关键不在于是否支持，而在于规则是否匹配了正确的文件扩展名、parser.dataUrlCondition.maxSize 是否设置合理，以及是否忽略了 css-loader 解析链路中的关键前提。这三个条件必须同时满足，而问题往往出现在最容易被忽视的细节上。
为什么 background-image: url("./a.png") 无法生效？
常见原因是在 JavaScript 中配置了 import 场景，但没有让 css-loader 正确识别并传递图片路径给 Webpack 处理。简而言之，只完成了部分配置。
具体的踩坑点如下：
- 需要确保
css-loader中url: true选项已启用（默认为开启）。如果错误地设置为 false，它将忽略url()声明，导致资源无法进入 Webpack 的处理流程。 - Webpack 规则中的
test需要包含目标图片文件后缀，例如/.(png|jpe?g|gif|webp|svg)$/i。许多开发者仅配置了jsx?$便以为足够了，实际上这是常见遗漏。 - 如果项目使用了 CSS Modules，请避免误开启
compileType: "icss"这类会禁用 URL 解析的配置。 - 图片路径应使用相对路径（如
./img/x.png），不要直接使用绝对路径或别名（如~assets/x.png），除非已配置了alias并且确认css-loader能够解析。
type: "asset" 与 type: "asset/resource" 在 CSS 场景中有何本质区别？
这不仅是语法上的区别，它们会直接影响构建产物的结构和浏览器发起请求的方式：
type: "asset"：当图片小于maxSize（例如8 * 1024）时，会被转换为 base64 内嵌到 CSS 中；超出限制则单独生成文件并自动填入 URL。这种配置在多数项目中最为推荐，因为它兼顾了内联和文件输出的优势。type: "asset/resource"：无论图片大小如何，都会生成独立文件（如img/abc123.png），CSS 中仅保存相对 URL。适用于大图或对缓存策略、SEO 有较高要求的场景。type: "asset/inline"：强制将所有图片转为 base64，忽略文件大小限制。这种模式下 CSS 文件可能变得非常庞大，因此建议仅用于 4KB 以下的小图标。asset/source对 CSS 图片引入基本无效，因为它仅导出文本内容，而 CSS 不会将纯字符串作为资源解析。
如何验证 CSS 图片处理是否正确？
不要仅凭页面显示来判断，还需要确认构建行为是否符合预期。以下是几个验证角度：
- 检查
dist目录：若配置为asset/resource，应能发现生成的图片文件；若使用asset且图片较小，CSS 中应出现data:image/png;base64,...形式的 base64 数据。 - 使用浏览器开发者工具，检查元素的计算样式，查看
background-image中的 URL 是相对路径（如img/xyz.png）还是 data URI。 - 在终端执行
npx webpack --stats=normal，观察输出中是否有asset modules类型的模块被 emit，其数量是否与引入的图片数量匹配。 - 若图片路径包含中文或空格，Webpack 5 默认会直接报错。此时需要配置
generator.filename: "[name][ext]"以取消 hash，或者提前清理不规范的文件名。
还有一个极易被忽略的细节：CSS 中引用图片依赖 css-loader 的解析链路，然而许多开发者仅修改 module.rules 却忽略了 css-loader 的版本——若版本低于 6.0，对 Asset Modules 的支持不完整。更普遍的情况是错误地设置了 url: false，直接阻断了资源流转。可以说，这类问题大多并非 Webpack 本身无法处理，而是配置链上的某个小环节被人为中断。
