@babel/preset-env

@babel/preset-env 是一個智慧預設值，讓您無需微觀管理目標環境所需的語法轉換（以及瀏覽器多重載入），即可使用最新的 JavaScript。這讓您的生活更輕鬆，JavaScript 捆綁也更小！

安裝
如何運作？
瀏覽器清單整合
選項

安裝

npm
Yarn
pnpm

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

yarn add --dev @babel/preset-env

pnpm add --save-dev @babel/preset-env

如何運作？

@babel/preset-env 若非仰賴許多優秀的開源專案，例如 browserslist、compat-table 和 electron-to-chromium，將無法實現。

我們利用這些資料來源來維護哪些版本的支援目標環境支援 JavaScript 語法或瀏覽器功能的對應，以及這些語法和功能對應至 Babel 轉換外掛和 core-js 多重載入的對應。

注意

@babel/preset-env 因為在 TC39 程序的這個階段，任何瀏覽器都無法實作，因此不會包含任何低於第 3 階段的 JavaScript 語法建議。這些建議必須手動包含。shippedProposals 選項將包含一些瀏覽器已實作的第 3 階段建議。

@babel/preset-env 會採用任何您指定的目標環境，並根據其對應關係檢查它們，以編譯外掛程式的清單，並將其傳遞給 Babel。

瀏覽器清單整合

對於基於瀏覽器或 Electron 的專案，我們建議使用 .browserslistrc 檔案來指定目標。您可能已經有這個設定檔，因為生態系統中的許多工具都使用它，例如 autoprefixer、stylelint、eslint-plugin-compat 等。

預設情況下，@babel/preset-env 將使用瀏覽器清單設定來源，除非目標或 ignoreBrowserslistConfig 選項已設定。

提示

如果您依賴 browserslist 的預設查詢（明確指定或沒有 browserslist 設定檔），您會想要查看沒有目標部分，以取得 preset-env 行為的資訊。

例如，僅包含瀏覽器市佔率 >0.25% 使用者所需的 polyfill 和程式碼轉換（忽略沒有安全更新的瀏覽器，例如 IE 10 和 BlackBerry）

babel.config.json
{
  "presets": [
    [
      "@babel/preset-env",
      {
        "useBuiltIns": "entry",
        "corejs": "3.22"
      }
    ]
  ]
}

.browserslistrc

> 0.25%
not dead

或

package.json

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

注意

請注意，自 v7.4.5 起，browserslist 查詢會以 mobileToDesktop: true 解析。例如，如果您想要建立查詢的快照，請執行 npx browserslist --mobile-to-desktop ">0.25%, not dead"。

選項

如需設定預設選項的更多資訊，請參閱預設選項文件。

`targets`

字串 | 陣列<字串> | { [字串]: 字串 }，預設為頂層 targets 選項，如果在 @babel/preset-env 的文件沒有指定與 browserslist 相關的選項，否則為 {}。

關於用法，請參閱 targets 選項文件。

`bugfixes`

布林值，預設為 false。

新增於：v7.9.0

注意

此選項將在 Babel 8 中預設啟用。

預設情況下，@babel/preset-env（以及一般的 Babel 外掛程式）會將 ECMAScript 語法功能分組為緊密相關的較小功能集合。這些群組可能很大，並包含許多邊緣情況，例如「函式引數」包含解構、預設和 rest 參數。根據此分組資訊，Babel 會根據您指定給 @babel/preset-env 的 targets 選項的瀏覽器支援目標來啟用或停用每個群組。

啟用此選項時，@babel/preset-env 會嘗試將有問題的語法編譯為目標瀏覽器支援的最近 無問題的現代語法。根據您的 targets 以及您使用多少現代語法，這可能會大幅縮小已編譯應用程式的規模。此選項會合併 @babel/preset-modules 的功能，而無需使用另一個預設。

`spec`

布林值，預設為 false。

為此預設中支援它們的任何外掛程式啟用更符合規格但可能較慢的轉換。

注意

