翻譯Babel文檔之@babel/preset-env

Babel已成爲前端工程化開發的必備工具鏈, 而@babel/preset-env(babel7.0 之後的插件與預設以@babel爲前綴)是經常使用的一組預先設定的插件, Babel中文網暫未對該部份內容作翻譯, 本文是對Babel英文官方文檔中@babel/preset-env內容的翻譯, 前端小xuo生英語渣渣水平有限, 歡迎指正與交流

@babel/preset-env

@babel/preset-env是一個智能的babel預設, 讓你能使用最新的JavaScript語法, 它會幫你轉換成代碼的目標運行環境支持的語法, 提高你的開發效率並讓打包後的代碼體積更小

安裝

使用npm

npm install --save-dev @babel/preset-env
複製代碼

使用yarn

yarn add @babel/preset-env --dev
複製代碼

運行機制

@babel/preset-env依賴了一些優秀的開源項目, 如browserslist, compat-table, electron-to-chromium...

咱們利用這些數據源維護和加強Babel語法轉換、語法實現, 來支持對應的目標環境的版本的語法、特徵

注意@babel/preset-env不支持stage-x的插件

@babel/preset-env利用你指定的任何目標環境, 檢查它們對應的插件並傳給Babel

瀏覽器列表集合

對基於瀏覽器或者Electron的項目, 咱們推薦使用一個.browserslistrc文件指定編譯目標.若是你已經有了這個配置文件, 它將被不少前段工程化生態的工具利用到, 好比 autoprefixer, stylelint, eslint-plugin-compat...

若是沒有配置targets或者ignoreBrowserslistConfig, @babel/preset-env將使用默認的Browserslist配置

若是你想支持市場份額大於0.25%並且忽略安全更新的瀏覽器如IE 10和BlackBerry的語法轉換和語法實現, 你能夠採用以下的配置

{
  "presets": [
    [
      "@babel/preset-env",
      {
        "useBuiltIns": "entry"
      }
    ]
  ]
}
複製代碼

.browserlistrc

> 0.25%
not dead
複製代碼

或者你能夠在package.json文件裏配置

"browserslist": "> 0.25%, not dead"
複製代碼

配置項

若是你想獲取更多關於配置項和預設的文檔, 可參考preset options文檔

targets

數據類型: string | Array<string> | { [string]: string }, 默認 {}

描述你的項目支持的目標環境

其能夠是一個browserslist-compatible查詢語句

{
  "targets": "> 0.25%, not dead"
}
複製代碼

或者是一個描述支持的最小的環境版本的對象

{
  "targets": {
    "chrome": "58",
    "ie": "11"
  }
}
複製代碼

環境如: chrome, opera, edge, firefox, safari, ie, ios, android, node, electron

注意, 若是不指定targets, @babel/prest-env會將全部的ECMAScript 2015+代碼按照默認的配置去轉換

咱們不推薦這樣使用, 由於這樣沒有利用到其支持特定瀏覽器的能力

{
  "presets": ["@babel/preset-env"]
}
複製代碼

targets.esmodules

數據類型: boolean

若是你代碼運行的瀏覽器支持ES Modules(www.ecma-international.org/ecma-262/6.…), 當指定以下的配置, browers字段將被忽略, 你能夠配合<script type="module"></script>專門爲用戶提供更小體積的代碼文件(jakearchibald.com/2017/es-mod…)

請注意: 若是這樣指定esmodules編譯目標, browsers字段將被忽略

{
  "presets": [
    [
      "@babel/preset-env",
      {
        "targets": {
          "esmodules": true
        }
      }
    ]
  ]
}
複製代碼

targets.node

數據類型: string | "current" | true

若是你的編譯針對當前的node版本, 你能夠指定node配置項, 若是你指定爲curren, 將等同於 "node": process.versions.node

targets.safari

數據類型: string | "tp"

若是你將針對Safari瀏覽器的技術預覽版technology preview版本去編譯, 能夠指定"safari": "tp"

targets.browsers

數據類型: string | Array<string>

一個利用browserlist的查詢選項, 如last 2 versions, > 5%, safari tp

注意, browsers的結果將被targets中衝突的項目覆寫

注意: 這個配置項將在後期的版本里被移除, 利於只直接設置targets成一個查詢語句

spec

數據類型: boolean, 默認爲false

爲一些容許的可是潛在的會比較慢的插件或者預設作配置

loose

數據類型: boolean, 默認爲false

容許支持loose transformations的插件或者預設

modules

