Webpack5 devServer如何监听Partial文件变更？

DevOps 小满

2026-8-25

Webpack-dev-server 无法监听 HTML Partial 文件触发 HMR 的解决方案

问题场景

使用配置了hot: true的webpack-dev-server，通过html-webpack-plugin的templateParameters传入自定义Partial实现HTML复用。修改页面HTML文件时HMR正常触发，但修改Partial文件（如header.html）时，无法触发页面刷新或HMR，希望无需额外Partial插件（如Handlebars），实现监听所有Partial文件，修改后自动更新所有引用该Partial的页面。

现有代码片段

Partial定义

const PARTIALS = {}
fs.readdirSync(path.join(__dirname,'src','partials')).forEach((file) => {
    PARTIALS[file.replace(/.html/,'')] = fs.readFileSync(`./src/partials/${file}`,{encoding:'utf-8'})
})

HtmlWebpackPlugin配置

plugins:[
    ...PAGES.map(page => new HtmlWebpackPlugin({
        template:`${PAGES_DIR}/${page}`,
        templateParameters:{
            PARTIALS
        },
        filename:`./${page}`,
        chunks:[page.replace(/\.html/,'')],
        minify:{
            collapseWhitespace:isProd
        }
    })),

devServer配置

devServer:{
    port:4200,
    compress:true,
    hot:true,
    watchFiles:['src/**/*.html'],
},

HTML中调用Partial的方式

<%= PARTIALS.header %>
    <div class="wrapper">
        <main class="main">
            <div class="wrapper"><h1>Webpacks</h1></div>
            <div class="logo"></div>
            <div class="card"><h2>SCSS</h2></div>
        </main>
<%= PARTIALS.footer %>

解决方案

方案1：通过HtmlWebpackPlugin钩子手动添加Partial依赖

Webpack需要明确知晓页面模板与Partial文件的依赖关系，才能在Partial修改时触发页面重编译。可以利用html-webpack-plugin的编译钩子，为每个页面添加Partial文件作为依赖：

先收集所有Partial文件的绝对路径：

const partialFiles = fs.readdirSync(path.join(__dirname, 'src', 'partials')).map(file => 
  path.resolve(__dirname, 'src', 'partials', file)
);

在webpack插件配置中添加依赖处理逻辑：

plugins:[
    ...PAGES.map(page => new HtmlWebpackPlugin({
        template:`${PAGES_DIR}/${page}`,
        templateParameters:{
            PARTIALS
        },
        filename:`./${page}`,
        chunks:[page.replace(/\.html/,'')],
        minify:{
            collapseWhitespace:isProd
        }
    })),
    // 自定义插件添加Partial依赖
    {
      apply: (compiler) => {
        compiler.hooks.compilation.tap('HtmlPartialDependency', (compilation) => {
          compilation.hooks.htmlWebpackPluginBeforeAssetTagGeneration.tapAsync(
            'AddPartialDependencies',
            (data, callback) => {
              // 将所有Partial文件加入当前页面的依赖列表
              partialFiles.forEach(file => {
                compilation.fileDependencies.add(file);
              });
              callback(null, data);
            }
          );
        });
      }
    }
],

配置完成后，Webpack会监听所有Partial文件，任意Partial修改时，所有页面都会重编译，devServer会自动触发页面刷新。

方案2：修改Partial导入方式，让Webpack自动识别依赖

当前用fs.readFileSync同步读取Partial内容，Webpack无法识别这类静态读取的文件依赖。改用require导入Partial，并配置Webpack处理HTML文件，让Webpack自动追踪依赖：

配置webpack处理Partial HTML文件：

webpack 5+ 可直接使用asset模块：

module: {
  rules: [
    {
      test: /\.html$/,
      include: path.resolve(__dirname, 'src/partials'),
      type: 'asset/source'
    }
  ]
}

webpack 4及以下需安装raw-loader后配置：

module: {
  rules: [
    {
      test: /\.html$/,
      include: path.resolve(__dirname, 'src/partials'),
      use: 'raw-loader'
    }
  ]
}

更新PARTIALS的定义，用require导入：

const PARTIALS = {};
fs.readdirSync(path.join(__dirname, 'src', 'partials')).forEach((file) => {
  const partialName = file.replace(/\.html/, '');
  // require导入让Webpack自动添加文件依赖
  PARTIALS[partialName] = require(`./src/partials/${file}`);
});

保留devServer.watchFiles的src/**/*.html配置，确保devServer监听Partial文件。

这种方式下，Webpack会自动跟踪每个Partial的依赖关系，Partial修改时，所有引用它的页面会重编译并触发HMR或刷新。

注意事项

开发环境下避免提前将PARTIALS编译为静态字符串，确保Webpack能追踪到文件依赖。
若HMR仍未生效，可尝试将hot: true替换为liveReload: true作为备选方案。

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

Webpack5 devServer如何监听Partial文件变更？

问题场景 #

现有代码片段 #