Babel 插件：30分鐘從入門到實(shí)戰(zhàn)

作者：曾昱 2022-09-30 15:46:26

本文不會(huì)深入討論它們的詳細(xì)用法，當(dāng)你在編寫插件的時(shí)候，可以根據(jù)功能需求找到它們，我們后文也會(huì)涉及到部分用法。

Babel 是一個(gè) source to source（源碼到源碼）的 JavaScript 編譯器，簡(jiǎn)單來說，你為 Babel 提供一些 JavaScript 代碼，Babel 可以更改這些代碼，然后返回給你新生成的代碼。Babel 主要用于將 ECMAScript 2015+ 代碼轉(zhuǎn)換為能夠向后兼容的 JavaScript 版本。Babel 使用插件系統(tǒng)進(jìn)行代碼轉(zhuǎn)換，因此任何人都可以為 babel 編寫自己的轉(zhuǎn)換插件，以支持實(shí)現(xiàn)廣泛的功能。

Babel 編譯流程

Babel 的編譯流程主要分為三個(gè)部分：解析（parse），轉(zhuǎn)換（transform），生成（generate）。

code -> AST -> transformed AST -> transformed code

解析 Parse

將源碼轉(zhuǎn)換成抽象語法樹（AST, Abstract Syntax Tree）。

比如：

function square(n) {
  return n * n;
}

以上的程序可以被轉(zhuǎn)換成類似這樣的抽象語法樹：

- FunctionDeclaration:
  - id:
    - Identifier:
      - name: square
  - params [1]
    - Identifier
      - name: n
  - body:
    - BlockStatement
      - body [1]
        - ReturnStatement
          - argument
            - BinaryExpression
              - operator: *
              - left
                - Identifier
                  - name: n
              - right
                - Identifier
                  - name: n

轉(zhuǎn)換 Transform

轉(zhuǎn)換階段接受一個(gè) AST 并遍歷它，在遍歷的過程中對(duì)樹的節(jié)點(diǎn)進(jìn)行增刪改。這也是運(yùn)行 Babel 插件的階段。

生成 Generate

將經(jīng)過一系列轉(zhuǎn)換之后的 AST 轉(zhuǎn)換成字符串形式的代碼，同時(shí)還會(huì)創(chuàng)建 sourcemap。

你會(huì)用到的一些工具庫

對(duì)于每一個(gè)階段，Babel 都提供了一些工具庫：

Parse 階段可以使用@babel/parser 將源碼轉(zhuǎn)換成 AST。?
Transform 階段可以使用@babel/traverse 調(diào)用 visitor 函數(shù)遍歷 AST，期間可以使用 @babel/types 創(chuàng)建 AST 和檢查 AST 節(jié)點(diǎn)的類型，批量創(chuàng)建 AST 的場(chǎng)景下可以使用 @babel/template 中途還可以使用 @babel/code-frame 打印報(bào)錯(cuò)信息。
Generate 階段可以使用@babel/generator 根據(jù) AST 生成代碼字符串和 sourcemap。

以上提及的包都是 @babel/core 的 dependencies，所以只需要安裝 @babel/core 就能訪問到它們。

除了上面提到的工具庫，以下工具庫也比較常用：

@babel/helper-plugin-utils：如果插件使用者的 Babel 版本沒有您的插件所需的 API，它能給用戶提供明確的錯(cuò)誤信息。
babel-plugin-tester：用于幫助測(cè)試 Babel 插件的實(shí)用工具，通常配合 jest 使用。

本文不會(huì)深入討論它們的詳細(xì)用法，當(dāng)你在編寫插件的時(shí)候，可以根據(jù)功能需求找到它們，我們后文也會(huì)涉及到部分用法。

認(rèn)識(shí) Babel 插件

接下來讓我們開始認(rèn)識(shí) Babel 插件吧。

