配置选项

非官方测试版翻译

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

• 核心选项

• 配置加载选项

• 插件与预设配置

• 配置合并选项

• 源码映射选项

• 杂项选项

• 代码生成器选项

• AMD/UMD/SystemJS模块选项

• 选项概念解析

可以通过多种方式向Babel传递配置选项。当直接调用Babel时，只需传递选项对象即可。当通过封装工具使用Babel时，通过配置文件传递选项可能更必要或更实用。

若通过@babel/cli传递选项，需使用kebab-case命名法。例如：

npx babel --root-mode upward file.js # equivalent of passing the rootMode config option

核心选项

这些选项仅作为Babel编程式配置的一部分，主要供封装Babel的工具或直接调用babel.transform的用户使用。集成方案（如babel-loader或@babel/register）的用户通常无需使用这些选项。

cwd

类型：string
默认值：process.cwd()

所有编程式选项中的路径都将基于此工作目录进行解析。

caller

类型：符合以下结构的对象

interface CallerData {
  name: string;
  supportsStaticESM?: boolean;
  supportsDynamicImport?: boolean;
  supportsTopLevelAwait?: boolean;
  supportsExportNamespaceFrom?: boolean;
}

History

Version	Changes
v7.11.0	Add supportsExportNamespaceFrom
v7.7.0	Add supportsTopLevelAwait
v7.5.0	Add supportsDynamicImport

工具可通过传递caller对象向Babel标识自身，并向配置、预设和插件传递能力标志。例如：

JavaScript

babel.transformFileSync("example.js", {
  caller: {
    name: "my-custom-tool",
    supportsStaticESM: true,
  },
});

该配置允许插件和预设根据ES模块支持情况，决定是否跳过将ES模块编译为CommonJS模块。

filename

类型：string

当前编译代码关联的文件名（如果存在）。此选项非必需，但当文件名未知时，Babel的部分功能将受限，因为某些选项依赖文件名实现其功能。

用户可能遇到的三种主要情况：

• 文件名会暴露给插件，部分插件可能要求提供文件名

• "test"、"exclude"和"ignore"等选项需依赖文件名进行字符串/正则匹配

• .babelrc.json或.babelrc文件将相对于被编译文件加载。若省略此选项，Babel行为等同于设置了babelrc: false

filenameRelative

类型：string
默认值：path.relative(opts.cwd, opts.filename)（若已传递"filename"）

用作Babel的sourceFileName选项默认值，并参与生成AMD/UMD/SystemJS模块转换的文件名。

code

类型：boolean
默认值：true

Babel 的默认返回值包含 code 和 map 属性，其中包含生成的代码。在需要多次调用 Babel 的场景中，禁用代码生成而改用 ast: true 直接获取 AST 可能很有帮助，这样可以避免不必要的工作。

ast

类型：boolean
默认值：false

Babel 默认生成字符串和 sourcemap，但在某些场景下直接获取 AST 本身很有用。主要用例是进行多次转换传递的链式操作，例如：

JavaScript

const filename = "example.js";
const source = fs.readFileSync(filename, "utf8");

// Load and compile file normally, but skip code generation.
const { ast } = babel.transformSync(source, {
  filename,
  ast: true,
  code: false,
});

// Minify the file in a second pass and generate the output code here.
const { code, map } = babel.transformFromAstSync(ast, source, {
  filename,
  presets: ["minify"],
  babelrc: false,
  configFile: false,
});

注意：此选项默认关闭，因为大多数用户不需要它，并且我们计划在 Babel 中实现缓存层。缓存 AST 结构将占用显著更多的空间。

cloneInputAst

类型：boolean
默认值：true
添加于 v7.11.0

默认情况下 babel.transformFromAst 会克隆输入 AST 以避免修改。如果输入 AST 不会在其他地方使用，指定 cloneInputAst: false 可以提升解析性能。

配置加载选项

配置加载可能有些复杂，因为环境中可能存在多种配置文件类型，且这些配置文件可能包含各种嵌套配置对象，具体应用取决于配置环境。

root

类型：string
默认值：opts.cwd
放置位置：仅允许在 Babel 的程序化选项中使用

基于 "rootMode" 处理的初始路径，用于确定当前 Babel 项目的概念根文件夹。主要在两种情况下使用：

