core-js v2 迁移到 v3 的破坏性变更与注意事项

一、包结构拆分与核心破坏性变更

core-js 在升级到 v3 时对底层架构进行了彻底的重构。过去 v2 采用单包容纳一切的做法，使得包体积与引用关系极为复杂，甚至在无污染垫片和全局垫片之间存在模糊的耦合。在 v3 中，这些设计缺陷被全面修正，带来了四项最关键的破坏性变更。

1. 彻底废弃 @babel/polyfill 并完成解耦

在 Babel 7.4.0 之前，绝大部分前端项目通过直接引入 @babel/polyfill 来实现浏览器垫片。然而，@babel/polyfill 本质上仅仅是将当时的 core-js@2 和 regenerator-runtime/runtime 进行打包合并，它不仅强制污染全局作用域，而且无法享受按需引入或新提案支持。

从 Babel 7.4.0 开始，官方宣布彻底废弃 @babel/polyfill。在 v3 时代，项目需要显式分开管理两部分能力：由 core-js 负责 ECMAScript 标准 API 与 Web API，由 regenerator-runtime 负责 async/await 及生成器语法转换。

2. 拆分独立无污染库：core-js-pure

在 v2 版本中，如果想要在不污染宿主原生对象原型的前提下使用垫片（例如开发公共类库或 SDK），通常会引用 core-js/library/...。这种内部目录的形式导致打包工具难以精确识别模块依赖，并且常常造成同一个库内同时混杂全局垫片与无污染垫片。

v3 将原先的 core-js/library 抽离成了完全独立的 npm 包 core-js-pure。若正在开发通用类库，所有无需修改宿主原型的垫片都必须统一从 core-js-pure 导入。

3. 内部引用路径大重构（淘汰 es6/es7 与 /fn/）

v2 的内部路径严格按照早期 ECMAScript 版本号划分，例如 core-js/es6/... 与 core-js/es7/...。随着 TC39 标准按年度发布，版本号划分模式已完全过时。v3 对此进行了彻底平铺与规范化：

• 废弃版本号目录：移除 core-js/es6 与 core-js/es7，全部统一整合为 core-js/es 或 core-js/stable。
• 移除 /fn/ 目录：在 v2 中按需引用函数垫片常写为 core-js/fn/array/flat，v3 已移除 /fn/，变更为 core-js/features/array/flat 或 core-js/actual/array/flat。
• 提案特性收敛：草案阶段（Stage 0 到 Stage 3）的提案统一归入 core-js/proposals/... 或 core-js/stage/...。

4. 补齐并重写 Web 标准 API

v2 虽然包含 core-js/web 模块，但仅支持 setTimeout、setInterval 和 setImmediate 等少数老旧补丁。现代前端应用常用的 URL、URLSearchParams 以及 queueMicrotask 等在 v2 中缺乏完整实现，导致很多团队必须额外引入 url-polyfill 等第三方库。

core-js v3 提供了完全符合 WHATWG 规范的 Web 标准实现。升级后，不再需要依赖混乱的第三方 URL 垫片，直接使用 core-js/web/url 或在全局配置中即可获得标准的 URL 构造与查询字符串解析行为。

二、Babel 工具链关键配置变更

绝大部分项目并不是手动编写 import "core-js/..."，而是通过 Babel 的预设或插件进行自动化按需注入。core-js 版本的跃迁直接改变了 Babel 工具链的配置行为。

1. @babel/preset-env 配置升级

在 v2 时代，在 @babel/preset-env 中开启 useBuiltIns: "usage" 或 useBuiltIns: "entry" 时，Babel 默认采用 v2 规则。升级到 v3 后，必须在配置中显式传入 corejs 选项，并明确指定大版本号。

如果不配置 corejs，Babel 7 会在终端打印警告：WARNING: We noticed you're using the 'useBuiltIns' option without specifying a 'corejs' version. Currently, we assume version 2.x...，并回退到 v2 逻辑，导致 v3 新增的方法无法被自动注入。

