babel 7.4 配置项（翻译）

附文： babel配置：github.com/jamiebuilds…

如何写好.babelrc？Babel的presets和plugins配置解析： excaliburhan.com/post/babel-…

注意事项： 该文章请结合如下配置查看。以上文章配置为6.x babel 版本。 如下配置项为 babel 7.4版本。

主要选项

这些选项只容许做为babel编程选项的一部分，所以它们主要用于包装babel的工具，或者直接调用babel.transform的人。babel集成的用户，好比babel-loader或@babel/register，不太可能使用它们。

• cwd Type: string Default: process.cwd() 程序选项中全部路径都将相对解析的工做目录。

• caller Type: Object with a string-typed "name" property.

实用程序能够将调用方对象传递给babel，并传递与功能相关的标志，供配置、预设和插件使用。例如： babel.transformFileSync("example.js", { caller: { name: "my-custom-tool", supportsStaticESM: true }, })

容许插件和预设决定，因为支持ES模块，它们将跳过将ES模块编译为CommonJS模块的过程。

• filename Type: string

与当前正在编译的代码关联的文件名（若是有）。文件名是可选的，但当文件名未知时并不是全部babel的功能均可用，由于选项的子集依赖于文件名来实现其功能。

用户可能遇到的三个主要状况是： 该文件名向插件公开。某些插件可能须要文件名。 “test”、“exclude”和“ignore”等选项须要字符串/regexp匹配的文件名。 .babelrc文件是相对于正在编译的文件加载的。若是省略此选项，babel的行为将相似于babelrc:false已设置。

• filenameRelative Type: string Default: path.relative(opts.cwd, opts.filename)（若是传递了“filename”）。 用做babel的sourcefilename选项的默认值，并用做为amd/umd/systemjs模块转换生成文件名的一部分。

• code Type: boolean Default: true

babel的默认返回值包括代码和映射属性以及生成的代码。在对babel进行多个调用的某些状况下，禁用代码生成并使用ast:true直接获取ast可能会有所帮助，以免作没必要要的工做。

• ast Type: boolean Default: false

Babel的默认设置是生成一个字符串和一个源映射，可是在某些状况下，获取AST自己可能颇有用。

注意：这个选项在默认状况下不是打开的，由于大多数用户不须要它，并且咱们但愿最终向babel添加一个缓存层。必须缓存ast结构将占用更多的空间。

这方面的主要用例是沿着 const filename = "example.js"; const source = fs.readFileSync(filename, "utf8");

//正常加载和编译文件，但跳过代码生成。 const { ast } = babel.transformSync(source, { filename, ast: true, code: false });

在第二遍中缩小文件并在此处生成输出代码。 const { code, map } = babel.transformFromAstSync(ast, source, { filename, presets: ["minify"], babelrc: false, configFile: false, });

配置加载选项

加载配置可能会变得有点复杂，由于环境能够有几种类型的配置文件，而且这些配置文件能够有各类嵌套的配置对象，这些对象根据配置而应用。

• root Type: string Default: opts.cwd 位置：仅在Babel的编程选项中容许

将基于“rootmode”处理的初始路径，以肯定当前babel项目的概念根文件夹。这主要用于两种状况： 检查默认“configfile”值时的基目录 “babelrcroots”的默认值。

• rootMode Type: "root" | "upward" | "upward-optional" Default: "root" 位置：仅在Babel的编程选项中容许 版本：^7.1.0

这个选项与“root”值结合起来，定义了babel如何选择它的项目根。不一样的模式定义了Babel处理“根”值以获取最终项目根的不一样方式。 “root”-将“root”值做为不变值传递。 “upward”-从“root”目录向上走，查找包含babel.config.js文件的目录，若是找不到babel.config.js，则抛出错误。 “upward-optional”—从“根”目录向上走，查找包含babel.config.js文件的目录，若是找不到babel.config.js，则返回“根”。 “root”是默认模式，由于它避免了babel意外加载彻底在当前项目文件夹以外的babel.config.js的风险。若是使用“向上可选”，请注意，它将沿着目录结构一直走到文件系统根目录，而且始终可能有人在其主目录中忘记babel.config.js，这可能会致使生成中出现意外错误。

