Webpack 5 的 Entrance Universe 入口宇宙特性是什么？如何玩转新一代入口配置？

在传统 Webpack 项目中，entry 配置往往是一行静态的对象或字符串，随着业务膨胀，这个对象会越来越长，维护成本也越来越高。Webpack 5 在入口体系上做了一次较为深度的重构，社区里有人把它形象地称为 Entrance Universe（入口宇宙），意思是入口不再是孤立的点，而是一个可以动态扩展、相互关联的体系。这篇文章就来聊聊这套入口设计到底解决了什么问题，以及在真实项目中怎么用。

一、传统入口配置的痛点在哪里

先看一个典型的老式多页面项目配置。假设我们有十个页面，每个页面一个入口，entry 大概长这样：

module.exports = {
  entry: {
    home: './src/pages/home/index.js',
    about: './src/pages/about/index.js',
    user: './src/pages/user/index.js'
    // 后面还有十几个，每加一个页面都要改这里
  }
};

这种写法的问题很明显。第一，入口列表是硬编码的，每新增一个页面都需要手动修改配置文件，团队协作时经常出现合并冲突。第二，入口之间无法表达依赖关系，如果两个页面共享一段初始化逻辑，只能在业务代码里手动 import，构建工具帮不上忙。第三，入口的粒度是死的，想按环境动态裁剪某些入口，只能写一堆 if else 在配置文件里打补丁。

更深层的问题在于，传统的 entry 只是一个字符串到模块的映射，它不携带任何元信息。构建器无法知道某个入口是给服务端渲染用的还是纯客户端用的，也无法知道某个入口是否允许被拆分成更小的 chunk。Entrance Universe 的核心思路，就是让入口从“一个字符串”升级为“一个携带完整描述信息的对象”，并通过依赖入口机制让入口之间建立联系。

二、Entrance Universe 的核心设计：入口即对象，依赖可声明

Webpack 5 中，entry 的值从一个简单的字符串变成了一个 EntryDescription 对象，支持 import、dependOn、filename、runtime、chunkLoading 等一系列字段。这就是入口宇宙的基石：每个入口都是一个自描述的节点，节点之间通过 dependOn 声明依赖，形成一个有向的图结构。看下面这个例子：

module.exports = {
  entry: {
    sharedRuntime: {
      import: './src/shared/bootstrap.js',
      runtime: 'shared'
    },
    home: {
      import: './src/pages/home/index.js',
      dependOn: 'sharedRuntime',
      filename: 'pages/[name].[contenthash].js'
    },
    about: {
      import: './src/pages/about/index.js',
      dependOn: 'sharedRuntime',
      filename: 'pages/[name].[contenthash].js'
    }
  }
};

这段配置里做了两件关键的事。其一，通过 runtime: 'shared' 把运行时代码抽成一个独立的共享 chunk，避免每个入口都打包一份 webpack runtime。其二，dependOn 声明 home 和 about 依赖 sharedRuntime 入口，Webpack 会保证被依赖的入口先于当前入口加载，且共享的模块只被提取一次。在十个以上入口的项目里，仅 runtime 去重这一项就能减少几十 KB 的重复代码。

需要注意的是，dependOn 不允许出现循环依赖。如果 A 依赖 B、B 又依赖 A，构建时会直接报错。这个限制是刻意设计的，因为入口之间的依赖图必须是 DAG（有向无环图），Webpack 才能确定稳定的加载顺序。另外，被 dependOn 指向的入口本身也可以有自己的 import 和 chunkLoading 配置，链式传递是支持的。

三、动态生成入口：让入口列表自动化

解决硬编码问题最实用的手段是动态扫描。结合 Node.js 的 fs 模块，我们可以在构建启动时自动扫描 pages 目录，为每个目录生成一个入口节点：

const fs = require('fs');
const path = require('path');

function generateEntries(pagesDir) {
  const entries = {};
  const shared = { import: './src/shared/bootstrap.js', runtime: 'shared' };

  for (const dir of fs.readdirSync(pagesDir)) {
    const entryFile = path.join(pagesDir, dir, 'index.js');
    if (fs.existsSync(entryFile)) {
      entries[dir] = {
        import: path.relative(__dirname, entryFile),
        dependOn: 'sharedBootstrap',
        filename: 'pages/[name].[contenthash].js'
      };
    }
  }
  return { sharedBootstrap: shared, ...entries };
}

module.exports = {
  entry: generateEntries(path.resolve(__dirname, 'src/pages'))
};

这样配置之后，新增页面只需要建目录写代码，完全不用碰 webpack.config.js。更进一步，你还可以在扫描时读取每个页面目录下的 meta.json，把 publicPath、chunkLoading 这类差异化配置下放到页面级别，实现真正的按需定制。

在模块联邦场景下，动态入口的威力更明显。宿主应用可以在运行时通过 __webpack_init_sharing__ 配合远程容器的入口描述来挂载子应用，而构建期只需要暴露一个约定式的入口模板。入口宇宙这个名字的由来也正是如此：入口不再是构建配置里写死的几个字符串，而是一个可以在构建期动态展开、在运行时按需加载的扩展体系。

四、与 splitChunks 的协同及常见踩坑点

入口体系升级后，splitChunks 的策略也需要跟着调整。最常见的坑是同时使用 dependOn 和 splitChunks.chunks: 'all' 时，某些共享模块会被提取两次：一次进了 dependOn 声明的入口 chunk，一次进了 splitChunks 生成的公共 chunk。正确的做法是，公共业务模块交给 splitChunks 处理，而 dependOn 只负责那些必须保证加载顺序的初始化逻辑（比如 polyfill、全局配置写入），两者各司其职。

另一个高频坑是 filename 里的占位符。入口级 filename 支持 [name] 和 [contenthash]，但如果你在 entry 里写死了文件名，又会同时在 output 里配置了 filename，入口级的配置优先级更高。有些团队在 output 里统一配了 js/[name].js，结果某个入口自己写了 filename 导致产物散落在两个目录里，排查起来非常费劲。建议统一在入口级指定 filename，output 里只保留兜底配置。

最后提醒一点：升级到这套入口体系后，务必检查 optimization.runtimeChunk 的配置。如果已经通过 runtime: 'shared' 抽离了运行时，就不要再设置 runtimeChunk: 'single'，否则会产生冲突警告，甚至生成多余的 runtime 文件。用一个简单的表格总结一下各配置的分工：

五、总结

Entrance Universe 并不是某个全新的配置项名字，而是 Webpack 5 把入口从静态字符串升级为可描述、可依赖、可动态生成的对象体系之后，带来的一整套入口组织方式。核心抓手就三个：EntryDescription 对象让入口携带元信息，dependOn 让入口之间建立可控的加载关系，动态扫描让入口列表彻底告别手工维护。

如果你的项目入口数量在五个以下，老式写法问题不大；一旦页面规模上来，或者需要接入模块联邦这类运行时加载场景，尽早切换到对象式入口配置，配合 runtime 共享和 splitChunks 的合理分工，构建产物的体积和加载性能都会有可感知的改善。建议先在一个边缘页面上试点，验证 dependOn 与现有 splitChunks 策略没有冲突后，再全量推广。

Webpack 5Entrance Universe入口配置修改时间：2026-09-04 14:12:43