Webpack4中HtmlWebpackPlugin与html-loader配合的变量及文件引入问题

我之前也碰到过这个一模一样的问题，核心矛盾在于html-loader和HtmlWebpackPlugin的模板插值规则冲突：html-loader默认会解析所有${}格式的内容，把它当成普通JavaScript变量处理，但htmlWebpackPlugin这个变量只存在于HtmlWebpackPlugin的模板上下文里，所以才会抛出"htmlWebpackPlugin未定义"的错误。

下面给你两种解决方案，既能满足加载子HTML、传递变量的需求，又能适配你想要的语法风格：

方案一：统一使用${}语法（自定义模板解析） #

这个方案让html-loader只负责处理${require(...)}格式的HTML片段引入，把其他${}留给我们自定义的模板函数来解析HtmlWebpackPlugin的变量。

1. 调整webpack.config.js配置 #

const HtmlWebpackPlugin = require('html-webpack-plugin');
const fs = require('fs');
const path = require('path');

module.exports = {
  // 你的基础配置：entry、output等
  module: {
    rules: [
      {
        test: /\.html$/,
        use: [
          {
            loader: 'html-loader',
            options: {
              interpolate: 'require', // 仅解析${require(...)}格式的资源引入
              esModule: false // Webpack4中需要关闭ES模块导出，否则require返回的是模块对象而非字符串
            }
          }
        ]
      }
    ]
  },
  plugins: [
    new HtmlWebpackPlugin({
      // 自定义模板解析逻辑，用ES6模板字符串处理变量
      templateContent: (templatePath) => {
        const templateStr = fs.readFileSync(path.resolve(__dirname, templatePath), 'utf8');
        return (data) => {
          // 暴露HtmlWebpackPlugin的上下文变量
          const { htmlWebpackPlugin } = data;
          // 用eval执行ES6模板字符串，注意：仅在自己可控的项目中使用，避免不可信模板的安全风险
          return eval(`\`${templateStr}\``);
        };
      },
      template: './src/index.html', // 你的主模板文件路径
      title: '我的自定义页面标题', // 要传递给模板的变量
      // 其他HtmlWebpackPlugin配置（如minify、filename等）
    })
  ]
};

2. 在index.html中使用统一的${}语法 #

<!doctype html>
<html>
<head>
  <title>${htmlWebpackPlugin.options.title}</title>
</head>
<body>
  <!-- 引入子HTML片段 -->
  ${require('./partials/header.html')}
  
  <main>
    <p>这里是页面主内容</p>
  </main>
  
  ${require('./partials/footer.html')}
</body>
</html>

方案二：使用HtmlWebpackPlugin原生EJS语法（推荐） #

这个方案不需要自定义模板解析逻辑，利用HtmlWebpackPlugin原生支持的EJS语法处理变量，同时用html-loader加载子HTML片段，配置更简单也更安全，是官方推荐的用法。

1. 调整webpack.config.js配置 #

const HtmlWebpackPlugin = require('html-webpack-plugin');

module.exports = {
  // 你的基础配置：entry、output等
  module: {
    rules: [
      {
        test: /\.html$/,
        use: [
          {
            loader: 'html-loader',
            options: {
              esModule: false // 关闭ES模块导出，让require直接返回HTML字符串
            }
          }
        ]
      }
    ]
  },
  plugins: [
    new HtmlWebpackPlugin({
      template: './src/index.html', // 主模板文件路径
      title: '我的自定义页面标题', // 要传递的变量
      // 其他HtmlWebpackPlugin配置
    })
  ]
};

2. 在index.html中混合使用EJS语法与require引入 #

<!doctype html>
<html>
<head>
  <!-- 用EJS语法读取HtmlWebpackPlugin传递的变量 -->
  <title><%= htmlWebpackPlugin.options.title %></title>
</head>
<body>
  <!-- 用require引入子HTML片段 -->
  <%= require('./partials/header.html') %>
  
  <main>
    <p>这里是页面主内容</p>
  </main>
  
  <%= require('./partials/footer.html') %>
</body>
</html>

方案选择建议 #

方案二更值得推荐，因为它不需要自定义模板解析逻辑，避免了eval带来的潜在安全风险，同时完全符合HtmlWebpackPlugin的设计规范，后续维护也更省心。两种方案都能完美实现你的两个需求：加载其他HTML文件到index.html，以及向模板传递自定义变量。

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