跳至主内容

使用指南

非官方测试版翻译

本页面由 PageTurner AI 翻译（测试版）。未经项目官方认可。 发现错误？ 报告问题 →

Babel 工具链提供了多种工具，无论你是"最终用户"还是构建 Babel 集成方案，这些工具都能简化使用流程。本文将简要介绍这些工具，更多细节可查阅文档的"使用"部分。

如果你正在使用框架，配置 Babel 的方式可能有所不同或已自动完成。请查看我们的交互式设置指南。

概述​

本指南将展示如何将采用 ES2015+ 语法的 JavaScript 应用代码编译成可在当前浏览器运行的代码，这包括语法转换和缺失功能的 polyfill 填补。

完整设置流程包含以下步骤：

  1. 运行以下命令安装所需包：

    npm install --save-dev @babel/core @babel/cli @babel/preset-env

  2. 在项目根目录创建 babel.config.json 配置文件（需 v7.8.0 及以上版本），内容如下：

    babel.config.json
    {
      "presets": [
        [
          "@babel/preset-env",
          {
            "targets": {
              "edge": "17",
              "firefox": "60",
              "chrome": "67",
              "safari": "11.1"
            },
            "useBuiltIns": "usage",
            "corejs": "3.6.5"
          }
        ]
      ]
    }

    上述浏览器列表仅为示例，请根据实际需要支持的浏览器调整配置。更多 @babel/preset-env 选项请参见此处。

若使用旧版 Babel 则需创建 babel.config.js

babel.config.js
const presets = [
  [
    "@babel/preset-env",
    {
      targets: {
        edge: "17",
        firefox: "60",
        chrome: "67",
        safari: "11.1",
      },
      useBuiltIns: "usage",
      corejs: "3.6.4",
    },
  ],
];

module.exports = { presets };

  1. 运行此命令将 src 目录代码编译至 lib 目录：

    Shell
    ./node_modules/.bin/babel src --out-dir lib

    使用 npm@5.2.0 自带的包运行器可简化命令：将 ./node_modules/.bin/babel 替换为 npx babel

下文将逐步解析该流程并介绍使用的各项工具。

命令行工具基础用法​

自第 7 版起，所有 Babel 模块均以独立 npm 包形式发布在 @babel 作用域下。这种模块化设计支持为不同场景定制工具，本节重点介绍 @babel/core 和 @babel/cli。

核心库​

Babel 的核心功能位于 @babel/core 模块。安装后：

npm install --save-dev @babel/core

可在 JavaScript 程序中直接通过 require 引用并使用：

JavaScript
const babel = require("@babel/core");

babel.transformSync("code", optionsObject);

作为最终用户，建议安装其他作为 @babel/core 接口的工具以更好地集成进开发流程。即便如此，仍建议查阅其文档了解配置选项，这些选项通常也可通过其他工具设置。

CLI 工具​

@babel/cli 支持在终端中使用 Babel。以下是安装命令和基础用法示例：

npm install --save-dev @babel/core @babel/cli

./node_modules/.bin/babel src --out-dir lib

该命令会解析 src 目录所有 JavaScript 文件，应用指定转换后输出至 lib 目录。未指定转换规则时，输出代码将与输入完全一致（代码风格不保留）。可通过传递选项参数指定转换规则。

上面我们使用了 --out-dir 选项。你可以通过运行 --help 查看 cli 工具支持的其他选项。但目前对我们最重要的选项是 --plugins 和 --presets。

插件与预设​

转换功能通过插件实现，这些小型 JavaScript 程序指导 Babel 如何执行代码转换。你甚至可以编写自定义插件来实现任意转换效果。要将 ES2015+ 语法转为 ES5，我们可以使用官方插件如 @babel/plugin-transform-arrow-functions：

npm install --save-dev @babel/plugin-transform-arrow-functions

./node_modules/.bin/babel src --out-dir lib --plugins=@babel/plugin-transform-arrow-functions

现在代码中的所有箭头函数都会被转换为 ES5 兼容的函数表达式：

JavaScript
const fn = () => 1;

// converted to

var fn = function fn() {
  return 1;
};

这是个好的开始！但我们的代码中还有其他需要转换的 ES2015+ 特性。与其逐个添加所需插件，我们可以使用"预设"——即预先配置的插件集合。

与插件类似，你也可以创建自定义预设来共享所需的插件组合。针对当前场景，env 就是个非常优秀的预设。

