core-js 按需引入优化：useBuiltIns 'usage' 与 'entry' 模式的区别

在基于 Babel 构建的现代前端工程中，Polyfill 垫片配置是平衡“旧浏览器兼容性”与“产物打包体积”的核心枢纽。配置项 useBuiltIns: 'entry' 采用“目标环境驱动”机制，依据目标浏览器清单全量展开所有缺失垫片，侧重全局容错与第三方依赖安全；而 useBuiltIns: 'usage' 则依托“代码 AST 语法分析”，逐文件检测实际引用的新语法并精准按需注入，大幅缩减构建体积。本文将从编译底层机制、工程落地配置、边界陷阱排查及选型决策四个维度，全面阐释两者的核心差异。

图 0：core-js 按需引入两种主要模式的核心理念与产物特征对照

一、核心工作机制：从 AST 遍历到垫片注入

为了让使用 ECMAScript 新标准（如 Promise、Array.prototype.includes、Object.fromEntries）编写的代码能够安全运行在旧版浏览器中，构建工具链通常依赖 core-js 提供垫片。但在打包时，究竟如何把这些垫片打包进产物，由 @babel/preset-env 的 useBuiltIns 参数直接控制。

1.1 useBuiltIns: 'entry' 的全量替换逻辑

entry 模式是一种“粗粒度但高可靠”的解决方案。它的基本逻辑如下：

• 开发者必须在项目源码的全局唯一入口文件（例如 main.js 或 index.js）顶部，手动声明 import "core-js";（或细化为 core-js/stable）。
• Babel 在转译该入口文件时，遇到这一行静态导入语句，便会读取项目中配置的 Browserslist 目标环境清单。
• Babel 不会去审查业务代码里到底有没有写过 Promise 或 Array.includes，只要目标浏览器集合中存在不支持某个特性的浏览器，Babel 就会把这行单句 import 展开替换为几十乃至上百个具体微模块的导入（例如 import "core-js/modules/es.promise.js"、import "core-js/modules/es.array.includes.js" 等）。

其最大优势在于全局兜底。由于所有垫片在入口处就已经全部挂载到全局原型或全局对象上，即使项目引用的某个未经编译的第三方 npm 依赖包内部使用了高版本 API，也能正常运行不报错。

1.2 useBuiltIns: 'usage' 的精准扫描机制

与 entry 模式不同，usage 模式实现了真正意义上的“按需扫描与注入”：

• 源码入口中严禁手动写入 import "core-js";，否则依然会触发全量打包。
• Babel 会对纳入编译范围的每一个源码文件进行抽象语法树（AST）深度遍历。每当在某个文件中解析到 ES6+ 的内置全局对象（如 Set、Map）或实例方法（如 [].flat()）时，Babel 会立即查验目标浏览器是否原生支持该 API。
• 一旦判定目标环境缺失且当前文件确实调用了该语法，Babel 就会在当前文件的头部直接插入对应的单个垫片导入。最终由打包工具（如 Webpack、Rollup）将所有散落各处的垫片模块去重合并打包。

这种机制使得整个项目的 Polyfill 体积直接与业务实际使用的现代特性数量挂钩，避免将大量未使用的垫片强行塞入 Bundle。

二、实操配置落地：从依赖安装到代码改造

在实际项目中落地这两种方案时，必须严格遵守依赖版本对应关系与代码编写规范，避免因配置不匹配造成冗余报错。

2.1 依赖安装与版本规范

core-js 经历了 v2 到 v3 的重大架构重构。core-js@2 已经彻底停止维护，无法兼容 Array.prototype.flat、Promise.allSettled 等现代特性。现代工程必须使用 core-js@3，并安装在 dependencies（生产依赖）中：

# 安装 Babel 基础套件与 core-js 核心运行时
npm install @babel/core @babel/preset-env --save-dev
npm install core-js@3 regenerator-runtime --save

2.2 目标环境配置（.browserslistrc）

无论是 entry 还是 usage，垫片裁减的前提是明确“项目需要兼容哪些浏览器”。推荐在项目根目录创建 .browserslistrc：

# 兼容全球使用率高于 0.5% 的浏览器，以及主流浏览器的最后两个稳定版本
> 0.5%
last 2 versions
Firefox ESR
not dead
not ie <= 10

2.3 方案 A：落地 useBuiltIns: 'entry' 配置

如果项目选择 entry 模式，需在 babel.config.js 中配置 useBuiltIns: 'entry'，并显式指定 corejs: 3：

// babel.config.js
module.exports = {
  presets: [
    [
      '@babel/preset-env',
      {
        useBuiltIns: 'entry',
        corejs: { version: 3, proposals: true },
        modules: false // 保留 ES Module 供构建工具做 Tree Shaking
      }
    ]
  ]
};