使用Monorepo项目结构（在每一个包的基础上运行构建/测试）的用户极可能但愿使用“向上”，由于Monorepo一般在项目根目录中有babel.config.js。在没有“向上”的monorepo子目录中运行babel将致使babel跳过在项目根目录中加载任何babel.config.js文件，这可能致使意外错误和编译失败。

• envName Type: string Default: process.env.BABEL_ENV || process.env.NODE_ENV || "development" 位置：仅在Babel的编程选项中容许

配置加载期间使用的当前活动环境。这个值在解析“env”配置时用做键，也能够经过api.env（）函数在配置函数、插件和预设中使用。

• configFile Type: string | boolean Default: path.resolve(opts.root, "babel.config.js"),若是存在该文件的话。不然的话为false。 位置：仅在Babel的编程选项中容许

默认为搜索默认babel.config.js文件，但能够传递任何JS或JSON5配置文件的路径。

注意：此选项不影响.babelrc文件的加载，所以尽管它可能会尝试执行配置文件：“/foo/.babelrc”，但不建议这样作。若是给定的.babelrc是经过标准的文件相对逻辑加载的，那么最终将加载同一个配置文件两次，并将其与自身合并。若是要连接特定的配置文件，建议使用独立于“babelrc”名称的命名方案。

• babelrc Type: boolean Default: 只要指定了文件名选项，就为真 位置：在babel的编程选项中，或者在加载的“configfile”中容许。编程选项将覆盖配置文件1。

若是为true，则能够搜索与提供给babel的“文件名”相关的配置文件。 程序选项中传递的babelrc值将覆盖配置文件中的一个集。 注意：.babelrc文件仅在当前“文件名”位于与其中一个“babelrcroots”包匹配的包内时加载。

• babelrcRoots Type: boolean | MatchPattern | Array Default: opts.root 位置：容许在Babel的编程选项中，或在加载的配置文件中。编程选项将覆盖配置文件1。

默认状况下，babel将只搜索“根”包中的.babelrc文件，由于不然babel将不知道是否要加载给定的.babelrc文件，或者是否已经安装了“插件”和“预设”，由于正在编译的文件可能在节点\模块中，或者已经安装了symlin参与了这个项目。 此选项容许用户提供在考虑是否加载.babelrc文件时应被视为“根”包的其余包的列表。 例如，一个Monorepo安装程序但愿容许单个软件包有本身的配置，可能但愿这样作

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

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

插件和预设选项

plugins Type: Array<PluginEntry | Plugin> (PluginEntry) Default: []

处理此文件时要激活的插件数组。有关各个条目如何交互的详细信息，尤为是在多个嵌套的“env”和“overrides”配置中使用时，请参见合并。 注意：该选项还容许babel自己的插件实例，但不建议直接使用这些实例。若是须要建立插件或预设的持久表示，则应使用babel.createConfigItem（）。

• presets Type: Array (PresetEntry) Default: []

处理此文件时要激活的预设数组。有关各个条目如何交互的详细信息，尤为是在多个嵌套的“env”和“overrides”配置中使用时，请参见合并。 注意：预设的格式与插件相同，除了名称规范化须要“preset-”而不是“plugin-”，并且预设不能是插件的实例。

• passPerPreset Type: boolean Default: false Status: Deprecated

指示babel以独立的方式运行预设数组中的每一个预设。这个选项每每会对插件的确切顺序带来不少混乱，可是若是您绝对须要在独立编译过程当中运行一组操做，那么这个选项很是有用。

注意：这个选项可能在未来的babel版本中被删除，由于咱们添加了更好的支持来定义插件之间的顺序。

配置合并选项

• extends Type: string 位置: 预设内不容许

配置能够“扩展”其余配置文件。当前配置中的配置字段将合并到扩展文件配置的顶部。

• env Type: { [envKey: string]: Options } 位置：不能嵌套在另外一个env块内。