// babel.config.js (面向普通 Web 应用的推荐配置)
module.exports = {
  presets: [
    [
      "@babel/preset-env",
      {
        // usage: 按代码实际使用的 API 按需注入
        // entry: 根据 browserslist 在入口文件处全量注入匹配环境的垫片
        useBuiltIns: "usage",
        corejs: {
          version: 3,
          // 如果需要支持 Stage 阶段的草案语法（如 Object.hasOwn 等早期提案），设为 true
          proposals: true
        }
      }
    ]
  ]
};

2. @babel/plugin-transform-runtime 配置升级

对于 NPM 组件库或工具库，为了避免污染使用者的全局 window 或 Array.prototype，必须使用 @babel/plugin-transform-runtime。在 v2 中，该插件搭配 @babel/runtime-corejs2；在 v3 中，对应依赖替换为 @babel/runtime-corejs3。

关键优势在于：@babel/runtime-corejs3 首次支持对实例方法（Instance Methods）进行无污染转换。在 v2 中，[1, 2].includes(2) 这类调用是无法通过 runtime 垫片的，但在 v3 下，Babel 会将其重写为 _includesInstanceProperty(arr).call(arr, 2)，真正做到了实例方法的沙箱隔离。

// babel.config.js (面向独立 NPM 类库开发者的配置)
module.exports = {
  plugins: [
    [
      "@babel/plugin-transform-runtime",
      {
        corejs: 3 // 需要安装依赖 @babel/runtime-corejs3
      }
    ]
  ]
};

3. 业务入口代码的写法转变

若项目在 @babel/preset-env 中配置的是 useBuiltIns: "entry"，需要在项目的最顶层入口（如 src/index.js 或 src/main.ts）手动引入垫片。写法对比如下：

三、系统化迁移实操步骤

将一个大型老旧项目从 core-js v2 升级到 v3，应当遵循“清理 -> 安装 -> 替换入口 -> 调整配置 -> 验证”的标准化顺序，确保每一步的产物均处于可解释、可追踪的状态。

步骤 1：审计旧依赖并彻底卸载

首先检查 package.json 中的 dependencies 和 devDependencies，找出所有与 v2 绑定的包并予以卸载：

# 卸载旧版废弃包及 runtime 插件
npm uninstall @babel/polyfill core-js @babel/runtime-corejs2
# 或使用 yarn / pnpm
yarn remove @babel/polyfill core-js @babel/runtime-corejs2

步骤 2：安装 core-js 3 对应套件

根据项目类型安装最新版本的依赖。注意：对于运行在生产环境业务中的应用，core-js 属于运行时必须存在的代码，应当安装在 dependencies 中，而非仅 devDependencies。

# Web 应用项目安装：
npm install --save core-js@3 regenerator-runtime

# 若为公共类库开发，需安装 runtime-corejs3：
npm install --save-dev @babel/plugin-transform-runtime @babel/runtime-corejs3

步骤 3：全局搜索并重构源码中的废弃路径

在代码编辑器中使用全局文本正则搜索，排查并替换所有直接 import 了旧路径的语句：

• 搜索 @babel/polyfill：替换为 core-js/stable 与 regenerator-runtime/runtime。
• 搜索 core-js/library/：替换为从 core-js-pure/ 引入。
• 搜索 core-js/fn/：将其改为 core-js/features/ 或具体标准子路径。
• 搜索 core-js/es6/ 或 core-js/es7/：将其更新为 core-js/es/。

步骤 4：更新 Babel 与构建工具配置

检查 .babelrc、babel.config.js 或 webpack.config.js 中的 Babel loader 配置，确保 @babel/preset-env 已经配置了 corejs: 3。如果项目使用了现代提案特性，建议将 corejs 声明为对象形式：

// 推荐形式：指定大版本并允许使用提案特性
corejs: { version: 3, proposals: true }

步骤 5：处理构建别名与打包策略

在 Webpack 构建配置中，建议对 node_modules 的转译规则进行检查。一般情况下，我们会在 babel-loader 中排除 node_modules（即 exclude: /node_modules/）。请确保 core-js 自身不需要经过二次 Babel 编译，否则可能引发意外的循环引用或构建性能骤降。

四、关键注意事项与避坑指南

在实际生产项目迁移过程中，常常会遇到因为第三方依赖间接引入旧版本、或者混淆了沙箱垫片与全局垫片而引发的疑难问题。以下四个检查点至关重要。