• 检查默认 "configFile" 值时的基础目录

• "babelrcRoots" 的默认值

rootMode

类型："root" | "upward" | "upward-optional"
默认值："root"
放置位置：仅允许在 Babel 的程序化选项中使用
添加于：v7.1.0

此选项与 "root" 值共同定义 Babel 选择项目根目录的方式。不同模式决定了 Babel 处理 "root" 值以获取最终项目根目录的不同方法。

注意：babel.config.json 从 Babel 7.8.0 开始支持。在较早的 Babel 7 版本中，仅支持 babel.config.js。

• "root" - 原样传递 "root" 值

• "upward" - 从 "root" 目录向上遍历，查找包含 babel.config.json 文件的目录，若未找到 babel.config.json 则抛出错误

• "upward-optional" - 从 "root" 目录向上遍历，查找包含 babel.config.json 文件的目录，若未找到 babel.config.json 则回退到 "root"

"root" 是默认模式，因为它能避免 Babel 意外加载完全在当前项目文件夹之外的 babel.config.json 文件的风险。如果使用 "upward-optional" 模式，请注意它会向上遍历目录结构直至文件系统根目录，而用户主目录中可能存在的遗忘的 babel.config.json 文件，可能导致构建过程中出现意外错误。

对于采用 monorepo 项目结构并按包执行构建/测试的用户，通常需要使用 "upward" 模式，因为 monorepo 项目常在根目录存放 babel.config.json 文件。若在 monorepo 子目录中运行 Babel 时不使用 "upward" 模式，将导致跳过加载项目根目录的 babel.config.json 文件，可能引发意外错误和编译失败。

envName

类型：string
默认值：process.env.BABEL_ENV || process.env.NODE_ENV || "development"
适用位置：仅允许在 Babel 的编程式选项中

配置加载过程中使用的当前活跃环境。该值在解析 "env" 配置时作为键名使用，同时可通过 api.env() 函数在配置函数、插件和预设内部访问。

configFile

类型：string | boolean
默认值：若存在则为 path.resolve(opts.root, "babel.config.json")，否则为 false
适用位置：仅允许在 Babel 的编程式选项中

默认搜索默认的 babel.config.json 文件，但可传入任何 JS 或 JSON5 配置文件的路径。

注意：此选项不会影响 .babelrc.json 文件的加载。虽然你可能想设置 configFile: "./foo/.babelrc.json"，但不建议这样做。如果通过标准的文件相对路径逻辑加载给定的 .babelrc.json，会导致同一配置文件被加载两次并与自身合并。若需链接特定配置文件，建议采用独立于 "babelrc" 名称的命名方案。

babelrc

类型：boolean
默认值：只要指定了 filename 选项即为 true
适用位置：允许在 Babel 的编程式选项或加载的 "configFile" 中使用（编程式选项优先级更高）

设为 true 将启用基于 Babel 提供的 "filename" 路径搜索配置文件和遗留的 .babelignore 文件。

编程式选项中传递的 babelrc 值会覆盖配置文件中设置的值。

注意：仅当当前 "filename" 位于匹配 "babelrcRoots" 包之一的包内时，才会加载 .babelrc.json 文件。

babelrcRoots

类型：boolean | MatchPattern | Array<MatchPattern>
默认值：opts.root
适用位置：允许在 Babel 的编程式选项或加载的 configFile 中使用（编程式选项优先级更高）

默认情况下，Babel 仅在 "root" 包内搜索 .babelrc.json 文件，因为否则 Babel 无法确定给定的 .babelrc.json 是否应被加载，或其 "plugins" 和 "presets" 是否已安装——被编译的文件可能位于 node_modules 内，或是通过符号链接引入项目的。

该选项允许用户提供其他包的列表，这些包在判断是否加载 .babelrc.json 文件时会被视为"根"包。

例如，希望允许各子包拥有独立配置的 monorepo 项目可能会这样设置：

JavaScript

babelrcRoots: [
  // Keep the root as a root
  ".",

  // Also consider monorepo packages "root" and load their .babelrc.json files.
  "./packages/*",
];

插件和预设选项

plugins

类型：Array<PluginEntry | Plugin> (PluginEntry)
默认值：[]

