Webpack构建向dist目录输出多余随机命名PNG且页面图片引用失效问题

直接定位根因 #

当前所有异常都来自两处配置错位：

1. url-loader没有配置资源输出路径、引用公共路径，默认输出的随机命名图片直接落在dist根目录，和html里生成的引用路径完全不匹配
2. 新版loader的默认ES模块解析逻辑，和html-loader对img标签src的解析规则冲突，会对同一张图片重复处理：一次是按静态资源拷贝逻辑生成文件，一次是按模块处理逻辑生成带hash的随机名文件
   这也解释了为什么其他资源加载正常：

• css中的background-image引用的资源，路径解析由css-loader处理，匹配css文件在dist/css/下的层级，能自动拼对相对路径
• slider目录下的图片，走的是CopyWebpackPlugin直接从src目录拷贝到dist/assets的流程，没有经过loader二次处理，所以路径完全正确

第一步：定向排查确认 #

打开构建产物dist/index.html，直接看3张加载失败的图片的实际src值：

• 正常预期的路径应该是./assets/slider/img1.png这类和拷贝路径匹配的相对地址
• 实际生成的大概率是x1y2z3abc456.png这类没有文件夹层级、直接带随机hash的文件名
  再检查dist目录：这三个带随机hash的png，是不是直接堆在dist根目录下，没有落在对应子文件夹里

第二步：逐项修复配置 #

1. 补全url-loader的完整配置 #

把原来无参数的url-loader调用，替换成带明确规则的配置块：

{
  test: /\.(jpg|png|jpeg|gif)$/,
  exclude: path.resolve(__dirname, './src/assets'), // 排除直接走拷贝流程的静态资源，避免重复处理
  use: {
    loader: 'url-loader',
    options: {
      // 小于8KB的图片转base64内联，超过的走文件输出
      limit: 8 * 1024,
      // 输出的文件存放路径：统一放在dist/img/目录下，保留原文件名加8位hash
      name: 'img/[name].[hash:8].[ext]',
      // 资源引用的公共路径，匹配所有静态资源的相对引用规则
      publicPath: '../',
      // 关闭ES模块解析，解决和html-loader的格式冲突
      esModule: false
    }
  }
}

两个容易漏的关键配置：

• esModule: false：新版url-loader默认开启ES模块导出，和html标签里的字符串类型src不兼容，会触发重复生成hash文件的问题
• publicPath：如果不配这个值，生成的引用路径会从页面当前所在的层级找资源，本来存在dist/img/下的文件，会被html从dist/同级路径查找，直接触发404

2. 修正html-loader的解析规则 #

把原来的html-loader配置加上白名单限制，避免无意义的全量资源扫描：

{
  test: /\.html$/,
  use: [
    {
      loader: 'html-loader',
      options: {
        minimize: true,
        // 仅解析img标签的src属性，不做其他冗余的资源扫描
        attributes: {
          list: [
            {
              tag: 'img',
              attribute: 'src',
              type: 'src'
            }
          ]
        }
      }
    }
  ]
}

3. 调整静态资源拷贝逻辑 #

如果你的img1.png、img2.png、img3.png本身就是放在src/assets目录下的静态资源，不需要走webpack的loader处理流程，直接确认CopyWebpackPlugin的拷贝路径正确即可：

new CopyWebpackPlugin({
  patterns: [
    {
      from: './src/assets',
      to: './assets',
      noErrorOnMissing: true
    }
  ]
})

验证方式 #

重新执行npm run build，检查三个核心点：

• dist目录下不会再出现没有文件夹层级的随机名PNG文件
• dist/index.html里的img标签src路径，和实际文件所在的目录完全匹配
• 直接打开dist/index.html，三张图片可以正常加载

内容的提问来源于stack exchange，提问作者user15076617