容许整个嵌套配置选项，只有在envkey与envname选项匹配时才启用这些选项。 注意：env[envkey]选项将合并到根对象中指定的选项的顶部。

• overrides Type: Array 位置: 不能嵌套在另外一个重写对象内，也不能嵌套在env块内.

容许用户提供一组选项，这些选项将一次合并到当前配置中。此功能最好与“test”/“include”/“exclude”选项一块儿使用，以提供应用覆盖的条件。例如：

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

能够用于为一个已知大小的特定文件启用压缩选项，并告诉Babel不要费心尝试良好地打印该文件。

• test Type: MatchPattern | Array (MatchPattern)

若是全部模式都不匹配，则当前配置对象将被视为不活动，并在配置处理期间被忽略。此选项在重写选项对象中使用时最有用，但容许在任何地方使用。 注意：这些切换不会影响前面部分中的编程和配置加载选项，由于它们早在准备合并的配置以前就被考虑到了。

include

Type: MatchPattern | Array (MatchPattern)

此选项是“测试”的同义词。

• exclude Type: MatchPattern | Array (MatchPattern)

若是任何模式匹配，则当前配置对象将被视为不活动，并在配置处理期间被忽略。此选项在重写选项对象中使用时最有用，但容许在任何地方使用。 注意：这些切换不会影响前面部分中的编程和配置加载选项，由于它们早在准备合并的配置以前就被考虑到了。

• ignore Type: Array (MatchPattern) 位置:预设内不容许

若是任何模式匹配，babel将当即中止当前构建的全部处理。例如，用户可能想作相似的事情 ignore: [ "./lib", ]

显式禁用lib目录中文件的babel编译。 注意：此选项禁用文件的全部babel处理。尽管这有其用途，但也值得考虑将“排除”选项做为一种不太激进的选择。

• only Type: Array (MatchPattern) 位置：预设内不容许

若是全部模式都不匹配，babel将当即中止当前构建的全部处理。例如，用户可能想作相似的事情 only: [ "./src", ] 在禁用其余全部功能的同时，显式启用SRC目录内文件的babel编译。 注意：此选项禁用文件的全部babel处理。尽管这有其用途，但也值得考虑将“测试”/“包括”选项做为一种不太激进的选择。

Source Map配置

• inputSourceMap Type: boolean | SourceMap Default: true

true:将尝试从文件自己加载输入源映射（若是它包含//sourceMappingURL=）。注释。若是找不到映射，或者没法加载和分析映射，则将自动放弃该映射。 若是提供了一个对象，它将被视为源映射对象自己。

• sourceMaps Type: boolean | "inline" | "both" Default: false

“true”: 为代码生成源映射并将其包含在结果对象中。 “inline”生成源映射并将其做为数据URL附加到代码末尾，但不将其包含在结果对象中。 “二者”与inline相同，但将在结果对象中包含映射。

@babel/cli重载其中一些内容，以影响映射写入磁盘的方式： 若是为true，则将映射写入磁盘上的.map文件 “inline”将直接写入文件，所以它将具备一个数据：包含映射 “both”将使用如下数据写入文件：url和.map。

注意：这些选项有点奇怪，因此使用true并用本身的代码处理其他的选项多是最有意义的，这取决于您的用例。

• sourceMap

这是sourcemaps的同义词。建议使用sourcemaps。

• sourceFileName Type: string Default: path.basename（opts.filenamerelative）（若是可用）或“unknown”

用于源映射对象内的文件的名称。

• sourceRoot Type: string

要在生成的源映射中设置的sourceRoot字段（若是须要）。

Misc options

• sourceType Type: "script" | "module" | "unambiguous" Default: "module"

“script”-使用ecmascript脚本语法分析文件。不容许导入/导出语句，文件不处于严格模式。