此選項已棄用，並將在 Babel 8 中移除。考慮移轉至頂層的 assumptions，自 Babel 7.13 起可用。請參閱 "從 @babel/preset-env 的 "loose" 和 "spec" 模式移轉"，以取得等效的基於假設的組態，可複製並貼上作為起點。

`loose`

布林值，預設為 false。

針對此預設中允許的任何外掛啟用 "鬆散" 轉換。

注意

`modules`

"amd" | "umd" | "systemjs" | "commonjs" | "cjs" | "auto" | false，預設為 "auto"。

啟用將 ES 模組語法轉換為其他模組類型的功能。請注意，cjs 只是 commonjs 的別名。

將此設定為 false 將保留 ES 模組。僅當您打算將原生 ES 模組發佈到瀏覽器時才使用此設定。如果您使用 Babel 搭配打包器，預設的 modules: "auto" 永遠是首選。

`modules: "auto"`

預設情況下，@babel/preset-env 使用 caller 資料來判斷是否應轉換 ES 模組和模組功能（例如 import()）。通常，caller 資料會在打包器外掛中指定（例如 babel-loader、@rollup/plugin-babel），因此不建議您自行傳遞 caller 資料——傳遞的 caller 可能覆寫打包器外掛中的 caller，而且如果打包器支援新的模組功能，您在未來可能會得到次佳的結果。

`debug`

布林值，預設為 false。

輸出至 console.log 由 preset-env 啟用的 polyfill 和轉換外掛，以及需要它們的目標（如果適用）。

`include`

Array<string|RegExp>，預設為 []。

歷史

版本	變更
`v7.4.0`	支援注入 `core-js@3` polyfill

始終包含的外掛陣列。

有效的選項包括任何

Babel 外掛 - 支援完整和簡寫名稱，例如以下功能等效：
- @babel/plugin-transform-spread
- @babel/transform-spread
- babel-transform-spread
- transform-spread
內建（適用於 core-js@2 和 core-js@3，例如 es.map、es.set 或 es.object.assign）。

外掛名稱可以完整或部分指定（或使用 RegExp）。

可接受的輸入

完整名稱（string）："es.math.sign"
部分名稱（string）："es.math.*"（解析為所有前綴為 es.math 的外掛）
RegExp 物件：/^transform-.*$/ 或 new RegExp("^transform-modules-.*")

請注意，上述 . 是 RegExp 等同於比對任何字元的符號，而不是實際的 '.' 字元。另外請注意，在 RegExp 中使用 .* 來比對任何字元，而不是 glob 格式中的 *。

如果原生實作有錯誤，或是不支援的功能與支援的功能結合時無法運作，這個選項會很有用。

例如，Node 4 支援原生類別，但不支援展開。如果 super 與展開引數一起使用，則需要 include @babel/plugin-transform-classes 轉換，因為否則無法轉譯帶有 super 的展開。

注意

include 和 exclude 選項僅適用於此預設值包含的外掛程式；因此，例如，包含 @babel/plugin-proposal-do-expressions 或排除 @babel/plugin-proposal-function-bind 會擲回錯誤。若要使用此預設值未包含的外掛程式，請將它們直接新增至您的 "plugins"。

`exclude`

Array<string|RegExp>，預設為 []。

永遠排除/移除的外掛程式陣列。

可能的選項與 include 選項相同。

此選項適用於排除轉換，例如 @babel/plugin-transform-regenerator，例如，如果您使用 fast-async 等其他外掛程式，而不是 Babel 的 async-to-gen。

`useBuiltIns`

"usage" | "entry" | false，預設為 false。

此選項設定 @babel/preset-env 如何處理 polyfill。

當使用 usage 或 entry 選項時，@babel/preset-env 會將直接參考新增至 core-js 模組作為裸入 (或需要)。這表示 core-js 會相對於檔案本身解析，且需要能夠存取。

由於 @babel/polyfill 已在 7.4.0 中棄用，我們建議直接新增 core-js，並透過 corejs 選項設定版本。

npm
Yarn
pnpm

