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"