1. 依赖冲突与双重打包陷阱（Duplicate Core-js）

这是升级后最常见的体积失控隐患。项目自身的业务代码已经成功迁移到了 core-js@3，但 node_modules 中某些较早发布的第三方 UI 库或图表库，其自身的 package.json 仍然锁定了 core-js@^2.6.12。

这会导致 Webpack 打包时同时将 core-js v2 和 v3 两套代码全部打包进产物，导致打包体积凭空增加几十 KB 到上百 KB，严重时还会因为两者的原型修改顺序产生诡异的运行时异常。

2. 未配置 proposals: true 导致新语法垫片遗漏

如果仅仅写了 corejs: 3，Babel 默认只会为已经进入 ECMAScript 最终正式标准（Stage 4） 的特性注入 Polyfill。若项目代码中使用了处于 Stage 3 阶段但浏览器尚未完全实现的提案语法（例如前几年的 Object.hasOwn 或私有字段相关辅助方法），打包后在低版本浏览器中运行时会直接报 TypeError: undefined is not a function。

若项目中使用了非正式标准的 Stage 提案，务必显式声明 corejs: { version: 3, proposals: true }。

3. 应用开发与类库开发的模式误区

许多开发者误以为 @babel/plugin-transform-runtime 是万能的，试图在大型独立 Web 站点项目中完全依靠它替代 @babel/preset-env 的垫片。这种做法存在严重漏洞：

transform-runtime 是通过在编译时解析当前项目源文件的语法树并替换为辅助函数来实现的。然而，现代项目中引入的大量未编译的第三方 NPM 包代码，并不会被项目的 transform-runtime 所处理。如果低版本浏览器缺少对应的原生全局 API，第三方包一调用原生方法就会崩溃。

核心选型准则：

• 业务系统 / 独立站点：采用 @babel/preset-env 的 useBuiltIns: "usage"（全局注入），确保整个运行环境具备完整 API。
• 开源组件库 / SDK / 工具包：采用 @babel/plugin-transform-runtime 搭配 @babel/runtime-corejs3，杜绝污染使用方的全局环境。

4. IE 11 等极端宿主环境下的 URL 与 Promise 陷阱

在需要严格兼容 IE 11 的企业级系统中，部分历史遗留代码会通过 window.URL 解析地址。在 core-js v3 中，core-js/web/url 虽然严格遵守了规范，但由于 IE 11 的底层宿主对象限制，某些开发者如果在引入 core-js 之后又手动引入了其他的全局 URL 脚本，可能会覆盖 core-js 的实现并造成不合规的解析行为。

建议在入口处统一只依赖 core-js 的官方 Web 垫片，并排查 HTML 模板 index.html 中是否有残留的外链 polyfill 脚本。

五、构建产物验证与验收

完成上述配置和代码调整后，必须通过构建层与运行时两个维度来验证迁移结果。

1. 依赖体积分析验证

启动 Webpack Bundle Analyzer（webpack-bundle-analyzer）或 Vite Rollup Visualizer，审查生成的打包分析报告。在报告的模块树状图中执行以下检查：

• 在模块树中搜索 core-js，确认仅存在 node_modules/core-js 一个主目录，没有任何带有 core-js@2 或 es6/es7 结构的包。
• 检查是否存在废弃的 @babel/polyfill 模块碎片。
• 检查注入的 polyfill 是否与配置的 .browserslistrc 吻合，没有注入目标浏览器早已原生支持的多余垫片。

2. 目标环境运行时校验

在受支持的最低版本浏览器（如 Chrome 49、老版本 Safari 或 IE 11）环境中运行打包产物，在控制台执行关键特性的测试断言：

// 运行时验证示例（可在低版本浏览器控制台或单元测试中执行）
console.log("Promise.prototype.finally:", typeof Promise.prototype.finally === "function");
console.log("Array.prototype.flat:", typeof Array.prototype.flat === "function");
console.log("Object.fromEntries:", typeof Object.fromEntries === "function");
console.log("URLSearchParams:", typeof window.URLSearchParams === "function");

若所有方法均返回 true 且无未捕获的报错，说明 core-js v3 的垫片注入完整且生效。至此，项目的 Polyfill 体系成功实现了现代化过渡。