npm install core-js@3 --save

# or

npm install core-js@2 --save

yarn add core-js@3

# or

yarn add core-js@2

pnpm add core-js@3

# or

pnpm add core-js@2

`useBuiltIns: 'entry'`

歷史

版本	變更
`v7.4.0`	它取代 `"core-js/stable"` 和 `"regenerator-runtime/runtime"` 輸入項
`v7.0.0`	它取代 `"@babel/polyfill"` 輸入項

提示

在你的整個應用程式中僅使用 import "core-js"; 一次。

如果你正在使用 @babel/polyfill，它已經包含 core-js：重複輸入它會擲回錯誤。

這些套件的重複輸入或需要可能會導致全域衝突和其他難以追蹤的問題。我們建議建立一個僅包含 import 陳述式的單一輸入檔案。

此選項啟用一個新的外掛程式，它會根據環境用個別輸入取代 import "core-js/stable"; 和 require("core-js"); 陳述式，輸入至不同的 core-js 輸入點。

在

JavaScript
import "core-js";

輸出（根據環境而異）

JavaScript
import "core-js/modules/es.string.pad-start";
import "core-js/modules/es.string.pad-end";

輸入 "core-js" 會為每個可能的 ECMAScript 功能載入多重填補：如果你知道你只需要其中一些功能怎麼辦？當使用 core-js@3 時，@babel/preset-env 能夠最佳化每個 core-js 輸入點及其組合。例如，你可能只想要多重填補陣列方法和新的 Math 提議

在

JavaScript
import "core-js/es/array";
import "core-js/proposals/math-extensions";

輸出（根據環境而異）

JavaScript
import "core-js/modules/es.array.unscopables.flat";
import "core-js/modules/es.array.unscopables.flat-map";
import "core-js/modules/esnext.math.clamp";
import "core-js/modules/esnext.math.deg-per-rad";
import "core-js/modules/esnext.math.degrees";
import "core-js/modules/esnext.math.fscale";
import "core-js/modules/esnext.math.rad-per-deg";
import "core-js/modules/esnext.math.radians";
import "core-js/modules/esnext.math.scale";

你可以閱讀 core-js 的文件，以取得關於不同輸入點的更多資訊。

注意

當使用 core-js@2 時（明確使用 corejs: "2" 選項或隱含使用），@babel/preset-env 也會轉換 @babel/polyfill 的輸入和需要。此行為已棄用，因為無法使用不同 core-js 版本的 @babel/polyfill。

`useBuiltIns: 'usage'`

當在每個檔案中使用多重填補時，為它們新增特定輸入。我們利用打包器只會載入一次相同多重填補的事實。

在

a.js
var a = new Promise();

b.js
var b = new Map();

輸出（如果環境不支援）

a.js
import "core-js/modules/es.promise";
var a = new Promise();

b.js
import "core-js/modules/es.map";
var b = new Map();

輸出（如果環境支援）

a.js
var a = new Promise();

b.js
var b = new Map();

`useBuiltIns: false`

不要自動為每個檔案加入 polyfill，也不要將 import "core-js" 或 import "@babel/polyfill" 轉換為個別的 polyfill。

`corejs`

新增於：v7.4.0

字串或 { 版本：字串，建議：布林值 }，預設為 "2.0"。版本字串可以是任何受支援的 core-js 版本。例如，"3.33" 或 "2.0"。

此選項僅在與 useBuiltIns: usage 或 useBuiltIns: entry 搭配使用時才有作用，並確保 @babel/preset-env 注入 core-js 版本所支援的 polyfill。建議指定次要版本，否則 "3" 將會被解譯為 "3.0"，可能不包含最新功能的 polyfill。

預設情況下，只會注入穩定 ECMAScript 功能的 polyfill：如果您想要 polyfill 建議，您有三個不同的選項