babel 插件是一個(gè)簡(jiǎn)單的函數(shù)，它必須返回一個(gè)匹配以下接口的對(duì)象。如果 Babel 發(fā)現(xiàn)未知屬性，它將拋出錯(cuò)誤。

以下是一個(gè)簡(jiǎn)單的插件示例：

export default function(api, options, dirname) {
  return {
    visitor: {
      StringLiteral(path, state) {},
    }
  };
};

Babel 插件接受 3 個(gè)參數(shù)：

api：一個(gè)對(duì)象，包含了 types (@babel/types)、traverse (@babel/traverse)、template(@babel/template) 等實(shí)用方法，我們能從這個(gè)對(duì)象中訪問到 @babel/core dependecies 中包含的方法。
options：插件參數(shù)。
dirname：目錄名。

返回的對(duì)象有 name、manipulateOptions、pre、visitor、post、inherits 等屬性：

name：插件名字。
inherits：指定繼承某個(gè)插件，通過 Object.assign 的方式，和當(dāng)前插件的 options 合并。
visitor：指定 traverse 時(shí)調(diào)用的函數(shù)。
pre 和 post 分別在遍歷前后調(diào)用，可以做一些插件調(diào)用前后的邏輯，比如可以往 file（表示文件的對(duì)象，在插件里面通過 state.file 拿到）中放一些東西，在遍歷的過程中取出來。
manipulateOptions：用于修改 options，是在插件里面修改配置的方式。

我們上面提到了一些陌生的概念：visitor、path、state，現(xiàn)在讓我們一起來認(rèn)識(shí)它們：

visitor 訪問者

這個(gè)名字來源于設(shè)計(jì)模式中的訪問者模式（https://en.wikipedia.org/wiki/Visitor_pattern）。簡(jiǎn)單的說它就是一個(gè)對(duì)象，指定了在遍歷 AST 過程中，訪問指定節(jié)點(diǎn)時(shí)應(yīng)該被調(diào)用的方法。

假如我們有這樣一段程序：

function foo() {
      return 'string'
    }

這段代碼對(duì)應(yīng)的 AST 如下：

- Program
       - FunctionDeclaration (body[0])
         - Identifier (id)
         - BlockStatement (body)
           - ReturnStatement (body[0])
           - StringLiteral (arugument)

當(dāng)我們對(duì)這顆 AST 進(jìn)行深度優(yōu)先遍歷時(shí)，每次訪問 StringLiteral 都會(huì)調(diào)用 visitor.StringLiteral。

當(dāng) visitor.StringLiteral 是一個(gè)函數(shù)時(shí)，它將在向下遍歷的過程中被調(diào)用（即進(jìn)入階段）。當(dāng) visitor.StringLiteral 是一個(gè)對(duì)象時(shí)（{ enter(path, state) {}, exit(path, state) {} }），visitor.StringLiteral.enter 將在向下遍歷的過程中被調(diào)用（進(jìn)入階段），visitor.StringLiteral.exit 將在向上遍歷的過程中被調(diào)用（退出階段）。

Path 路徑

Path 用于表示兩個(gè)節(jié)點(diǎn)之間連接的對(duì)象，這是一個(gè)可操作和訪問的巨大可變對(duì)象。

Path 之間的關(guān)系如圖所示：

除了能在 Path 對(duì)象上訪問到當(dāng)前 AST 節(jié)點(diǎn)、父級(jí) AST 節(jié)點(diǎn)、父級(jí) Path 對(duì)象，還能訪問到添加、更新、移動(dòng)和刪除節(jié)點(diǎn)等其他方法，這些方法提高了我們對(duì) AST 增刪改的效率。

State 狀態(tài)

在實(shí)際編寫插件的過程中，某一類型節(jié)點(diǎn)的處理可能需要依賴其他類型節(jié)點(diǎn)的處理結(jié)果，但由于 visitor 屬性之間互不關(guān)聯(lián)，因此需要 state 幫助我們?cè)诓煌?visitor 之間傳遞狀態(tài)。

