Skip to main content

@babel/polyfill

危险

🚨 从 Babel 7.4.0 开始，这个包已经被弃用，取而代之的是直接包含 core-js/stable（以填充 ECMAScript 特性）：

¥🚨 As of Babel 7.4.0, this package has been deprecated in favor of directly including core-js/stable (to polyfill ECMAScript features):

JavaScript
import "core-js/stable";

如果你将生成器或异步函数编译到 ES5，并且你使用的是早于 7.18.0 的 @babel/core 或 @babel/plugin-transform-regenerator 版本，则还必须加载 regenerator runtime 包。使用 @babel/preset-env 的 useBuiltIns: "usage" 选项或 @babel/plugin-transform-runtime 时会自动加载。

¥If you are compiling generators or async function to ES5, and you are using a version of @babel/core or @babel/plugin-transform-regenerator older than 7.18.0, you must also load the regenerator runtime package. It is automatically loaded when using @babel/preset-env's useBuiltIns: "usage" option or @babel/plugin-transform-runtime.

Babel 包括 polyfill，其中包括自定义 再生器运行时 和 core-js。

¥Babel includes a polyfill that includes a custom regenerator runtime and core-js.

这将模拟完整的 ES2015+ 环境（没有 < Stage 4 提案），并且旨在用于应用而不是库/工具。（这个 polyfill 在使用 babel-node 时会自动加载）。

¥This will emulate a full ES2015+ environment (no < Stage 4 proposals) and is intended to be used in an application rather than a library/tool. (this polyfill is automatically loaded when using babel-node).

这意味着你可以使用新的内置函数（如 Promise 或 WeakMap）、静态方法（如 Array.from 或 Object.assign）、实例方法（如 Array.prototype.includes）和生成器函数（前提是你使用 regenerator 插件）。为了做到这一点，polyfill 添加到全局作用域以及像 String 这样的原生原型。

¥This means you can use new built-ins like Promise or WeakMap, static methods like Array.from or Object.assign, instance methods like Array.prototype.includes, and generator functions (provided you use the regenerator plugin). The polyfill adds to the global scope as well as native prototypes like String in order to do this.

安装​

¥Installation

npm install --save @babel/polyfill
信息

因为这是一个 polyfill（它将在你的源代码之前运行），我们需要它是 dependency，而不是 devDependency

¥Because this is a polyfill (which will run before your source code), we need it to be a dependency, not a devDependency

尺寸​

¥Size

提供 polyfill 是为了方便，但你应该将它与 @babel/preset-env 和 useBuiltIns 选项 一起使用，这样它就不会包含并非总是需要的整个 polyfill。否则，我们建议你手动导入单个 polyfill。

¥The polyfill is provided as a convenience but you should use it with @babel/preset-env and the useBuiltIns option so that it doesn't include the whole polyfill which isn't always needed. Otherwise, we would recommend you import the individual polyfills manually.

TC39 提案​

¥TC39 Proposals

如果你需要使用不是第 4 阶段的提案，@babel/polyfill 不会自动为你导入这些提案。你将不得不从另一个 polyfill（如 core-js）单独导入它们。我们可能会尽快将其作为单独的文件包含在 @babel/polyfill 中。

¥If you need to use a proposal that is not Stage 4, @babel/polyfill will not automatically import those for you. You will have to import those from another polyfill like core-js individually. We may work towards including this as separate files in @babel/polyfill soon.

在 Node / Browserify / Webpack 中的使用​

¥Usage in Node / Browserify / Webpack

要包含 Polyfill，你需要将其添加到应用入口点的顶部。

¥To include the polyfill you need to require it at the top of the entry point to your application.

确保在所有其他代码/引入语句之前调用它！

¥Make sure it is called before all other code/require statements!

JavaScript
require("@babel/polyfill");

如果你在应用的入口点中使用 ES6 的 import 语法，则应该在入口点顶部导入 Polyfill，以确保首先加载 Polyfill：

