在 Webpack 的模块热替换（HMR）机制中，每一次代码变更并不会重新打包整个应用，而是生成体积很小的补丁文件，由浏览器通过 WebSocket 通知后按需拉取。这些补丁文件具体叫什么名字、放在什么路径下，完全由配置项 output.hotUpdateChunkFilename 决定。很多团队在搭建多页应用或者微前端基座时，发现子应用之间的热更新会相互干扰，其实并不是 HMR 本身有缺陷，而是没有意识到这个文件名模板需要按场景调整。
hotUpdateChunkFilename 的基础用法与占位符
output.hotUpdateChunkFilename 是 Webpack 输出配置中的一项字符串模板，用来定义热更新过程中生成的 Chunk 补丁文件名称。它的默认值等价于 [id].[fullhash].hot-update.js，其中 [id] 代表 Chunk 的编号，[fullhash] 是本次编译的完整哈希。当开发者启动 webpack serve 并修改源码时，Webpack 会在内存文件系统中按照该模板写出类似 0.abc123.hot-update.js 的文件，随后推送给浏览器。
除了默认的 [id] 与 [fullhash]，该配置还支持若干占位符。例如 [hash] 表示基于内容生成的短哈希，[runtime] 指代运行时代码所属 Chunk 的标识，[name] 则对应 Chunk 的名称（如果有的话）。我们还可以添加目录前缀，把热更新文件统一放到 hot/ 子目录中，避免和正式产物混在一起。下面是一段典型的 Webpack 配置代码，展示了如何自定义该字段：
const path = require('path');
module.exports = {
mode: 'development',
devServer: {
hot: true
},
output: {
filename: '[name].js',
// 将热更新Chunk放到hot目录下，并用name区分
hotUpdateChunkFilename: 'hot/[name].[fullhash].hot-update.js',
// 主热更新文件也建议同步调整
hotUpdateMainFilename: 'hot/[fullhash].hot-update.json'
}
};
使用 [name] 替代 [id] 的好处在于可读性更强，尤其在多入口项目中，你能直接从网络面板看到 hot/app.4f3a9c.hot-update.js 这样的命名，快速定位是哪个入口触发的更新。但需要注意，如果 Chunk 没有显式名称（如动态 import 产生的匿名块），[name] 会退化为数字 id，此时和 [id] 效果一致。
多实例与微前端下的命名冲突问题
在微前端架构里，主应用与多个子应用可能各自运行独立的 Webpack Dev Server，或者共用同一个编译实例但拥有不同入口。如果所有应用都采用默认的 hotUpdateChunkFilename，那么它们生成的热更新文件都会平铺在根路径，且文件名仅由 id 与 hash 构成。当子应用 A 和子应用 B 的 Chunk id 恰好重复（比如都是 0），且哈希碰撞或旧文件未及时清理时，浏览器就可能拉错补丁，导致热更新失效甚至页面崩溃。
解决思路之一是为每个子应用分配独立的路径前缀。例如主应用使用 hot/main/[id].[fullhash].hot-update.js，订单子应用使用 hot/order/[id].[fullhash].hot-update.js。这样即便 id 相同，由于目录隔离，文件不会彼此覆盖。在 Module Federation 场景下，远程模块的更新文件也应通过类似规则区分，避免宿主与远程之间产生命名交叉。下面的配置演示了通过环境变量动态拼接前缀：
const appName = process.env.APP_NAME || 'main';
module.exports = {
output: {
hotUpdateChunkFilename: `hot/${appName}/[id].[fullhash].hot-update.js`,
hotUpdateMainFilename: `hot/${appName}/[fullhash].hot-update.json`
}
};
另一种常见误区是认为修改了 output.path 就能自动隔离热更新文件。实际上 output.path 只影响物理或内存中的基础目录，而 HMR 文件的最终 URL 仍由 hotUpdateChunkFilename 与 hotUpdateMainFilename 拼接而成。因此即便 path 不同，若模板字符串完全一致，在同源调试时依然可能由于浏览器缓存键相同而出错。建议在微前端本地联调时，将应用名写入模板，而非依赖 path 差异。
与 hotUpdateMainFilename 的协同及调试技巧
不少开发者只改了 hotUpdateChunkFilename，却忽略了 output.hotUpdateMainFilename。后者控制的是热更新清单文件（通常是 JSON），里面记录了本次更新涉及哪些 Chunk 及其对应的补丁路径。若两者前缀不一致，浏览器能拿到清单，却找不到清单里声明的 Chunk 文件，控制台会报 404。因此这两个配置必须配套修改，保持目录结构统一。
在调试阶段，可以故意把模板写成非法格式（如包含空格或未转义字符）来观察 Webpack 的报错信息，从而确认配置是否生效。正常情况下，Webpack 会在编译日志中输出 HMR 文件的写入路径。我们也可以借助浏览器开发者工具的 Network 面板，筛选 .hot-update. 请求，核对实际拉取的 URL 是否和配置模板吻合。如果发现路径带了多余斜杠或缺少前缀，多半是模板字符串拼接时少了斜杠，例如 hot${appName}/ 而非 hot/${appName}/。
此外，当项目从 Webpack 4 升级到 5 时，[hash] 与 [fullhash] 的语义发生了细微变化：Webpack 5 中 [hash] 不再等价于 [fullhash]，前者更偏向内容片段哈希。因此在老配置里写死的 [hash] 建议显式改为 [fullhash]，避免热更新文件名在升级后变短导致缓存策略异常。理解这些差异，才能让热更新 Chunk 文件名真正服务于稳定高效的本地开发体验。
WebpackhotUpdateChunkFilename热更新Chunk修改时间：2026-08-15 04:21:31