一種處理方式是使用遞歸，并將狀態(tài)往下層傳遞：

const anotherVisitor = {
  Identifier(path) {
    console.log(this.someParam) // => 'xxx'
  }
};

const MyVisitor = {
  FunctionDeclaration(path, state) {
    // state.cwd: 當(dāng)前執(zhí)行目錄
    // state.opts: 插件 options
    // state.filename: 當(dāng)前文件名(絕對(duì)路徑)
    // state.file: BabelFile 對(duì)象，包含當(dāng)前整個(gè) ast，當(dāng)前文件內(nèi)容 code，etc.
    // state.key: 當(dāng)前插件名字
    path.traverse(anotherVisitor, { someParam: 'xxx' });
  }
};

另外一種傳遞狀態(tài)的辦法是將狀態(tài)直接設(shè)置到 this 上，Babel 會(huì)給 visitor 上的每個(gè)方法綁定 this。在 Babel 插件中，this 通常會(huì)被用于傳遞狀態(tài)：從 pre 到 visitor 再到 post。

export default function({ types: t }) {
     return {
       pre(state) {
         this.cache = new Map();
       },
       visitor: {
         StringLiteral(path) {
           this.cache.set(path.node.value, 1);
         }
       },
       post(state) {
         console.log(this.cache);
       }
     };
   }

常用的 API

Babel 沒有完整的文檔講解所有的 api，因此下面會(huì)列舉一些可能還算常用的 api（并不是所有，主要是 path 和 types 上的方法或?qū)傩裕覀儾⒉恍枰勘诚聛恚谀阈枰玫臅r(shí)候，能找到對(duì)應(yīng)的方法即可。

你可以通過 babel 的 typescript 類型定義找到以下列舉的屬性和方法，還可以通過 Babel Handbook 找到它們的具體使用方法。

Babel Handbook：https://astexplorer.net/

查詢

path.node：訪問當(dāng)前節(jié)點(diǎn)
path.get()：獲取屬性內(nèi)部的 path
path.inList：判斷路徑是否有同級(jí)節(jié)點(diǎn)
path.key：獲取路徑所在容器的索引
path.container：獲取路徑的容器（包含所有同級(jí)節(jié)點(diǎn)的數(shù)組）
path.listKey：獲取容器的key
path.getSibling()：獲得同級(jí)路徑
path.findParent()：對(duì)于每一個(gè)父路徑調(diào)用 callback 并將其 NodePath 當(dāng)作參數(shù)，當(dāng) callback 返回真值時(shí)，則將其 NodePath 返回
path.find()：與 path.findParent 的區(qū)別是，該方法會(huì)遍歷當(dāng)前節(jié)點(diǎn)

遍歷

path.stop()：跳過遍歷當(dāng)前路徑的子路徑
path.skip()：完全停止遍歷

判斷

types.isXxx()：檢查節(jié)點(diǎn)的類型，如 types.isStringLiteral(path.node)
path.isReferencedIdentifier()：檢查標(biāo)識(shí)符（Identifier）是否被引用

增刪改

path.replaceWith()：替換單個(gè)節(jié)點(diǎn)
path.replaceWithMultiple()：用多節(jié)點(diǎn)替換單節(jié)點(diǎn)
path.replaceWithSourceString()：用字符串源碼替換節(jié)點(diǎn)
path.insertBefore() / path.insertAfter()：插入兄弟節(jié)點(diǎn)
path.get('listKey').unshiftContainer() / path.get('listKey').pushContainer()：插入一個(gè)節(jié)點(diǎn)到數(shù)組中，如 body
path.remove()：刪除一個(gè)節(jié)點(diǎn)

作用域

