怎么通过 browserslist 精确控制 core-js 的 Polyfill 范围

一、协同机制：Browserslist 是如何裁剪 core-js 的

在许多前端项目中，开发者往往会遇到产物打包体积居高不下的问题。如果直接在入口执行 import 'core-js'，会将 ECMAScript 所有特性的补丁全量打包进来，体积轻松膨胀上百 KB。即使现代浏览器早已原生支持了 Promise、Map、Array.prototype.includes 等特性，全量引入仍会覆盖原生实现或进行无谓的垫片填充。

为了解决这一问题，Babel 提供了 @babel/preset-env 智能预设。该预设本身并不硬编码具体的语法降级和补丁列表，而是作为一个协作枢纽，通过以下链条实现精确裁剪：

1. 目标环境解析：从项目的 .browserslistrc 或 package.json 中提取查询规则（如 > 1%, last 2 versions, not dead），交由 browserslist 模块转化为具体的浏览器及版本清单（例如 Chrome 115、Safari 16.4、Firefox 118 等）。
2. 兼容性数据库映射：借由 caniuse-lite 与 core-js-compat 数据库，查询出清单中目标浏览器对每一个 ES 提案和标准的实际支持状况。只要清单中存在任何一款浏览器不支持某项特性，该特性就会被列为“缺失项”。
3. 代码 AST 分析与按需注入：当 Babel 开启 useBuiltIns: 'usage' 时，遍历业务代码中的语法与全局/原型方法调用（如 [].at() 或 Promise.any()），一旦发现代码用到了某个特性，且该特性属于上一步计算得出的“缺失项”，便自动在当前文件顶部注入对应的具体小模块（如 import "core-js/modules/es.array.at.js"）。

二、四步实操：配置精确按需 Polyfill

实现精准控制无需复杂的自定义脚本，只需要规范建立 .browserslistrc 与 babel.config.js 的标准配置。下面按实际工程落地顺序讲解具体操作步骤。

步骤 1：在项目根目录创建 .browserslistrc

推荐将目标规则独立写在根目录的 .browserslistrc 文件中，这样不仅 Babel 能读取，Autoprefixer、postcss-preset-env 等工具也能无缝共享同一套标准。

# .browserslistrc
# 全球或区域份额超过 0.5% 的活跃浏览器，排除已停止维护的浏览器
> 0.5%
last 2 versions
not dead
not ie 11
not op_mini all
Chrome >= 87
Safari >= 14

配置要点： 明确添加 not ie 11 可以立即剔除大量专为旧版 IE 准备的补丁（如 Symbol 原型扩展、深层迭代器修补等）。对于国内企业级桌面或移动 Web 场景，推荐根据埋点数据设定具体的最低主流内核版本（如 Chrome >= 87）。

步骤 2：安装必要依赖

需要安装 @babel/preset-env 以及运行时所需的 core-js（必须选用第 3 版）。

npm install --save-dev @babel/core @babel/preset-env
npm install --save core-js@3

步骤 3：在 Babel 配置文件中深度声明参数

在根目录下创建或编辑 babel.config.js。最关键的配置是设置 useBuiltIns: 'usage' 并指定 corejs 的具体次版本号。

// babel.config.js
module.exports = {
  presets: [
    [
      '@babel/preset-env',
      {
        // 核心：基于代码实际使用情况按需引入，配合 browserslist 精准注入
        useBuiltIns: 'usage',
        // 务必指定 corejs 的小版本号（例如 3.38），避免 Babel 默认按照 3.0 处理而遗漏新 API
        corejs: {
          version: '3.38',
          proposals: false // 若需垫片处于 stage 阶段的提案，设为 true
        },
        // 构建时输出具体的 polyfill 注入日志，便于验证与调试
        debug: false
      }
    ]
  ]
};

步骤 4：移除业务入口的手工全量引入

过去很多项目会在 main.js 或 index.js 最顶部显式写入 import 'core-js/stable' 或 import '@babel/polyfill'。在配置了 useBuiltIns: 'usage' 后，必须彻底删除这些手动引入语句。否则 Babel 在静态扫描时会尊重你的全量引入声明，导致整套按需过滤机制失效。

三、规则对比：不同 Browserslist 规则对补丁范围的影响

不同的 Browserslist 范围对 Polyfill 数量的最终影响是极其显著的。为了更直观地理解规则与补丁注入的关系，我们选取几项近年常见的 ECMAScript API 进行实际比对分析：

