使用 @babel/preset-env 编译现代 JavaScript 语法只是 babel 工作的一半，另一半是补齐运行时缺失的 API，比如 Promise、Array.prototype.includes、Object.assign 这些新增的全局对象和实例方法。语法层面的转换（箭头函数、class、解构等）由插件负责，而 API 层面的兼容则要靠 polyfill。useBuiltIns 就是 @babel/preset-env 中控制 polyfill 引入策略的核心配置项，它有三个可选值：false、entry、usage。选错配置，轻则打包体积暴涨几十 KB，重则线上白屏报错。
useBuiltIns 三个取值的行为差异
先看最基础的 false。这是默认值，含义是 preset-env 只处理语法转换，完全不注入任何 polyfill。如果你在源码里手写了 import "@babel/polyfill" 这样的语句，babel 不会对它做任何裁剪，整个 polyfill 包会被原样打进去。在只面向现代浏览器的项目里这样没问题，但一旦要兼容 IE11 或者一些老旧的安卓 WebView，运行时就会因为缺少 Promise 之类的 API 直接挂掉。
第二个取值是 entry。它的意思是：你在入口文件里手动引入完整的 polyfill（通常是 import "core-js/stable" 加上 regenerator-runtime），babel 在编译时会根据你配置的 targets 目标环境，把这行全量引入替换成目标环境实际需要的那部分模块。比如目标浏览器支持大部分 ES2015 特性时，最终产物里就不会包含已经原生支持的 polyfill。这种模式的好处是行为可控，所有入口统一注入；缺点是你必须自己在每个入口文件顶部写引入语句，漏写一个入口就会出问题。
第三个也是目前最推荐的取值：usage。它会扫描你的源代码，发现哪个文件用了哪些还不被目标浏览器支持的 API，就在那个文件顶部自动注入对应的 polyfill 模块。你不需要在入口写任何引入语句，babel 全自动处理。举个直观的例子，配置和代码如下：
{
"presets": [
["@babel/preset-env", {
"targets": { "chrome": "58", "ie": "11" },
"useBuiltIns": "usage",
"corejs": 3
}]
]
}
// 源码 main.js
const arr = [1, 2, 3];
console.log(arr.includes(2));
Promise.resolve().then(() => console.log("done"));编译后 babel 会在文件顶部自动加上对 core-js/modules/es.array.includes 和 core-js/modules/es.promise 等模块的引入，且只引入这些，不多不少。这就是所谓按需引入的字面含义。
corejs 版本选择与常见报错排查
useBuiltIns 设为 entry 或 usage 时，必须同时指定 corejs 选项，否则 babel 会给出警告并可能行为异常。core-js 目前主流是 3.x 版本，写法上推荐明确到次版本号，比如 "corejs": "3.30" 这样写字符串形式，而不是只写数字 3。只写数字时 babel 默认取该大版本的最老版本，可能缺少新 API 的垫片定义，导致明明配置了 usage 却仍然没有注入某个新 API 的情况。
注意一个历史遗留问题：老的 @babel/polyfill 包内部依赖的是 core-js@2，而 core-js 的作者后来因为代码里被注入推广文案引发过争议，社区普遍建议直接使用 core-js@3 并配合 regenerator-runtime。项目里要安装对应依赖：
npm install --save core-js@3 regenerator-runtime
另一个高频报错是 "You have specified using a version of core-js that does not exist"。原因通常是 corejs 配置的版本号与实际安装的 core-js 版本对不上。例如配置写的是 3.37，但项目里装的是 3.36，就需要重新安装匹配的版本或者调整配置。还有一类问题是 usage 模式下某些第三方依赖内部用了新 API 但没有经过 babel 处理，babel 扫描不到就不会注入，这时要么把该依赖纳入编译范围，要么退回 entry 模式兜底。
entry 与 usage 的实际选型建议
从包体积角度看，usage 通常是最优的，因为注入粒度精确到单个 API 模块，且分散在使用它的文件里，配合 webpack 的代码分割能实现按需加载。entry 模式则是把目标环境需要的全部 polyfill 集中注入到入口，对于大量使用新 API 的项目，两者体积差距会缩小，但 entry 不会遗漏，也不用担心 node_modules 里的代码缺垫片。
实践中可以按场景选择：业务代码全部自己掌控、依赖库较新的项目，直接用 usage；项目里有大量未经编译的老旧第三方库，或者构建流程复杂、多入口管理混乱时，entry 更稳妥。另外别忘了 targets 的配置会直接影响裁剪结果，可以用 .browserslistrc 文件统一管理，与 autoprefixer 等工具共享同一份浏览器目标。最后提醒一点：polyfill 解决的是 API 兼容，语法转换靠的是 preset 的插件体系，两者配合才能让编译产物在目标浏览器中稳定运行，排查线上兼容问题时先分清报错属于哪一类，才能对症下药。
useBuiltInspolyfillbabel preset-env修改时间：2026-09-06 21:56:50