¥If you are using ES6's import syntax in your application's entry point, you should instead import the polyfill at the top of the entry point to ensure the polyfills are loaded first:

JavaScript
import "@babel/polyfill";

使用 webpack，有多种方法可以包含 polyfill：

¥With webpack, there are multiple ways to include the polyfills:

  • 与 @babel/preset-env 一起使用时，

    ¥When used alongside @babel/preset-env,

    • 如果在 .babelrc 中指定了 useBuiltIns: 'usage'，则不要在 webpack.config.js 条目数组或源中包含 @babel/polyfill。注意，@babel/polyfill 还是需要安装的。

      ¥If useBuiltIns: 'usage' is specified in .babelrc then do not include @babel/polyfill in either webpack.config.js entry array nor source. Note, @babel/polyfill still needs to be installed.

    • 如果在 .babelrc 中指定了 useBuiltIns: 'entry'，那么如上所述，通过 require 或 import 在你的应用的入口点顶部包含 @babel/polyfill。

      ¥If useBuiltIns: 'entry' is specified in .babelrc then include @babel/polyfill at the top of the entry point to your application via require or import as discussed above.

    • 如果没有指定 useBuiltIns 键，或者在你的 .babelrc 中明确设置了 useBuiltIns: false，则直接将 @babel/polyfill 添加到你的 webpack.config.js 中的条目数组中。

      ¥If useBuiltIns key is not specified or it is explicitly set with useBuiltIns: false in your .babelrc, add @babel/polyfill directly to the entry array in your webpack.config.js.

webpack.config.js
module.exports = {
  entry: ["@babel/polyfill", "./app/js"],
};

  • 如果不使用 @babel/preset-env，则如上所述将 @babel/polyfill 添加到 webpack 条目数组。它仍然可以通过 import 或 require 添加到应用的入口点顶部，但不建议这样做。

    ¥If @babel/preset-env is not used then add @babel/polyfill to webpack entry array as discussed above. It can still be added at the top of the entry point to application via import or require, but this is not recommended.

提醒

我们不建议你直接导入整个 polyfill：要么尝试 useBuiltIns 选项，要么仅手动导入你需要的 polyfill（从这个包或其他地方）。

¥We do not recommend that you import the whole polyfill directly: either try the useBuiltIns options or import only the polyfills you need manually (either from this package or somewhere else).

在浏览器中的使用​

¥Usage in Browser

可从 @babel/polyfill npm 版本中的 dist/polyfill.js 文件获得。这需要包含在所有编译的 Babel 代码之前。你可以将其添加到你的编译代码中，也可以将其包含在 <script> 之前。

¥Available from the dist/polyfill.js file within a @babel/polyfill npm release. This needs to be included before all your compiled Babel code. You can either prepend it to your compiled code or include it in a <script> before it.

注意：不要通过 browserify 等 require，使用 @babel/polyfill。

¥NOTE: Do not require this via browserify etc, use @babel/polyfill.

详情​

¥Details

提示

如果你正在寻找不会修改要在工具/库中使用的全局变量的东西，请查看 transform-runtime 插件。这意味着你将无法像 Array.prototype.includes 一样使用上面提到的实例方法。

¥If you are looking for something that won't modify globals to be used in a tool/library, checkout the transform-runtime plugin. This means you won't be able to use the instance methods mentioned above like Array.prototype.includes.

注意：根据你实际使用的 ES2015 方法，你可能不需要使用 @babel/polyfill 或运行时插件。你可能只想 加载你正在使用的特定 polyfill（如 Object.assign）或仅记录加载库的环境应包含某些 polyfill。

¥Note: Depending on what ES2015 methods you actually use, you may not need to use @babel/polyfill or the runtime plugin. You may want to only load the specific polyfills you are using (like Object.assign) or just document that the environment the library is being loaded in should include certain polyfills.