path.scope.hasBinding(): 從當(dāng)前作用域開始向上查找變量
path.scope.hasOwnBinding()：僅在當(dāng)前作用域中查找變量
path.scope.generateUidIdentifier()：生成一個(gè)唯一的標(biāo)識(shí)符，不會(huì)與任何本地定義的變量相沖突
path.scope.generateUidIdentifierBasedOnNode()：基于某個(gè)節(jié)點(diǎn)創(chuàng)建唯一的標(biāo)識(shí)符
path.scope.rename()：重命名綁定及其引用

AST Explorer

在 @babel/types 的類型定義中，可以找到所有 AST 節(jié)點(diǎn)類型。我們不需要記住所有節(jié)點(diǎn)類型，社區(qū)內(nèi)有一個(gè) AST 可視化工具能夠幫助我們分析 AST：axtexplorer.net。

在這個(gè)網(wǎng)站的左側(cè)，可以輸入我們想要分析的代碼，在右側(cè)會(huì)自動(dòng)生成對(duì)應(yīng)的 AST。當(dāng)我們?cè)谧髠?cè)代碼區(qū)域點(diǎn)擊某一個(gè)節(jié)點(diǎn)，比如函數(shù)名 foo，右側(cè) AST 會(huì)自動(dòng)跳轉(zhuǎn)到對(duì)應(yīng)的 Identifier AST 節(jié)點(diǎn)，并高亮展示。

我們還可以修改要 parse 的語言、使用的 parser、parser 參數(shù)等。

自己實(shí)現(xiàn)一個(gè)插件吧

現(xiàn)在讓我們來實(shí)現(xiàn)一個(gè)簡(jiǎn)單的插件吧！以下是插件需要實(shí)現(xiàn)的功能：

將代碼里重復(fù)的字符串字面量(StringLiteral)提升到頂層作用域。
接受一個(gè)參數(shù) minCount，它是 number 類型，如果某個(gè)字符串字面量重復(fù)次數(shù)大于等于 minCount 的值，則將它提升到頂層作用域，否則不做任何處理。

因此，對(duì)于以下輸入：

const s1 = "foo";
const s2 = "foo";

const s3 = "bar";

function f1() {
  const s4 = "baz";
  if (true) {
    const s5 = "baz";
  }
}

應(yīng)該輸出以下代碼：

var _foo = "foo",
  _baz = "baz";
const s1 = _foo;
const s2 = _foo;
const s3 = "bar";

function f1() {
  const s4 = _baz;

  if (true) {
    const s5 = _baz;
  }
}

通過 https://astexplorer.net/，我們發(fā)現(xiàn)代碼里的字符串在 AST 上對(duì)應(yīng)的節(jié)點(diǎn)叫做 StringLiteral，如果想要拿到代碼里所有的字符串并且統(tǒng)計(jì)每種字符串的數(shù)量，就需要遍歷 StringLiteral 節(jié)點(diǎn)。

我們需要一個(gè)對(duì)象用于存儲(chǔ)所有 StringLiteral，key 是 StringLiteral 節(jié)點(diǎn)的 value 屬性值，value 是一個(gè)數(shù)組，用于存儲(chǔ)擁有相同 path.node.value 的所有 path 對(duì)象，最后把這個(gè)對(duì)象存到 state 對(duì)象上，以便于在遍歷結(jié)束時(shí)能統(tǒng)計(jì)相同字符串的重復(fù)次數(shù)，從而可以判斷哪些節(jié)點(diǎn)需要被替換為一個(gè)標(biāo)識(shí)符。

export default function() {
  return {
    visitor: {
      StringLiteral(path, state) {
        state.stringPathMap = state.stringPathMap || {};
        const nodes = state.stringPathMap[path.node.value] || [];
        nodes.push(path);
        state.stringPathMap[path.node.value] = nodes;
      }
    }
  };
}

