Webpack output.uniqueName 是什么？如何用唯一名称防止多个 Webpack 运行时冲突？

在一个页面里同时跑多个 Webpack 打包出来的应用，听起来没什么问题，实际部署后却经常出现诡异的现象：某个应用的异步 chunk 加载报 404 或者加载到了别的应用的 chunk、全局变量 webpackJsonp 被后来者覆盖、微前端场景下子应用互相干扰。这些问题的根源基本都指向同一个点——多个 Webpack 运行时（runtime）使用了相同的全局名称。Webpack 提供的 output.uniqueName 配置就是用来解决这件事的，它会为每个构建产物生成唯一的运行时命名空间，避免彼此踩踏。

一、多个 Webpack 运行时为什么会产生冲突

要理解冲突的成因，得先知道 Webpack 运行时在浏览器里是怎么工作的。Webpack 打包产物中除了业务代码，还包含一段运行时代码，负责模块管理、chunk 加载、异步依赖协调等。在 Webpack 4 及更早的版本里，这段运行时会通过一个名为 webpackJsonp 的全局数组来注册各个 chunk：每个 chunk 文件执行时会把自己 push 到这个全局数组上，运行时再从数组里取出并初始化模块。

问题就出在这里。如果页面上有两个应用都是用 Webpack 打包的，而且都没有做任何命名隔离，它们会共用 window.webpackJsonp 这一个全局变量。后加载的应用会覆盖或污染先加载应用的注册表，导致先加载的应用在异步加载 chunk 时找不到自己的模块，或者拿到对方的模块 ID，抛出 Cannot read property 'call' of undefined 之类的奇怪错误。

这种冲突在以下场景中尤其常见：微前端架构中主应用与多个子应用同页运行、一个大型门户页嵌入了多个团队各自打包的 widget、老系统逐步迁移时新旧版本共存。凡是同页面出现两份以上 Webpack runtime，就必须考虑命名隔离。

二、output.uniqueName 的作用与配置方法

output.uniqueName 是 Webpack 5 引入的统一配置项，用来给当前构建的运行时指定一个唯一的命名空间。设置之后，Webpack 会用它来生成全局变量的名称，例如默认情况下 webpackChunk 前缀会变成 webpackChunk你的应用名，HMR 的全局挂载点、chunk 加载相关的全局回调也都会带上这个前缀。这样一来，即使两个应用同页运行，各自的 chunk 注册数组也是不同的全局变量，互不干扰。

基础配置非常简单，在 webpack 配置文件中加上这一行即可：

const path = require('path');

module.exports = {
  mode: 'production',
  entry: './src/index.js',
  output: {
    path: path.resolve(__dirname, 'dist'),
    publicPath: '/sub-app/',
    filename: 'bundle.js',
    // 为当前应用指定唯一名称，建议与 package.json 的 name 保持一致
    uniqueName: 'sub-app-order'
  }
};

需要注意的是，uniqueName 会作为全局标识符的一部分，因此值必须是合法的 JavaScript 标识符字符（字母、数字、下划线、$），不要包含中划线开头或特殊符号。实践中通常直接使用 package.json 中的包名。如果你配置了 output.library，Webpack 默认会用 library.name 作为 uniqueName 的回退值，但显式声明永远比依赖隐式行为更可靠。

还有一个容易忽略的细节：uniqueName 也会影响一些其他输出的命名，比如为 module federation 生成的共享作用域、script type="text/json" 的数据挂载点等。所以在微前端 + 模块联邦的场景下，主应用和每个子应用都应该各自设置不同的 uniqueName，这是保证 remote 与 host 正常通信的前提之一。

三、从 Webpack 4 的 jsonpFunction 迁移到 uniqueName

在 Webpack 4 时代，解决这个问题的配置叫 output.jsonpFunction，它只控制 chunk 注册用的全局函数名：

// Webpack 4 的旧写法，已不推荐
module.exports = {
  output: {
    jsonpFunction: 'webpackJsonpOrderApp'
  }
};

升级到 Webpack 5 之后，jsonpFunction 已被废弃，取而代之的就是 uniqueName。两者最大的区别在于覆盖范围：jsonpFunction 只隔离 chunk 注册的全局变量，而 uniqueName 是一个统一的命名空间，会同时作用于 chunk 加载、HMR、模块联邦等所有需要全局挂载的场景，隔离得更彻底。如果你还在用旧配置，Webpack 5 会给出弃用警告，建议统一改成：

// Webpack 5 推荐写法
module.exports = {
  output: {
    uniqueName: 'order-app'
  }
};

如果项目因为依赖锁死暂时无法升级 Webpack，也可以在 Webpack 4 中继续使用 jsonpFunction，但要确保页面中所有 Webpack 产物的该值都互不相同，最好建立一个团队级的命名规范清单，把每个应用的名称登记下来，避免后期新应用无意中撞名。

四、微前端场景下的完整实践建议

在微前端架构中，仅靠 uniqueName 只能解决全局变量冲突这一个维度，完整的隔离方案还需要配合其他配置。以下是一个子应用相对完整的输出配置示例：

const { ModuleFederationPlugin } = require('webpack').container;
const packageJson = require('./package.json');

module.exports = {
  output: {
    publicPath: '//cdn.example-static.com/order/',
    uniqueName: packageJson.name, // 例如 order-app
    // 隔离 HMR websocket 的名称，避免本地开发时多个应用抢占
    hotUpdateGlobal: 'webpackHotUpdate' + packageJson.name
  },
  plugins: [
    new ModuleFederationPlugin({
      name: 'orderApp',
      filename: 'remoteEntry.js',
      exposes: {
        './OrderList': './src/components/OrderList'
      },
      shared: { react: { singleton: true }, 'react-dom': { singleton: true } }
    })
  ]
};

除了配置层面，还有两点实践建议。第一，uniqueName 的命名最好与 CI/CD 中的产物目录、CDN 路径对应起来，形成一对一关系，方便排查问题时快速定位是哪个应用在页面上抛错。第二，在 qiankun 这类微前端框架中，子应用的 JS 通常在沙箱中执行，全局变量冲突被框架部分屏蔽，但 uniqueName 依然建议设置，因为沙箱在 sandbox: false 或某些逃逸场景下依然会暴露问题，提前隔离成本几乎为零。

总结一下，output.uniqueName 是 Webpack 5 中处理多运行时共存问题的标准答案：它统一取代了旧的 jsonpFunction，用一个配置项隔离了所有需要全局命名的运行时挂载点。只要页面上可能出现两份以上的 Webpack 产物，无论是现在还是可预见的将来，都建议在构建配置中显式写上这个字段，把冲突隐患消灭在打包阶段。

WebpackuniqueName运行时冲突修改时间：2026-09-13 19:14:50