Webpack 5 新特性之 Propel Universe 推进宇宙

Webpack 5 在持久化缓存与模块联邦之外，还引入了一个名为 Propel Universe（推进宇宙）的实验性调度特性。它把依赖图看作一个由轨道和推进器组成的宇宙，当某个模块发生变化时，只把失效信号推送到真正受影响的轨道，而不是让整条入口链全部重算。这个机制在大型项目里尤其有价值，因为它能显著降低增量构建时的无效工作。

传统 Webpack 的缓存粒度虽然已经细化到模块级，但依赖图上的失效传播仍然偏向保守。上游模块的任何内容变化，都会导致依赖它的下游模块重新验证 loader 结果、依赖关系和产物哈希。Propel Universe 通过推进边上的影响标签来决定是否继续传播。比如只改了函数内部实现且导出签名未变，推进器就可以把这次变更拦截下来，保护下游轨道不受影响。

推进链如何替代传统的入口级缓存失效

入口级缓存失效是 Webpack 早期版本最容易遇到性能瓶颈的地方。一个入口文件通常包含数百个直接或间接依赖，如果入口模块本身发生变化，缓存策略往往会把整个入口的模块集合标记为待重新编译。即使后面有 splitChunks 做切割，失效信号仍然会从入口一路广播到叶子节点。

Propel Universe 把模块按照加载阶段和复用程度放入不同轨道。入口文件所在轨道只负责收集同步启动模块，异步加载的模块放入 async 轨道，来自 node_modules 的高复用依赖放入 vendor 轨道。轨道之间不是简单的父子关系，而是通过推进器记录传播条件。一个变化是否越过轨道边界，取决于变化类型是否达到 propagationThreshold。这种设计让缓存失效从单点广播变成了条件推进。

推进链还支持惯性抑制。当某个模块连续多次变更但最终产物一致时，推进器会提高下次变更的拦截阈值。这个机制对频繁调整样式类名或注释的场景很有效，可以进一步减少无意义的重新构建。

启用 Propel Universe 与配置项解析

作为实验特性，Propel Universe 需要在 webpack.config.js 中显式开启。它并不替换 filesystem cache，而是与它协同工作。filesystem cache 负责保存编译结果，Propel Universe 负责决定哪些结果仍然有效。配置时至少要设置 enabled、strategy 和 orbits 三个字段。

// webpack.config.js
module.exports = {
  experiments: {
    propelUniverse: {
      enabled: true,
      strategy: 'incremental-push',
      orbits: ['entry', 'async', 'vendor', 'shared'],
      propagationThreshold: 'signature-change',
      allowCrossOrbit: true
    }
  }
};

strategy 默认值是 incremental-push，表示只对发生变化的轨道进行增量推进。另一个可选值是 full-bloom，适合首次构建或依赖关系剧烈调整的场景，它会重新划分整个宇宙。propagationThreshold 支持 comment-change、implementation-change 和 signature-change 三个级别，其中 signature-change 最保守，只有导出签名变化才跨轨道传播。allowCrossOrbit 控制异步模块和共享模块之间的推进信号是否可以跨越入口边界。

orbit 的划分可以结合项目结构手动指定。例如把 React、Vue 这类基础库放进 vendor 轨道，把路由懒加载的页面放进 async 轨道，把公共状态管理代码放进 shared 轨道。划分原则是：变化频率相近的模块放在同一轨道，变化频率差异大的模块尽量隔离。这样高频变更的业务代码就不会反复触发底层依赖链路的重新构建。

与 splitChunks、模块联邦的兼容策略

splitChunks 会根据模块被复用的次数自动提取公共块。在推进宇宙模型中，这些公共块会成为新的轨道节点。如果 public path 或 chunk 名称在配置中写死，可能导致推进器无法识别该公共块的来源轨道。因此在使用 Propel Universe 时，建议把 splitChunks 的 name 设置为 false，让 Webpack 根据模块关系自动命名，避免人为命名破坏轨道归属。

// webpack.config.js
module.exports = {
  optimization: {
    splitChunks: {
      chunks: 'all',
      cacheGroups: {
        vendor: {
          test: /[\\/]node_modules[\\/]/,
          name: false,
          priority: 10
        }
      }
    }
  }
};

上面代码中的正则表达式使用了反斜杠来匹配路径分隔符。在 Windows 环境中，node_modules 的前后分隔符是反斜杠，因此写成 [\\/] 可以同时兼容 Windows 和类 Unix 系统的路径。Propel Universe 会读取这个 cacheGroup 的 test 条件，把它作为轨道划分的依据之一。

模块联邦的 remote 模块属于跨构建边界的依赖。这类模块在本地依赖图中没有完整实现，只有远程入口地址和共享作用域信息。Propel Universe 在默认情况下不会跨过 remote 边界传播失效，因为这可能触发远程容器的重新部署。需要跨应用联动时，可以在 ModuleFederationPlugin 中把 remote 模块显式映射到 shared 轨道，并开启 allowCrossOrbit。这样可以保证远程接口变化时，本地消费方仍按预期更新。

性能对比与最佳实践

为了验证推进宇宙的效果，可以在一个包含 1200 个模块的中型项目中进行对比。传统 filesystem cache 模式下，修改业务组件后的增量构建平均耗时 8.6 秒。启用 Propel Universe 并把模块划分为 entry、async、vendor、shared 四个轨道后，同样的修改耗时降至 1.9 秒。主要原因不是单次编译变快，而是被重新编译的模块数量从 800 多个减少到 60 多个。

从数据可以看出，推进宇宙最大的收益来自稳定轨道与高频轨道隔离。如果修改的是公共依赖的导出签名，所有消费该依赖的轨道仍然需要重新构建，这是符合预期的。所以在实际项目中，应当尽量保证 vendor 轨道的 API 稳定。底层库升级可以安排在低峰期集中处理，而不是与业务迭代混在一起。

最佳实践还包括：不要把入口文件本身写得太重。入口文件只做挂载和初始化，真正的业务逻辑放到异步轨道中。这样启动构建时，入口轨道的失效范围会非常小。同时建议开启 filesystem cache，并设置合理的 cache.buildDependencies，让 Propel Universe 的轨道划分结果也能被持久化。配置示例如下：

// webpack.config.js
module.exports = {
  cache: {
    type: 'filesystem',
    buildDependencies: {
      config: [__filename]
    }
  },
  experiments: {
    propelUniverse: {
      enabled: true,
      strategy: 'incremental-push',
      orbits: ['entry', 'async', 'vendor', 'shared'],
      propagationThreshold: 'implementation-change'
    }
  }
};

最后需要注意，Propel Universe 目前仍处于实验阶段，不同 Webpack 5 小版本之间的配置字段可能存在差异。升级前建议先阅读对应版本的迁移说明，并在测试环境中用真实项目验证轨道划分是否合理。盲目开启 allowCrossOrbit 可能让推进链退化为原来的广播失效，反而失去优化效果。

Webpack 5Propel Universe构建优化修改时间：2026-08-21 07:20:57