通過 https://astexplorer.net/，我們發(fā)現(xiàn)如果想要往頂層作用域中插入一個(gè)變量，其實(shí)就是往 Program 節(jié)點(diǎn)的 body 上插入 AST 節(jié)點(diǎn)。Program 節(jié)點(diǎn)也是 AST 的頂層節(jié)點(diǎn)，在遍歷過程的退出階段，Program 節(jié)點(diǎn)是最后一個(gè)被處理的，因此我們需要做的事情是：根據(jù)收集到的字符串字面量，分別創(chuàng)建一個(gè)位于頂層作用域的變量，并將它們統(tǒng)一插入到 Program 的 body 中，同時(shí)將代碼中的字符串替換為對(duì)應(yīng)的變量。

export default function() {
  return {
    visitor: {
      StringLiteral(path, state) { /** ... */ },
      Program: {
        exit(path, state) {
          const { minCount = 2 } = state.opts || {};
      
          for (const [string, paths] of Object.entries(state.stringPathMap || {})) {
            if (paths.length < minCount) {
              continue;
            }
      
            const id = path.scope.generateUidIdentifier(string);
      
            paths.forEach(p => {
              p.replaceWith(id);
            });
      
            path.scope.push({ id, init: types.stringLiteral(string) });
          }
        },
      },
    }
  };
}

完整代碼

import { PluginPass, NodePath } from '@babel/core';
import { declare } from '@babel/helper-plugin-utils';

interface Options {
  /**
   * 當(dāng)字符串字面量的重復(fù)次數(shù)大于或小于 minCount，將會(huì)被提升到頂層作用域
   */
  minCount?: number;
}

type State = PluginPass & {
  // 以 StringLiteral 節(jié)點(diǎn)的 value 屬性值為 key，存放所有 StringLiteral 的 Path 對(duì)象
  stringPathMap?: Record<string, NodePath[]>;
};

const HoistCommonString = declare<Options>(({ assertVersion, types }, options) => {
  // 判斷當(dāng)前 Babel 版本是否為 7
  assertVersion(7);

  return {
    // 插件名字
    name: 'hoist-common-string',

    visitor: {
      StringLiteral(path, state: State) {
        // 將所有 StringLiteral 節(jié)點(diǎn)對(duì)應(yīng)的 path 對(duì)象收集起來，存到 state 對(duì)象里，
        // 以便于在遍歷結(jié)束時(shí)能統(tǒng)計(jì)相同字符串的重復(fù)次數(shù)
        state.stringPathMap = state.stringPathMap || {};

        const nodes = state.stringPathMap[path.node.value] || [];
        nodes.push(path);

        state.stringPathMap[path.node.value] = nodes;
      },

      Program: {
        // 將在遍歷過程的退出階段被調(diào)用
        // Program 節(jié)點(diǎn)是頂層 AST 節(jié)點(diǎn)，可以認(rèn)為 Program.exit 是最后一個(gè)執(zhí)行的 visitor 函數(shù)
        exit(path, state: State) {
          // 插件參數(shù)。還可以通過 state.opts 拿到插件參數(shù)
          const { minCount = 2 } = options || {};

          for (const [string, paths] of Object.entries(state.stringPathMap || {})) {
            // 對(duì)于重復(fù)次數(shù)少于 minCount 的 Path，不做處理
            if (paths.length < minCount) {
              continue;
            }

            // 基于給定的字符串創(chuàng)建一個(gè)唯一的標(biāo)識(shí)符
            const id = path.scope.generateUidIdentifier(string);

            // 將所有相同的字符串字面量替換為上面生成的標(biāo)識(shí)符
            paths.forEach(p => {
              p.replaceWith(id);
            });

            // 將標(biāo)識(shí)符添加到頂層作用域中
            path.scope.push({ id, init: types.stringLiteral(string) });
          }
        },
      },
    },
  };
});

測(cè)試插件

測(cè)試 Babel 插件有三種常用的方法：

