PUG结合Webpack使用loader加载图片的变量引用问题

问题背景回顾 #

之前项目里用WebpackCopyPlugin复制图片，Pug里用绝对路径引用一切正常。现在想改用loader处理图片，按文档用img(src=require('./img.png'))的写法，却遇到了几个异常场景：

场景分析与解决方案 #

场景1：无变量的require正常，但无法满足变量需求

原因：Webpack是静态打包工具，只能准确解析静态的、明确的路径，这种写法能让Webpack精准定位到文件，所以没问题，但没法动态传文件名。

解决思路：用Webpack支持的动态require写法，同时给Webpack明确的上下文范围，避免过度打包。

场景2：模板字符串带变量，开发正常但构建时复制所有图片

原因：当你写require(@img/${fileName})时，Webpack静态分析无法确定运行时fileName的值，所以会默认把@img目录下所有符合file-loader测试规则的文件都打包（jp2、jxr没被复制是因为你的file-loader规则里没包含这些后缀）。

解决办法：

1. 扩展file-loader的测试规则，包含所有你需要的图片格式：

   { 
     test: /\.(png|jpg|gif|svg|jp2|jxr)$/, // 补上jp2、jxr格式
     use: [
       { 
         loader: 'file-loader',
         options: {
           esModule: false,
           name: '[name].[ext]',
           outputPath: `${PATHS.assets}/img`,
           context: path.resolve(PATHS.src, 'assets/img'), // 明确上下文目录，帮助Webpack精准解析
         },
       },
     ],
   },
   

2. 如果不想打包整个目录的文件，可以用require.context精准控制：
   在Pug里这样写：

   // 提前定义上下文：只加载@img下的指定格式文件，支持子目录
   - const imageContext = require.context('@img/', true, /\.(png|jpg|gif|svg)$/)
   - let fileName = '1-1.png'
   img(src=imageContext(`./${fileName}`))
   

   这样Webpack只会打包require.context匹配到的文件，而非整个目录。

场景3：变量包含路径片段，报错Error: Callback was already called.

原因：这种写法会让Webpack的路径解析逻辑混乱，加上pug-loader和vue-loader的resourceQuery处理可能存在冲突，导致重复回调。

解决办法：

1. 尽量使用别名+动态子路径的写法，不要把完整相对路径放进变量：

   - let subDir = 'icons/logo'
   - let fileName = 'boto.agency.b.svg'
   img(src=require(`@img/${subDir}/${fileName}`))
   

2. 升级pug-loader、file-loader到最新版本，避免版本兼容问题。
3. 可以尝试临时去掉pug-loader的oneOf规则，直接用pug-loader测试，排查是否是规则冲突导致的问题。

场景4：拼接变量后传入require，报错Cannot find module

原因：Webpack静态分析无法识别完全动态拼接的路径（比如require(path)，其中path是拼接后的字符串），它需要明确的上下文前缀才能定位文件。

解决办法：把固定的上下文部分写在require的字符串里，只让变量替换动态部分：

- let basePath = '@img/' // 固定上下文前缀
- let fileName = '1-1.png'
img(src=require(basePath + fileName)) // 不要先拼接成完整变量再传入require

这样Webpack能识别到上下文是@img/，就能正确解析动态的文件名部分。

额外优化建议 #

• 如果你还需要保留部分图片用CopyWebpackPlugin复制（比如静态资源），可以在CopyWebpackPlugin里用exclude排除已经用loader处理的文件，避免重复复制。
• 可以考虑用url-loader替代file-loader，小图片转base64，减少HTTP请求：

  { 
    test: /\.(png|jpg|gif|svg|jp2|jxr)$/,
    use: [
      { 
        loader: 'url-loader',
        options: {
          esModule: false,
          limit: 8192, // 小于8k的图片转base64
          name: '[name].[ext]',
          outputPath: `${PATHS.assets}/img`,
          context: path.resolve(PATHS.src, 'assets/img'),
        },
      },
    ],
  },
  

内容的提问来源于stack exchange，提问作者Михаил Журавлёв