使用 useBuiltIns: "entry" 時，您可以直接匯入建議 polyfill：import "core-js/proposals/string-replace-all"。
使用 useBuiltIns: "usage" 時，您有兩個不同的替代方案：
- 將 shippedProposals 選項設定為 true。這將啟用 polyfill 和已在瀏覽器中發布一段時間的建議轉換。
- 使用 corejs: { version: "3.8", proposals: true }。這將啟用由 core-js@3.8 支援的所有建議的 polyfilling。

`forceAllTransforms`

布林值，預設為 false。

範例

透過 Babel 7 的 JavaScript 設定檔支援，如果 env 設為 production，你可以強制執行所有轉換。

babel.config.js
module.exports = function(api) {
  return {
    presets: [
      [
        "@babel/preset-env",
        {
          targets: {
            chrome: 59,
            edge: 13,
            firefox: 50,
          },
          // for uglifyjs...
          forceAllTransforms: api.env("production"),
        },
      ],
    ],
  };
};

危險

targets.uglify 已過時，且將在下一主要版本中移除，改用此選項。

預設情況下，此預設值將執行目標環境所需的所有轉換。如果你想強制執行所有轉換，請啟用此選項，這在輸出將透過 UglifyJS 或僅支援 ES5 的環境執行時很有用。

提示

如果你需要支援 ES6 語法的替代縮小程式，我們建議使用 Terser。

`configPath`

字串，預設為 process.cwd()

將開始瀏覽器清單設定檔搜尋的起點，並向上遞迴至系統根目錄，直到找到為止。

`ignoreBrowserslistConfig`

布林值，預設為 false

切換是否使用 browserslist 設定來源，其中包括搜尋任何 browserslist 檔案或參照 package.json 中的 browserslist 鍵。這對使用 browserslist 設定檔處理不會由 Babel 編譯的檔案的專案很有用。

`browserslistEnv`

新增於：v7.10.0 字串，預設為 undefined

要使用的 Browserslist 環境。

`shippedProposals`

布林值，預設為 false

歷史

版本	變更
`v7.14.0`	包含私有欄位品牌檢查
`v7.12.0`	包含類別靜態區塊和匯入斷言
`v7.10.0`	包含類別屬性和私有方法
`v7.9.0`	包含數字分隔符號

切換啟用對已在瀏覽器中發布的內建/功能建議的支援。如果目標環境原生支援某項功能建議，則會啟用其對應的解析器語法外掛程式，而非執行任何轉換。請注意，這並不會啟用與 @babel/preset-stage-3 相同的轉換，因為建議在發布到瀏覽器之前可能會持續變更。

目前支援下列項目

使用 useBuiltIns: "usage" 時注入的內建函式

esnext.global-this（僅受 core-js@3 支援）
esnext.string.match-all（僅受 core-js@3 支援）

功能

已具體化的功能這些功能在舊版 Babel 中位於 shippedProposals 旗標之後。它們現在已普遍可用。

您可以在此處閱讀有關設定預設值選項的更多資訊

注意事項

無效的 browserslist 查詢

雖然 op_mini all 是有效的 browserslist 查詢，但 preset-env 目前會忽略它，原因是缺乏 Opera Mini 的支援資料。

安裝​

如何運作？​

瀏覽器清單整合​

選項​

targets​

bugfixes​

spec​

loose​

modules​

modules: "auto"​

debug​

include​

exclude​

useBuiltIns​

useBuiltIns: 'entry'​

useBuiltIns: 'usage'​

useBuiltIns: false​

corejs​

forceAllTransforms​

configPath​

ignoreBrowserslistConfig​

browserslistEnv​

shippedProposals​

注意事項​

無效的 browserslist 查詢​

安裝

如何運作？

瀏覽器清單整合

選項

`targets`

`bugfixes`

`spec`

`loose`

`modules`

`modules: "auto"`

`debug`

`include`

`exclude`

`useBuiltIns`

`useBuiltIns: 'entry'`

`useBuiltIns: 'usage'`

`useBuiltIns: false`

`corejs`

`forceAllTransforms`

`configPath`

`ignoreBrowserslistConfig`

`browserslistEnv`

`shippedProposals`

注意事項

無效的 browserslist 查詢