“module”-使用ecmascript模块语法分析文件。文件自动严格，容许导入/导出语句。 “明确”-若是存在导入/导出语句，请将文件视为“模块”，不然将其视为“脚本”。 在类型未知的上下文中，无歧义很是有用，但它可能致使错误匹配，由于拥有不使用导入/导出语句的模块文件是彻底有效的。 此选项很重要，由于当前文件的类型会同时影响输入文件的分析，以及某些但愿向当前文件添加导入/须要使用的转换。 例如，@babel/plugin transform runtime依赖于当前文档的类型来决定是插入导入声明，仍是插入require（）调用。@babel/preset env对其“usebuiltins”选项也作一样的操做。因为babel默认的处理文件是es模块，所以一般这些插件/预置将插入import语句。设置正确的sourcetype可能很重要，由于拥有错误的类型会致使babel将import语句插入到本来是commonjs文件的文件中。在执行节点模块依赖项编译的项目中，这一点尤其重要，由于插入导入语句可能会致使Webpack和其余工具将文件视为ES模块，从而破坏其余功能性CommonJS文件。 注意：此选项不会影响.mjs文件的分析，由于它们当前被硬编码为始终解析为“模块”文件。

• highlightCode Type: boolean Default: true

在babel的错误消息中突出显示代码片断中的标记，以使它们更易于阅读。

• wrapPluginVisitorMethod Type: (key: string, nodeType: string, fn: Function) => Function

容许用户在每一个访问者上添加一个包装器，以便在Babel执行插件时检查访问者进程。 键是一个简单的不透明字符串，表示正在执行的插件。 nodeType是当前访问的ast节点的类型。 FN是访问者功能自己。 用户能够返回一个替换函数，该函数应该在执行了他们但愿执行的任何日志记录和分析以后调用原始函数。

• parserOpts Type: {}

一个不透明的对象，包含要传递给所使用的分析器的选项。

• generatorOpts Type: {}

代码生成器选项

• retainLines Type: boolean Default: false

Babel将努力生成代码，以便在原始文件中的同一行上打印项目。这个选项的存在是为了让不能使用源映射的用户能够获得模糊有用的错误行编号，但这只是一个最大的努力，并不能保证在全部状况下都使用全部插件。

• compact Type: boolean | "auto" Default: "auto"

“auto”将经过评估code.length>500_000来设置该值。 在紧凑模式下生成代码时，将省略全部可选的换行符和空白。

• minified Type: boolean Default: false

包括compact:true、省略块结束分号、尽量省略新foo（）中的（），并可能输出较短的文本版本。

• auxiliaryCommentBefore Type: string

容许指定在原始文件中不存在的代码段以前插入前缀注释。 注意：原始文件中存在和不存在的内容的定义可能会变得有点难看，所以不建议使用此选项。若是您须要以某种方式注释代码，最好使用babel插件进行注释。

• auxiliaryCommentAfter Type: string

容许指定在原始文件中不存在的代码段后插入前缀注释。 注意：原始文件中存在和不存在的内容的定义可能会变得有点难看，所以不建议使用此选项。若是您须要以某种方式注释代码，最好使用babel插件进行注释。

• comments Type: boolean Default: true

若是未给定函数，则为shouldprintcomment提供默认注释状态。有关详细信息，请参阅该选项的默认值。

• shouldPrintComment Type: (value: string) => boolean Default without minified: (val) => opts.comments || /@license|@preserve/.test(val) Default with minified: () => opts.comments

能够决定给定注释是否应包含在babel的输出代码中的函数。

AMD/UMD/SystemJS模块选项

• moduleIds Type: boolean Default: !!opts.moduleId

启用模块ID生成。

• moduleId Type: string

用于模块的硬编码ID。不能与GetModuleID一块儿使用。

• getModuleId Type: (name: string) => string

给定babel生成的模块名，返回要使用的名称。返回错误值将使用原始名称。

• moduleRoot Type: string

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

基本概念