npm install --save-dev @babel/preset-env

./node_modules/.bin/babel src --out-dir lib --presets=@babel/env

该预设在无配置情况下会包含所有支持现代 JavaScript(ES2015、ES2016 等)的插件。但预设也支持配置选项。与其通过终端传递 CLI 和预设选项，我们来看另一种配置方式：配置文件。

配置​

根据需求不同，配置文件有几种使用方式。详细配置方法请参阅我们的深度指南：配置 Babel。

现在创建名为 babel.config.json 的文件（要求 v7.8.0 及以上版本），内容如下：

babel.config.json
{
  "presets": [
    [
      "@babel/preset-env",
      {
        "targets": {
          "edge": "17",
          "firefox": "60",
          "chrome": "67",
          "safari": "11.1"
        }
      }
    ]
  ]
}

现在 env 预设只会为目标浏览器未支持的特性加载转换插件。语法转换已配置完成，接下来看看 polyfill。

Polyfill​

🚨 As Babel 7.4.0 起，该包已被弃用，建议直接引入 core-js/stable（用于 polyfill ECMAScript 特性）：

JavaScript
import "core-js/stable";

若需将生成器或异步函数编译到 ES5，且使用的 @babel/core 或 @babel/plugin-transform-regenerator 版本低于 7.18.0，则必须额外加载 regenerator runtime 包。使用 @babel/preset-env 的 useBuiltIns: "usage" 选项或 @babel/plugin-transform-runtime 时会自动加载此包。

@babel/polyfill 模块包含 core-js 和定制的 regenerator runtime，用于模拟完整的 ES2015+ 环境。

这意味着你可以使用新的内置对象（如 Promise/WeakMap）、静态方法（如 Array.from/Object.assign）、实例方法（如 Array.prototype.includes）以及生成器函数（需配合 regenerator 插件）。Polyfill 会将这些功能注入全局作用域和原生原型（如 String）中。

对库/工具开发者来说这可能过度。如果不需要 Array.prototype.includes 等实例方法，可使用 transform runtime 插件替代 @babel/polyfill，完全避免污染全局作用域。

更精准的做法是：若明确知道需要 polyfill 的特性，可直接从 core-js 按需引入。

由于我们构建的是应用程序，直接安装 @babel/polyfill 即可：

npm install --save @babel/polyfill

注意这里使用 --save 选项而非 --save-dev，因为这是一个需要在源代码之前运行的 polyfill。

幸运的是，我们正在使用 env 预设，它提供了 "useBuiltIns" 选项。当设置为 "usage" 时，实际上就应用了上述的最后一项优化——只包含你需要的 polyfill。启用这个新选项后，配置会变成这样：

babel.config.json
{
  "presets": [
    [
      "@babel/preset-env",
      {
        "targets": {
          "edge": "17",
          "firefox": "60",
          "chrome": "67",
          "safari": "11.1"
        },
        "useBuiltIns": "usage"
      }
    ]
  ]
}

现在 Babel 会检测你代码中目标环境缺失的所有功能，并只引入必要的 polyfill。例如以下代码：

JavaScript
Promise.resolve().finally();

将会被转换成这样（因为 Edge 17 不支持 Promise.prototype.finally）：

JavaScript
require("core-js/modules/es.promise.finally");

Promise.resolve().finally();

如果我们没有使用 env 预设并将 "useBuiltIns" 选项设为 "usage"（默认为 "false"），就需要在入口文件中_仅一次_引入完整的 polyfill，且必须在其他代码之前。

例如：

babel.config.json
{
  "presets": [
    [
      "@babel/preset-env",
      {
        "targets": {
          "edge": "17",
          "firefox": "60",
          "chrome": "67",
          "safari": "11.1"
        },
        "useBuiltIns": "entry"
      }
    ]
  ]
}

Then import core-js (to polyfill ECMAScript features) first, in our entry file to emulate a full ES2015+ environment since @babel/polyfill has been deprecated:

JavaScript
 import "core-js/stable";

总结​

我们使用 @babel/cli 在终端运行 Babel，@babel/polyfill 为所有新 JavaScript 功能提供 polyfill，并通过 env 预设仅包含我们使用且目标浏览器缺失的功能转换和 polyfill。

有关在构建系统、IDE 等环境中配置 Babel 的更多信息，请查阅我们的交互式设置指南。