同时，在项目的打包入口文件（如 src/index.js）最顶端添加垫片导入：

// src/index.js (必须放在第一行)
import "core-js/stable";
import "regenerator-runtime/runtime";

// 随后引入应用业务逻辑
import React from "react";
...

2.4 方案 B：落地 useBuiltIns: 'usage' 配置

如果追求极致的体积精简，将 useBuiltIns 修改为 'usage'：

// babel.config.js
module.exports = {
  presets: [
    [
      '@babel/preset-env',
      {
        useBuiltIns: 'usage',
        corejs: { version: 3, proposals: true },
        modules: false
      }
    ]
  ]
};

三、关键细节与边界隐患：usage 模式为何会“漏打”或“误打”？

尽管 usage 模式在体积上有明显优势，但很多团队在实际采用时却遭遇过线上低版本浏览器白屏。深入理解其技术边界是避免事故的前提。

3.1 原型链方法推断与“保守过度引入”

JavaScript 是弱类型动态语言。当开发者在代码中写下：

const isFound = dataset.includes(targetItem);

在静态编译阶段，Babel 仅根据 AST 只能观察到 dataset 正在调用 includes 方法，但无法确切得知 dataset 在运行时到底是一个 Array、一个 String，还是开发者自定义的一个普通对象。

为了保证代码在任何情况下都不会抛出 undefined is not a function，Babel 采取了保守注入策略：它会同时把 core-js/modules/es.array.includes 与 core-js/modules/es.string.includes 两个垫片模块全部注入当前文件。这种行为虽然带来了一定程度的轻微体积冗余，但属于合理的防御性妥协。

3.2 第三方依赖（node_modules）跳过编译引发的白屏风险

这是 usage 模式最容易诱发生产事故的死角。在通常的 Webpack 构建流水线中，为了提升构建性能，开发者通常会配置：

// webpack.config.js
rules: [
  {
    test: /\.m?js$/,
    exclude: /node_modules/, // 极其常见的构建规则
    use: 'babel-loader'
  }
]

一旦项目中引入了某个第三方 npm 库，而该库自身发布的代码中使用了较新的 ES 特性（例如 String.prototype.replaceAll），且该库作者并没有在发包前自行打包内置 polyfill。

在 entry 模式下，由于整个运行环境在应用启动时就被注入了全套垫片，该第三方库在旧浏览器中能够安然运行。但在 usage 模式下：

1. 业务自身的代码没有写过 replaceAll，因此 Babel 不会在业务代码中注入该垫片；
2. 第三方库位于 node_modules 中，被 babel-loader 的 exclude 规则直接跳过，Babel 根本没有机会扫描该库的 AST。

结果就是在目标低版本浏览器上运行时，第三方库执行到该代码时抛出 TypeError: data.replaceAll is not a function，导致整页崩溃。

3.3 动态反射与动态属性访问（eval / window[api]）

AST 扫描完全基于静态字面量分析。如果代码中存在以下动态调用模式：

const method = 'flatMap';
const result = list[method](item => [item, item * 2]);
eval("Reflect.ownKeys(targetObj)");

Babel 无法在编译期计算出 list[method] 指向的是 ES2019 的 Array.prototype.flatMap，因此该特性在 usage 模式下会被完全遗漏。

四、工程选型指南与方案对比矩阵

在实际架构设计中，不存在绝对的“最优解”，只有与项目约束相契合的工程折中。下表全面量化了 useBuiltIns 两种模式以及库开发方案的核心特征：

4.1 具体选型建议

• 首选推荐 useBuiltIns: 'usage' 的场景： 面向移动端、C 端 Web 应用，首屏加载时间和 JS 资源体积（Bundle Size）是关键核心指标。此时应果断采用 usage 模式，并将体积压缩至极限。 配套防护：若排查发现某第三方依赖确有未编译的高版本语法，只需在构建工具中将该依赖加入 babel-loader 的 include 白名单，或在入口文件处针对性地单项导入对应的 core-js/modules/es.xxx。
• 建议保留 useBuiltIns: 'entry' 的场景： 大型中后台业务系统、多团队协同开发的历史遗留系统、或者引入了海量老旧且难以追溯源码的第三方组件库。由于首屏体积并非首要矛盾，而跨团队排查“因第三方依赖漏打 Polyfill 导致的隐蔽白屏”时间成本极高，采用 entry 全量垫片方案能够以最低的维护成本确保整站稳定性。
• 基础库与 SDK 开发的红线规范： 如果你正在编写一个发布给他人使用的 npm 库，无论 entry 还是 usage 都严禁使用！因为它们会修改全局对象和内置原型，导致引用你类库的宿主项目出现全局环境冲突。库开发必须选用 @babel/plugin-transform-runtime 并启用 corejs: 3，以局部别名导入的形式实现纯净兼容。