处理此文件时要启用的插件数组。关于各条目如何交互（尤其在跨多个嵌套的 "env" 和 "overrides" 配置时），详见合并。

注意：此选项也接受 Babel 自身的 Plugin 实例，但不推荐直接使用。如需创建插件/预设的持久化表示，应使用 babel.createConfigItem()。

presets

类型：Array<PresetEntry> (PresetEntry)
默认值：[]

处理此文件时要启用的预设数组。关于各条目如何交互（尤其在跨多个嵌套的 "env" 和 "overrides" 配置时），详见合并。

注意：预设格式与插件相同，区别在于名称规范化要求"preset-"前缀（而非"plugin-"），且预设不能是 Plugin 的实例。

passPerPreset

类型：boolean
默认值：false
状态：已弃用

指示 Babel 将 presets 数组中的每个预设作为独立编译过程执行。此选项易导致插件执行顺序混淆，但在需要将操作集拆分为独立编译过程时仍有价值。

注意：未来 Babel 版本可能移除此选项，因我们将改进插件间的顺序定义机制。

输出目标

targets

类型：string | Array<string> | { [string]: string }
默认值：{}
允许位置：Babel 程序化选项或配置文件
添加于：v7.13.0

History

Version	Changes
v7.20.0	Support deno target
v7.15.0	Support rhino target

描述项目需支持/定位的目标环境。

可接受 browserslist 兼容 的查询（含注意事项）：

babel.config.json

{
  "targets": "> 0.25%, not dead"
}

或包含需支持的最低环境版本的对象：

babel.config.json

{
  "targets": {
    "chrome": "58",
    "ie": "11"
  }
}

支持的环境：android、chrome、deno、edge、electron、firefox、ie、ios、node、opera、rhino、safari、samsung。

若未指定次要版本，Babel 会将其解释为 MAJOR.0。例如 "node": 12 将视为 Node.js 12.0。

未指定 targets

当未指定 targets 时：Babel 会假定你正在尽可能支持最旧的浏览器。例如，@babel/preset-env 会将所有 ES2015-ES2020 代码转换为 ES5 兼容的代码。

提示

我们建议设置 targets 以减少输出代码体积。

babel.config.json

{
  "presets": ["@babel/preset-env"]
}

因此，Babel 的行为与 browserslist 不同：当你的 Babel 或 browserslist 配置中没有找到 targets 时，它_不会_使用 defaults 查询。如果你想使用 defaults 查询，需要显式将其作为 target 传入：

babel.config.json

{
  "targets": "defaults"
}

我们承认这并非理想方案，并将在 Babel v8 中重新审视此问题。

targets.esmodules

类型：boolean | "intersect"

History

Version	Changes
v7.13.0	Support "intersect"