• MatchPattern Type: string | RegExp | (filename: string | void, context: { callee: { name: string } | void, envName: string ) => boolean

几个babel选项对文件路径执行测试。一般，这些选项支持一种通用的模式方法，其中每一个模式均可以。 string-一个文件路径，支持*和**做为彻底段塞匹配。任何与模式匹配的文件或父文件夹都算做匹配。路径跟随的节点的正常路径逻辑，例如posix必须是/分隔的，但在Windows上同时支持/和\。

regexp-与规范化文件名匹配的正则表达式。在POSIX上，路径regexp将针对一个/分隔的路径运行，在Windows上，它将在一个分隔的路径上运行。 重要的是，若是使用其中任何一个选项，babel要求提供文件名选项，不然会将其视为错误。

（filename:string void，context:callee:name:string void，envname:string）=>boolean 是一个常规回调，它应该返回一个布尔值来指示它是否匹配。函数将传递文件名，若是没有给babel，则传递未定义的文件名。它还传递由顶级调用babel指定的当前envname和被调用方选项。

• Merging Babel的配置合并相对简单。选项在存在时将覆盖现有选项，而且其值未定义，有一些特殊状况：

Parserropts对象是使用与顶级选项相同的逻辑合并的，而不是替换的。 generatoropts对象使用与顶级选项相同的逻辑进行合并，而不是替换。 插件和预设根据插件/预设对象/函数自己的标识以及条目的名称进行替换。

插件/预设合并 例如，考虑一个配置：

plugins: [ './other', ['./plug', { thing: true, field1: true }] ], overrides: [{ plugins: [ ['./plug', { thing: false, field2: true }], ] }]

覆盖项将合并在顶级插件的顶部。重要的是，插件阵列做为一个总体，不只取代了顶级阵列。合并逻辑将看到“./plug”在这两种状况下都是相同的插件，thing:false，field2:true将替换原始选项，从而致使配置为 plugins: [ './other', ['./plug', { thing: false, field2: true }], ],

因为合并基于identity+name，所以在同一个plugins/presets数组中使用相同名称的同一个插件两次被认为是错误的。例如 plugins: [ './plug', './plug', ] 被视为错误，由于它与插件：'.'/plug']相同。此外，偶数 plugins: [ ['./plug', {one: true}], ['./plug', {two: true}] ] 被认为是错误，由于第二个老是替换第一个。 若是您确实想实例化一个插件的两个独立实例，则必须为每一个实例指定一个名称以消除它们之间的歧义。例如： plugins: [ ['./plug', {one: true}, "first-instance-name"], ['./plug', {two: true}, "second-instance-name"] ] 由于每一个实例都有一个惟一的名称，这是一个惟一的标识

• Plugin/Preset entries PluginEntry / PresetEntry 单个插件/预设项能够有几个不一样的结构：

EntryTarget-单个插件 [entryTarget，entryOptions]-带有选项的单个插件 [entryTarget，entryOptions，string]-带有选项和名称的单个插件（有关名称的详细信息，请参阅合并） configitem-由babel.createConfigitem（）建立的插件配置项。 同一EntryTarget能够屡次使用，除非为每一个EntryTarget指定了不一样的名称，不然这样作将致使重复的插件/预设错误。 这可能有点难理解，所以做为一个例子： 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 Type: string | {} | Function string-须要样式路径或插件/预设标识符。标识符将经过名称规范化传递。 {} | Function-一个实际的插件/预设对象或函数，在它被要求require（）以后。

EntryOptions Type: undefined | {} | false 选项在执行时传递给每一个插件/预设。未定义将被规范化为空对象。 false表示一个条目被彻底禁用。在排序很重要的状况下，这可能颇有用，但须要一个单独的条件来决定是否启用了某些功能。例如： plugins: [ 'one', ['two', false], 'three', ], overrides: [{ test: "./src", plugins: [ 'two', ] }]

将会为src下的文件提供two这个插件，可是two这个插件将会在one和three之间执行。

• 名称规范化

默认状况下，babel指望插件的名称中有babel插件或babel预设前缀。为了不重复，babel有一个名称规范化阶段，在加载项时会自动添加这些前缀。这能够归结为几个主要规则：

绝对的路径是不受影响的。

以/开头的相对路径未经处理。

对包中的文件的引用不会受到影响。

以module:为前缀的任何标识符都将删除前缀，不然将不会被触及。

plugin-/preset-将在没有前缀的任何@babel范围的包的开头注入。

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"