數據類型: "amd" | "umd" | "systemjs" | "commonjs" | "cjs" | "auto" | false, 默認爲 "auto"

允轉換ES6模塊語法爲其餘的模塊類型

設置爲false將不會轉換模塊

注意cjs是commonjs的一個別名

debug

數據類型: boolean, 默認爲false

console.log輸出編譯目標或者使用的插件在plugin data version中指定的版本

include

數據類型: Array<string|RegExp>, 默認爲[]

一個常常包含的插件的數組

合法的配置包括:

• Babel plugins, @babel/plugin-transform-spread與不帶前綴的plugin-transform-spread都支持
• Built-ins(同時支持cores-js@2和cores-js@3, 如es.map, es.set, 或者es.object.assign)

插件的名字能夠用完整的或者部分的去指定, 或者使用正則表達式

能夠接收的輸入:

• 全稱(string): "es.math.sign"
• 部分名稱(string): "es.math.*"(解析爲全部以es.math爲前綴的插件)
• 正則(Object): /^transform-.*$/ 或者 new RegExp("^transform-modules-.*")

注意以上正則表達式裏的.至關於匹配全部的字符, 不只僅是.字符. 並且注意正則表達式裏.*與glob裏*相反

若是一個原生的實現或者一節結合了不支持的特性加上支持的特性失效時, 這個選項對於debug會頗有用

例如, Node 4支持原生的classes可是不支持spread, 若是super和參數spread一塊兒使用, @babel/plugin-transform-classes須要被include, 否則的話就不可能被轉譯

注意: include和exclude選項僅在插件被預設包含時纔會生效, 因此, 舉個例子, 包含@babel/plugin-proposal-do-expressions, 或者排除@babel/plugin-proposal-function-bind將會報錯, 若是要時候用預設裏不包含的插件, 請直接將其添加至plugins

exclude

數據類型: Array<string|RegExp>, 默認爲[]

一個記錄不包含或者移除的插件的數組

可能的配置與include選項相似

這個選項至關於黑名單, 若是你不使用generators並且當配置useBuiltIns時不想包含regeneratorRuntime, 或者利用其它如fast-async的插件替換Babel's async-to-gen

useBuiltIns

數據類型: "usage" | "entry" | false, 默認false

這個選項配置了@babel/preset-env如何處理polyfill

當usage或者entry選項被使用, @babel/preset-env將直接飲用cores-js模塊至關於暴露imports或者requries, 這一位置core-js將被直接解析到文件自己並且須要可訪問

由於@babel/polyfill在Babel 7.4.0已被廢棄, 咱們推薦直接添加core-js和經過corejs選項設置版本

npm install core-js@3 --save

# or

npm install core-js@2 --save
複製代碼

useBuiltIns: 'entry'

注意: 你的整個app裏只能使用一次import "core-js 和import "regenerator-runtime/runtime". 若是你正在使用@babel/polyfill, 其已包含了core-js和regenerator-runtime: 若是屢次引入它或報錯.屢次引入這些包將致使全局的衝突和其它難易追蹤的問題. 咱們推薦建立一個只包含import聲明的單入口文件

當須要根據不一樣的基於環境的入口須要引入不一樣的core-js時, 這個選項容許一個新的插件來替換import "core-js/stable"和import "regenerator-runtime/runtime"聲明(或者require("corejs")和require("regenerator-runtime/runtime"))

In

import "core-js";
複製代碼

Out(基於不一樣的環境)

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提案:

In

import "core-js/es/array";
import "core-js/proposals/math-extensions";
複製代碼

Out(基於不一樣的環境)

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. 這種行爲已被廢棄, 由於不可能與@babel/polyfill使用不一樣的core-js版本

useBuiltIns: 'usage'

當文件裏被使用時, 添加特定的引入來語法填充, 咱們利用它, 一個打包的文件只會加載一次相同的語法填充

In

a.js

var a = new Promise();
複製代碼

b.js

var b = new Map();
複製代碼

Out(若是環境須要語法填充)

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

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

Out(若是環境支持該語法)

var a = new Promise();
複製代碼

var b = new Map();
複製代碼

useBuiltIns: false

不在每個文件自動添加語法填充, 不轉換import "core-js"和import "@babel/polyfill"爲單獨的語法填充

corejs

數據結構: 2, 3 或者 { version: 2 | 3, proposals: boolean }, 默認爲 2

這個選項只會在與useBuiltIns: usage或者useBuiltIns: entry一塊兒使用時纔會生效, 確保@babel/preset-env爲你的core-js版本注入了正確的引入