你也可以针对支持 ES Modules 的浏览器。当 esmodules 选项为 "intersect" 时，它将与 browsers target 和 browserslist 的 targets 取交集。你可以将此方法与 <script type="module"></script> 结合使用，从而有条件地为用户提供更小的脚本(https://jakearchibald.com/2017/es-modules-in-browsers/#nomodule-for-backwards-compatibility).

babel.config.json

{
  // Resolve to "Chrome 61+, FF60+, Safari 11+"
  "targets": {
    "esmodules": "intersect", // Chrome 61+, FF 60+, Safari 10.1+
    "browsers": "chrome 58, firefox 60, safari 11"
  }
}

当 esmodules 选项为 true 时，它将覆盖 browsers target 或 browserslist 的 targets。

提示

如果你使用 browserslist 的 defaults 作为 target，或者你计划支持 2019 年及之后发布的任何主流浏览器，可以安全地移除 esmodules，因为这些浏览器已支持 ES Modules。

targets.node

类型：string | "current" | true。

如果你想针对当前 Node 版本进行编译，可以指定 "node": true 或 "node": "current"，这等同于 "node": process.versions.node。

或者，你也可以使用 browserslist 查询指定 Node 版本：

babel.config.json

{
  "targets": "node 12" // not recommended
}

在这种情况下，browserslist 会将其解析为 node-releases 库中可用的_最新_版本。由于 Node.js 可能在次要版本中支持新的语言特性，为 Node.js 12.22 生成的程序在 Node.js 12.0 上可能会抛出语法错误。我们建议在使用 browserslist 的 node 查询时始终指定次要版本：

babel.config.json

{
  "targets": "node 12.0"
}

targets.safari

类型：string | "tp"。

如果你想针对 Safari 的技术预览版进行编译，可以指定 "safari": "tp"。

targets.browsers

类型：string | Array<string>。

使用 browserslist 查询选择浏览器（例如：last 2 versions, > 5%, safari tp）。

注意，浏览器的结果会被 targets 中的显式项覆盖。

targets.deno

类型：string。

最低支持版本为 1.0。

babel.config.json

{
  "targets": {
    "deno": "1.9"
  }
}

browserslistConfigFile

类型：boolean
默认值：true
允许位置：Babel 的编程式选项中，或配置文件中
添加于：v7.13.0

控制是否使用 browserslist 配置源，包括搜索 browserslist 配置文件或引用 package.json 中的 browserslist 字段。对于使用 browserslist 配置但不会被 Babel 编译的项目文件非常有用。

若指定为字符串，则必须表示 browserslist 配置文件的路径。相对路径将相对于指定此选项的配置文件解析，或当作为编程式选项传递时相对于 cwd 解析。

browserslistEnv

类型：string
默认值：undefined
允许位置：Babel 的编程式选项中，或配置文件中
添加于：v7.13.0

要使用的 Browserslist 环境。

配置合并选项

extends

类型：string
允许位置：不允许在预设内部

配置可以"扩展"其他配置文件。当前配置中的字段将合并到被扩展文件的配置之上。

env

类型：{ [envKey: string]: Options }
允许位置：不可嵌套在另一个 env 块内

允许设置完整的嵌套配置选项，这些选项仅在 envKey 匹配 envName 选项时启用。

注意：env[envKey] 选项将合并到根对象指定的选项之上。

overrides

类型：Array<Options>
允许位置：不可嵌套在另一个 overrides 对象内，也不可在 env 块内

允许提供选项数组，这些选项将逐个合并到当前配置中。此功能最好与 "test"/"include"/"exclude" 选项配合使用，为覆盖规则提供条件。例如：

JavaScript

overrides: [{
  test: "./vendor/large.min.js",
  compact: true,
}],

可用于为已知是大文件且已压缩的特定文件启用 compact 选项，告知 Babel 无需费力美化输出。

test

类型：MatchPattern | Array<MatchPattern> (MatchPattern)

若所有模式均未匹配，则当前配置对象将被视为无效并在配置处理中被忽略。此选项在 overrides 选项对象中最有用，但也允许在其他位置使用。

注意：这些开关不会影响前文所述的程序化配置选项和配置加载选项，因为它们在准备合并的配置生效之前早已被处理。

include

类型：MatchPattern | Array<MatchPattern> (MatchPattern)

此选项是 "test" 的同义词。

exclude

类型：MatchPattern | Array<MatchPattern> (MatchPattern)

若匹配任一模式，当前配置对象将被视为无效，并在配置处理过程中被忽略。该选项在overrides配置对象中最为实用，但允许在任何位置使用。

注意：这些开关不会影响前文所述的程序化配置选项和配置加载选项，因为它们在准备合并的配置生效之前早已被处理。

ignore

类型：Array<MatchPattern> (MatchPattern)
位置：不允许在预设(presets)内部使用

若匹配任一模式，Babel将立即停止当前构建的所有处理流程。例如用户可通过：

JavaScript

ignore: ["./lib"];

显式禁用对lib目录内文件的Babel编译。

注意：此选项会完全禁用文件的所有Babel处理流程。虽然有其适用场景，但也可考虑使用侵入性更低的"exclude"替代方案。

only

类型：Array<MatchPattern> (MatchPattern)
位置：不允许在预设(presets)内部使用

若所有模式均未匹配，Babel将立即停止当前构建的所有处理流程。例如用户可通过：

JavaScript

only: ["./src"];

显式启用对src目录内文件的Babel编译，同时禁用其他所有文件。

注意：此选项会完全禁用文件的所有Babel处理流程。虽然有其适用场景，但也可考虑使用侵入性更低的"test"/"include"替代方案。

源码映射(Source Map)选项

inputSourceMap

类型：boolean | SourceMap
默认值：true

设为true时，若文件包含//# sourceMappingURL=...注释，Babel将尝试从中加载输入源码映射。若未找到映射或加载解析失败，将静默放弃处理。

若提供对象类型参数，该对象将直接作为源码映射对象使用。

sourceMaps

类型：boolean | "inline" | "both"
默认值：false

• true：生成源码映射并包含在返回结果对象中

• "inline"：生成源码映射并以data URL形式附加在代码末尾，但不包含在返回结果对象中

• "both"：行为与inline相同，但会在返回结果对象中包含映射

配置文件中的选项不影响@babel/cli是否将独立的.map文件写入磁盘。当通过CLI将--source-maps选项传递给@babel/cli时，它还将控制是否写入.map文件：

• true：在磁盘上生成独立的.map文件

• "inline"：将直接写入文件，因此该文件将包含一个data:，其中包含映射

• "both"：同时生成包含 data: URL 的整合文件及独立的 .map 文件

注意：这些选项逻辑较为特殊，根据使用场景建议优先使用true并在自有代码中处理其他需求。

sourceMap

此为sourceMaps的同名选项，建议优先使用sourceMaps。

sourceFileName

类型：string
默认值：path.basename(opts.filenameRelative)（当可用时），否则为"unknown"

指定在 source map 对象中使用的文件名。

sourceRoot

类型：string

设置在生成的 source map 中使用的 sourceRoot 字段（如果需要）。

其他选项

sourceType

类型："script" | "module" | "commonjs" | "unambiguous"
默认值："module"

• "script" - 使用 ECMAScript 脚本语法解析文件。不允许 import/export 语句，文件不启用严格模式。

• "module" - 使用 ECMAScript 模块语法解析文件。文件自动启用严格模式，允许使用 import/export 语句。

• "commonjs" - 按 CommonJS 环境运行方式解析文件。建议在转换 .cjs 源文件时使用此选项。关于 "script" 和 "commonjs" 的语法差异，请参阅解析器文档。

• "unambiguous" - 如果文件中存在 import/export 语句则视为"模块"，否则视为"脚本"。

当文件类型未知时，unambiguous 非常有用，但可能导致误判，因为完全不使用 import/export 语句的模块文件也是有效的。

此选项至关重要，因为当前文件的类型既影响输入文件的解析方式，也影响某些可能向当前文件添加 import/require 的转换逻辑。

例如，@babel/plugin-transform-runtime 需要根据当前文档类型决定插入 import 声明还是 require() 调用。@babel/preset-env 的 "useBuiltIns" 选项同理。由于 Babel 默认将文件视为 ES 模块，这些插件/预设通常会插入 import 语句。设置正确的 sourceType 非常重要，因为类型错误可能导致 Babel 向本应作为 CommonJS 的文件插入 import 语句。这在编译 node_modules 依赖的项目中尤为关键，因为插入 import 语句可能使 Webpack 等工具将文件识别为 ES 模块，破坏原本可用的 CommonJS 文件。

注意：此选项不影响 .mjs 文件的解析，这类文件始终强制按 "module" 模式解析。

assumptions

类型：{ [assumption: string]: boolean }
默认值：{}
添加于：v7.13.0
可放置位置：编程式选项、配置文件和预设中均可使用

设置 Babel 可接受的假设条件以生成更精简的输出：

babel.config.json

{
  "assumptions": {
    "iterableIsArray": true
  },
  "presets": ["@babel/preset-env"]
}

详细信息请查阅假设条件文档页。

highlightCode

类型：boolean
默认值：true

在 Babel 的错误信息中高亮显示代码片段标记，提高可读性。

wrapPluginVisitorMethod

类型：(key: string, nodeType: string, fn: Function) => Function

允许用户在每次访问器执行时添加包装器，以便在 Babel 执行插件过程中观察访问器处理流程。

• key 是代表当前执行插件的简单标识字符串

• nodeType 是当前被访问的 AST 节点类型

• fn 是访问者函数本身。

用户可以返回一个替换函数，该函数应在执行所需的日志记录和分析后调用原始函数。

parserOpts

类型：{}

一个包含要传递给解析器的选项的不透明对象。

可用的解析器选项请参见解析器选项。

generatorOpts

类型：{}

一个包含要传递给代码生成器的选项的不透明对象。最常用选项请参见代码生成器选项。

代码生成器选项

retainLines

类型：boolean
默认值：false

Babel 会尽量生成代码，使项目打印位置与原始文件中的行号保持一致。此选项适用于无法使用源码映射但需要基本错误行号的场景，但这仅是最佳尝试，无法在所有插件场景中完全保证。

compact

类型：boolean | "auto"
默认值："auto"

"auto" 模式将通过 code.length > 500_000 自动设定值

在紧凑模式下生成代码时，所有可选换行符和空白字符将被省略。

minified

类型：boolean
默认值：false

包含 compact: true 设置，省略块结束分号，在可能时省略 new Foo() 中的 ()，并可能输出更短形式的字面量。

auxiliaryCommentBefore

类型：string

允许指定前缀注释，插入到原始文件中不存在的代码片段之前。

注意：原始文件中存在与否的定义可能较为复杂，因此_不建议_使用此选项。如需注释代码，建议通过 Babel 插件实现。

auxiliaryCommentAfter

类型：string

允许指定前缀注释，插入到原始文件中不存在的代码片段之后。

注意：原始文件中存在与否的定义可能较为复杂，因此_不建议_使用此选项。如需注释代码，建议通过 Babel 插件实现。

comments

类型：boolean
默认值：true

当未提供函数时，为 shouldPrintComment 设置默认的注释状态。更多信息请参见该选项的默认值说明。

shouldPrintComment

类型：(value: string) => boolean
非 minified 模式默认值：(val) => opts.comments || /@license|@preserve/.test(val)
minified 模式默认值：() => opts.comments

该函数可决定特定注释是否应包含在 Babel 的输出代码中。

高级用法

更多代码生成器选项请参见生成器选项。

AMD / UMD / SystemJS 模块选项

moduleIds

类型：boolean
默认值：!!opts.moduleId

启用模块 ID 生成功能。

moduleId

类型：string

用于模块的硬编码 ID。不可与 getModuleId 同时使用。

getModuleId

类型：(name: string) => string

接收 Babel 生成的模块名，返回要使用的名称。返回假值将保留原始 name。

moduleRoot

类型：string

要包含在生成模块名称中的根路径。

选项概念

MatchPattern（匹配模式）

类型：string | RegExp | (filename: string | void, context: { caller: { name: string } | void, envName: string, dirname: string ) => boolean

多个 Babel 选项会对文件路径执行测试。通常这些选项支持通用模式匹配，每种模式可以是：

• string - 支持 **、* 和 *.ext 的简单文件路径。匹配该模式的任何文件或父文件夹均视为匹配。路径遵循 Node 的标准路径逻辑，在 POSIX 系统中必须使用 / 分隔符，在 Windows 系统中同时支持 / 和 \。

• RegExp - 用于匹配规范化文件名的正则表达式。在 POSIX 系统中路径将使用 / 分隔符进行匹配，在 Windows 系统中则使用 \ 分隔符。

关键点：若使用上述两种模式，Babel 要求必须提供 filename 选项，否则会视为错误。

• (filename: string | void, context: { caller: { name: string } | void, envName: string, dirname: string }) => boolean 是通用回调函数，应返回布尔值表示是否匹配。该函数接收文件名（若未提供则为 undefined），同时接收由 Babel 顶层调用指定的当前 envName 和 caller 选项，以及配置文件所在目录（若以编程方式调用转换则为当前工作目录）的 dirname。

备注

基于字符串的匹配不支持完整 glob 模式。** 匹配 0 或多个路径段，* 匹配 1 个路径段，*.ext 匹配带扩展名的通配符。其他任何使用 * 的方式（例如作为路径或文件名的一部分）均不受支持。如需复杂模式匹配，请使用正则匹配或在配置中自定义函数。

以下是一些匹配机制的工作示例：

Description	Pattern	Matches	Does Not Match
Exact path matching	foo/bar	/src/foo/bar	/src/foo, /src/foo/baz, /src/foo/bar/baz
Single wildcard (*)	*/bar	/src/foo/bar, /src/xyz/bar	/src/foo/baz, /src/bar, /src/foo/bar/baz
Double wildcard (**)	**/bar	/src/bar, /src/foo/bar, /src/a/b/c/bar	/src/bar/foo, /src/barfoo
File extension pattern (*.ext)	foo/*.js	/src/foo/test.js, /src/foo/index.js/	/src/foo/test.ts, /src/foo/test.js.map
Combined patterns	**/test/*.js	/src/test/file.js, /src/a/b/test/file.js	/src/test.js, /src/test/sub/file.js

以下是 * 不具备通配功能的示例场景：

Description	Pattern	Does Not Match
Star in path	test*me/*.js	/src/testme/1.js, /src/testme/2.js, /src/test-me/3.js
Star in file name	foo*bar.js	/src/foobar.js, /src/foo-bar.js
Star in extension	file.ts*	/src/file.ts, /src/file.tsx

合并机制

请参阅 Babel 如何合并配置项。

插件/预设条目

PluginEntry / PresetEntry（插件/预设条目）

单个插件/预设条目可包含多种结构：

• EntryTarget - 独立插件

• [EntryTarget, EntryOptions] - 带配置的独立插件

• [EntryTarget, EntryOptions, string] - 带配置和名称的独立插件（名称用法详见合并机制）

• ConfigItem - 由 babel.createConfigItem() 创建的插件配置项

同一 EntryTarget 可多次使用，但需为每个实例指定不同名称，否则会触发重复插件/预设错误。

为便于理解，示例如下：

JavaScript

plugins: [
  // EntryTarget
  '@babel/plugin-transform-classes',

  // [EntryTarget, EntryOptions]
  ['@babel/plugin-transform-arrow-functions', { spec: true }],

  // [EntryTarget, EntryOptions, string]
  ['@babel/plugin-transform-for-of', { loose: true }, "some-name"],

  // ConfigItem
  babel.createConfigItem(require("@babel/plugin-transform-spread")),
],

EntryTarget（条目目标）

类型：string | {} | Function

插件（plugin）或预设（preset）目标可以来自以下几种不同的来源：

• string - 一个 require 风格的路径或插件/预设标识符。标识符将通过名称规范化处理。

• {} | Function - 通过 require() 加载后的实际插件/预设对象或函数。

EntryOptions

类型：undefined | {} | false

选项会在插件/预设执行时传递给它们。undefined 会被规范化为空对象。

false 表示该条目被完全禁用。这在顺序很重要但需要单独条件决定是否启用的场景中非常有用。例如：

JavaScript

plugins: [
  'one',
  ['two', false],
  'three',
],
overrides: [{
  test: "./src",
  plugins: [
    'two',
  ]
}]

将为 src 目录下的文件启用 two 插件，但 two 仍会在 one 和 three 之间执行。

名称规范化

默认情况下，Babel 要求插件名称包含 babel-plugin- 前缀，预设包含 babel-preset- 前缀。为避免重复，Babel 在加载时会自动添加这些前缀，主要遵循以下规则：

• 绝对路径保持不变

• 以 ./ 开头的相对路径保持不变

• 包内部的文件引用保持不变

• 任何以 module: 为前缀的标识符会移除前缀但其他部分不变

• 对于未包含前缀的 @babel 作用域包，会在开头注入 plugin-/preset-

• 对于未包含前缀的无作用域包，会注入 babel-plugin-/babel-preset- 前缀

• 对于名称中_完全不包含_ babel-plugin-/babel-preset- 的 @ 作用域包，会注入对应前缀

• 如果只给出 @ 作用域名，会将 babel-plugin/babel-preset 作为包名注入

以下是在插件上下文中的应用示例：

Input	Normalized
"/dir/plugin.js"	"/dir/plugin.js"
"./dir/plugin.js"	"./dir/plugin.js"
"mod"	"babel-plugin-mod"
"mod/plugin"	"mod/plugin"
"babel-plugin-mod"	"babel-plugin-mod"
"@babel/mod"	"@babel/plugin-mod"
"@babel/plugin-mod"	"@babel/plugin-mod"
"@babel/mod/plugin"	"@babel/mod/plugin"
"@scope"	"@scope/babel-plugin"
"@scope/babel-plugin"	"@scope/babel-plugin"
"@scope/mod"	"@scope/babel-plugin-mod"
"@scope/babel-plugin-mod"	"@scope/babel-plugin-mod"
"@scope/prefix-babel-plugin-mod"	"@scope/prefix-babel-plugin-mod"
"@scope/mod/plugin"	"@scope/mod/plugin"
"module:foo"	"foo"