从上表可见： 在规则 A（宽松配置）下，哪怕只有 0.2% 的冷门或老旧浏览器出现在清单中，Babel 为了保障整体可用性，也会被迫将 Promise.allSettled、Promise.any 等全部注入补丁。 而在规则 B 下，因为明确将目标底线上调至 Chrome >= 87, Safari >= 14，绝大多数成熟 API 均直接利用浏览器原生引擎执行，不仅包体积减少 30KB~80KB，而且消除了包装层带来的额外运行时开销。

四、结果验证与调试排查方法

修改配置后，不能停留在“写完配置就认为已经生效”的假设上，必须通过严谨的命令行工具与编译调试输出进行验证。

1. 用命令行直接检查生效的目标浏览器清单

在终端中运行 Browserslist 自带的 CLI 工具，查看当前配置匹配出来的精确浏览器版本：

npx browserslist

输出示例（截选）：

chrome 120
chrome 119
chrome 118
edge 120
firefox 121
ios_saf 17.2
safari 17.2
safari 16.6

如果在输出中依然能看到 ie 11、chrome 49 等早已被业务抛弃的浏览器代号，说明规则筛选条件依然过宽，需要立即调整 .browserslistrc。

2. 开启 Babel debug: true 审查补丁注入清单

在 babel.config.js 中将 debug 临时设为 true，然后执行构建（如 npm run build）。Babel 会在控制台打印详细的 targets 解析结果及每个文件被注入的具体 polyfill：

// babel.config.js
module.exports = {
  presets: [
    ['@babel/preset-env', {
      useBuiltIns: 'usage',
      corejs: '3.38',
      debug: true // 开启调试日志
    }]
  ]
};

控制台调试输出示例：

Using targets:
{
  "chrome": "87.0.0",
  "safari": "14.0.0"
}

Using polyfills with `usage` option:

[src/main.js] Added following polyfills:
  es.array.at { "safari":"14.0.0" }
  es.object.has-own { "safari":"14.0.0" }

[src/utils/math.js] Added following polyfills:
  (none)

通过这套日志可以清晰确认： 由于 Safari 14 缺失 Array.prototype.at，Babel 才会为其添加 es.array.at 垫片；而在 math.js 中，由于没有使用超出目标浏览器能力的新特性，补丁数量为 (none)。

五、工程实践中的关键陷阱与优化建议

在实际生产环境中，以下四个常见陷阱往往会导致精准控制失效或打包产物异常：

1. 仅声明 corejs: 3 而未指定小版本号

很多项目直接写 corejs: 3。如果不写小版本，Babel 默认会将其视作 core-js@3.0。由于 Promise.any、Array.prototype.at 等都是后续次版本（如 3.7、3.8、3.18）才陆续加入的，Babel 在查询兼容数据时会误以为该版本 core-js 尚未提供对应垫片，从而完全不进行注入，导致线上在旧浏览器直接报错 undefined is not a function。 正确做法：明确声明为当前所装版本的次版本号，例如 corejs: '3.38' 或 corejs: { version: '3.38', proposals: false }。

2. 第三方依赖（node_modules）未参与转译或二次污染

由于性能考虑，大部分 Webpack 或 Vite 项目通常会配置 exclude: /node_modules/。如果某个第三方 NPM 包源码中直接使用了 ES2022+ 语法，且该包在发布时未做降级，那么它既不会被 Babel 扫描注入补丁，也不会被正确转译。 若目标浏览器遇到此类包，页面便会直接崩溃。遇到这种情况，应当在构建配置中将该特定依赖包加入 babel-loader 的 include 白名单中。

3. caniuse-lite 数据长期未更新

Browserslist 的版本数据存储在本地的 caniuse-lite 依赖包中。如果项目半年以上没有更新该包，新发布的浏览器版本（如 Chrome 120+）可能不被识别，从而回退到旧版数据或导致份额统计失真。 建议定期在项目根目录执行官方更新命令：

npx update-browserslist-db@latest

六、总结

利用 browserslist 精确控制 core-js 的 Polyfill 范围，本质上是用现代浏览器的原生能力替换通用的降级垫片。只要掌握三个核心支点：

• 在 .browserslistrc 中明确划定项目真正承诺支持的浏览器底线，剔除 IE 11 及陈旧无维护内核；
• 在 @babel/preset-env 中开启 useBuiltIns: 'usage' 并精确指定 corejs 小版本号，彻底废弃全量静态引入；
• 结合 npx browserslist 与构建 debug 输出，将补丁的注入范围纳入团队可审查、可量化的性能监控体系中。

遵循以上规范，既能免去手动管理 Polyfill 的繁琐心智负担，又能让构建产物保持轻盈高质，实现性能与兼容性的最佳平衡。