測(cè)試轉(zhuǎn)換后的 AST 結(jié)果，檢查是否符合預(yù)期
測(cè)試轉(zhuǎn)換后的代碼字符串，檢查是否符合預(yù)期（通常使用快照測(cè)試）
執(zhí)行轉(zhuǎn)換后的代碼，檢查執(zhí)行結(jié)果是否符合預(yù)期

我們一般使用第二種方法，配合 babel-plugin-tester 可以很好地幫助我們完成測(cè)試工作。配合 babel-plugin-tester，我們可以對(duì)比輸入輸出的字符串、文件、快照。

import pluginTester from 'babel-plugin-tester';
import xxxPlugin from './xxxPlugin';

pluginTester({
  plugin: xxxPlugin,
  fixtures: path.join(__dirname, '__fixtures__'),
  tests: {
    // 1. 對(duì)比轉(zhuǎn)換前后的字符串
    // 1.1 輸入輸出完全一致時(shí)，可以簡(jiǎn)寫
    'does not change code with no identifiers': '"hello";',
    // 1.2 輸入輸出不一致
    'changes this code': {
      code: 'var hello = "hi";',
      output: 'var olleh = "hi";',
    },
    // 2. 對(duì)比轉(zhuǎn)換前后的文件
    'using fixtures files': {
      fixture: 'changed.js',
      outputFixture: 'changed-output.js',
    },
    // 3. 與上一次生成的快照做對(duì)比
    'using jest snapshots': {
      code: `
        function sayHi(person) {
          return 'Hello ' + person + '!'
        }
      `,
      snapshot: true,
    },
  },
});

本文將以快照測(cè)試為例，以下是測(cè)試我們插件的示例代碼：

import pluginTester from 'babel-plugin-tester';
import HoistCommonString from '../index';

pluginTester({
  // 插件
  plugin: HoistCommonString,
  // 插件名，可選
  pluginName: 'hoist-common-string',
  // 插件參數(shù)，可選
  pluginOptions: {
    minCount: 2,
  },
  tests: {
    'using jest snapshots': {
      // 輸入
      code: `const s1 = "foo";
      const s2 = "foo";

      const s3 = "bar";

      function f1() {
        const s4 = "baz";
        if (true) {
          const s5 = "baz";
        }
      }`,
      // 使用快照測(cè)試
      snapshot: true,
    },
  },
});

當(dāng)我們運(yùn)行 jest 后（更多關(guān)于 jest 的介紹，可以查看 jest 官方文檔https://jestjs.io/docs/getting-started），會(huì)生成一個(gè) snapshots 目錄：

有了快照以后，每次迭代插件都可以跑一下單測(cè)以快速檢查功能是否正常。快照的更新也很簡(jiǎn)單，只需要執(zhí)行 jest --updateSnapshot。

使用插件

如果想要使用 Babel 插件，需要在配置文件里添加 plugins 選項(xiàng)，plugins 選項(xiàng)接受一個(gè)數(shù)組，值為字符串或者數(shù)組。以下是一些例子：

// .babelrc
{
    "plugins": [
        "babel-plugin-myPlugin1",
        ["babel-plugin-myPlugin2"],
        ["babel-plugin-myPlugin3", { /** 插件 options */ }],
        "./node_modules/asdf/plugin"
    ]
}

Babel 對(duì)插件名字的格式有一定的要求，比如最好包含 babel-plugin，如果不包含的話也會(huì)自動(dòng)補(bǔ)充。以下是 Babel 插件名字的自動(dòng)補(bǔ)全規(guī)則：

到這里，Babel 插件的學(xué)習(xí)就告一段落了，如果大家想繼續(xù)深入學(xué)習(xí) Babel 插件，可以訪問 Babel 的倉庫（https://github.com/babel/babel/tree/main/packages）這是一個(gè) monorepo，里面包含了很多真實(shí)的插件，通過閱讀這些插件，相信你一定能對(duì) Babel 插件有更深入的理解！