Babel 编译与 AST 实战:从手写一个自动埋点插件说起

上周产品和数仓团队推了一套精细化数据运营方案,要求业务线在核心交易链路的所有关键交互函数里加上统一的行为埋点。第二天开晨会,几个业务同学就开始倒苦水:老项目里几十个页面、上百个点击与提交逻辑,如果全靠人肉去调 tracker.send(...),改起来枯燥乏味不说,后续代码审查和业务迭代时漏埋、错埋几乎难以避免。

当时组里有人提议在运行时通过 Monkey Patch(劫持原型链方法)来搞,但在 React 函数组件和复杂 Hooks 满天飞的今天,很多行为直接收敛在局部闭包或事件回调里,运行时劫持根本探不进去。既然运行期被动挨打,为什么不在编译期主动破局?利用 Babel 在打包生成代码之前遍历 AST(抽象语法树),自动向指定目标函数的第一行注入埋点调用,是一套既干净又不会对业务逻辑产生心智负担的做法。

重新认识 Babel:不止是语法降级工具

很多同学对 Babel 的认知往往停留在“把 ES6+ 语法转成 ES5”或者“把 JSX 转成 React.createElement”。平时配置 Webpack,也只是抄一下 @babel/preset-env 和几个插件,很少探究底层发生了什么。

从编译原理的角度看,Babel 本质上是一个典型的 Source-to-Source 编译器(转译器)。它的工作管道非常清晰,由三个核心阶段组成:

1
2
3
4
       解析 (Parse)               转换 (Transform)             生成 (Generate)
源码 ----------------> AST (抽象语法树) ---------------> 新 AST --------------> 目标代码
@babel/parser @babel/traverse @babel/generator
+ @babel/types
  1. Parse(解析):@babel/parser(以前叫 Babylon)把源码字符串进行词法分析和语法分析,转换成树状结构的 AST 对象。
  2. Transform(转换):@babel/traverse 深度优先遍历这棵 AST。各个插件在这里挂载自己的访问者(Visitor),使用 @babel/types 或 @babel/template 对目标节点进行读取、替换、插入或删除。所有 Babel 插件的核心逻辑,全都在这个阶段。
  3. Generate(生成):@babel/generator 读取被修改后的新 AST,打印成目标代码字符串,并顺便生成对应的 Source Map。

平时我们写的 Babel 插件,其实就是在 Transform 阶段插手,对特定类型的语法树节点做外科手术。

核心概念:Visitor、Path 与 Scope

在动手写代码前,必须建立起对 Babel 内部三种核心抽象的认识,否则遇到复杂嵌套时很容易写出死循环。

1. Visitor(访问者模式)

AST 是一个包含上万个节点的树形 JSON。如果让你写遍历代码,你可能会写一堆递归的 if (node.type === '...')。Babel 采用了访问者模式(Visitor Pattern):只要在插件里声明你感兴趣的节点类型,Babel 在遍历到该类型节点时就会自动调用对应的处理函数。

1
2
3
4
5
6
7
8
9
10
11
const visitor = {
// 进入任意函数声明节点时触发
FunctionDeclaration(path, state) {
console.log('遇到函数声明:', path.node.id.name);
},
// 也可以显式区分 enter 和 exit 阶段
Identifier: {
enter(path) { /* 进入标识符 */ },
exit(path) { /* 离开标识符 */ }
}
};

2. Node 与 Path 的区别

初学者最容易混淆的是 node 和 path:

  • node:纯粹的 AST 节点数据(纯数据对象),记录了当前语法的属性,比如 type: "Identifier", name: "handleClick"。它不包含父子关系的上下文,也不知道自己挂在哪条分支上。
  • path:Babel 包装在 node 外层的一个反应式句柄。它记录了当前节点在整棵树里的位置、父节点是谁(path.parentPath)、上下文作用域是什么(path.scope),并提供了强大的树操作方法,比如 path.replaceWith()、path.remove()、path.findParent()。

写插件时,除了少数直接构造节点的场景,绝大部分时间我们打交道的都是 path。

3. @babel/types 与 @babel/template

要在 AST 里无中生有插入一段代码,有两种流派:

第一种是用 @babel/types(通常缩写为 t)。它提供了非常严谨的构造函数,比如创建一个方法调用 tracker('click'):

1
2
3
4
5
6
t.expressionStatement(
t.callExpression(
t.identifier('tracker'),
[t.stringLiteral('click')]
)
);

逻辑虽然清晰,但如果需要插入一整段包含判断逻辑的代码,纯手工用 t.* 去拼装 AST 会让人写到怀疑人生。

第二种是用 @babel/template。它允许我们直接用模板字符串写出接近正常的 JavaScript 代码,由工具自动预编译成 AST 节点,体验要舒畅得多:

1
2
3
4
5
6
7
8
9
10
11
12
import template from '@babel/template';

const buildTracker = template.statement(`
tracker.send({
eventId: EVENT_ID,
timestamp: Date.now()
});
`);

const trackerNode = buildTracker({
EVENT_ID: t.stringLiteral('user_click')
});

在工业级插件里,通常将两者结合:细粒度的属性检查和标识符生成用 @babel/types,大块的代码片段注入用 @babel/template。

手写一个自动埋点插件

我们要实现的目标:
在业务代码里,只要开发者在函数上方写了特定形式的注释(例如 /* @autotrack: order_submit_click */),或者匹配到了特定的函数名规则,Babel 在编译时就自动向该函数体内最顶部注入一行 _tracker('order_submit_click');同时在文件顶部自动引入埋点 SDK 依赖,避免手动 import。

步骤一:自动处理模块导入

如果一个文件里有函数被插桩了,但该文件本身没有引入埋点库,编译出来的代码一跑就会报 ReferenceError: _tracker is not defined。

所以插件的第一件事,是检测当前模块是否已经导入了埋点 SDK;如果没导,就在文件顶部动态插入 import _tracker from 'tracker-sdk'。

我们可以监听顶层的 Program 节点:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
const { addDefault } = require('@babel/helper-module-imports');

function ensureTrackerImport(path, state) {
// 如果当前文件已经注入过,直接返回之前生成的标识符
if (state.trackerIdentifier) {
return state.trackerIdentifier;
}

let trackerId = null;

// 遍历所有顶层 import 声明,检查是否已经由用户手动引入过
path.traverse({
ImportDeclaration(importPath) {
if (importPath.node.source.value === 'tracker-sdk') {
const specifier = importPath.node.specifiers.find(
s => s.type === 'ImportDefaultSpecifier'
);
if (specifier) {
trackerId = specifier.local.name;
}
}
}
});

// 如果没有引入,使用官方 helper 生成一个无冲突的唯一标识符并注入 import 语句
if (!trackerId) {
trackerId = addDefault(path, 'tracker-sdk', {
nameHint: '_tracker'
}).name;
}

state.trackerIdentifier = trackerId;
return trackerId;
}

这里用到了官方工具库 @babel/helper-module-imports。它的好处是如果文件里已经有个变量叫 _tracker,它会自动递增重命名为 _tracker2,天然保证作用域安全。

步骤二:识别目标函数与注释提取

JavaScript 里的函数有多种声明形态:普通函数声明、函数表达式、以及箭头函数:

1
2
3
4
5
6
7
8
// 1. 函数声明
function handleSubmit() { ... }

// 2. 赋值形式的函数表达式
const handlePay = function() { ... };

// 3. 箭头函数
const handleCancel = () => { ... };

为了方便统一处理,我们可以直接监听函数的函数体 BlockStatement,或者用一个辅助函数统一处理各种函数类型。这里我们挑选最常用的三种节点:FunctionDeclaration、FunctionExpression、ArrowFunctionExpression。

怎么判断一个函数需要埋点?最灵活的策略是通过 Leading Comments(前置注释)传参:

1
2
3
4
/* @autotrack: button_confirm_click */
function onConfirm() {
saveData();
}

在 Babel 的 AST 节点上,前置注释被保存在 node.leadingComments 数组中。我们写一个正则去匹配它:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
const TRACK_COMMENT_REGEX = /@autotrack:\s*([\w-]+)/;

function getTrackEventId(path) {
// 注意:如果是 const fn = () => {},注释可能挂在父级的 VariableDeclaration 上
const targetNode = path.parentPath.isVariableDeclaration()
? path.parentPath.node
: path.node;

const comments = targetNode.leadingComments;
if (!comments || !comments.length) {
return null;
}

for (const comment of comments) {
const match = TRACK_COMMENT_REGEX.exec(comment.value);
if (match) {
return match[1]; // 返回捕获到的 eventId
}
}

return null;
}

这里踩过一个坑:对于 const handleClick = () => {} 这种写法,开发者写的注释在语法分析时是挂在 VariableDeclaration(变量声明语句)上的,而不是箭头函数本身的节点上。如果不顺着 path.parentPath 往上找一步,就会丢失注释。

步骤三:注入埋点代码节点

找到目标函数并拿到了 eventId,接下来就是在函数体最前头插入一段 AST。

但这里必须防御一种特殊情况:单表达式箭头函数。
例如:const getRatio = () => 0.75;
这种箭头函数的 body 是一个普通的表达式节点(NumericLiteral),而不是包含语句列表的 BlockStatement。如果直接对其执行 unshift 操作,编译器会直接报错。

我们需要先把它转化为块级作用域:

1
2
3
4
5
6
7
8
if (!path.get('body').isBlockStatement()) {
// 将 () => expr 转换为 () => { return expr; }
path.get('body').replaceWith(
t.blockStatement([
t.returnStatement(path.node.body)
])
);
}

统一变成 BlockStatement 之后,就可以用 @babel/template 组装 AST 节点并插入了:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
const template = require('@babel/template').default;

const buildTrackerCall = template.statement(`
TRACKER_ID(EVENT_ID, {
path: window.location.pathname
});
`);

function insertTrackerCall(path, trackerId, eventId) {
const bodyPath = path.get('body');

// 检查是否已经注入过,防止多次遍历造成重复插桩
const hasInjected = bodyPath.node.body.some(stmt => {
return stmt._injectedByAutoTrack;
});
if (hasInjected) return;

const trackerNode = buildTrackerCall({
TRACKER_ID: t.identifier(trackerId),
EVENT_ID: t.stringLiteral(eventId)
});

// 打上自定义私有标记
trackerNode._injectedByAutoTrack = true;

// 插入到函数体第一行
bodyPath.unshiftContainer('body', trackerNode);
}

完整插件组装

把上面的模块串起来,输出一个标准的 Babel 插件接口:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
// plugins/babel-plugin-auto-track.js
const { addDefault } = require('@babel/helper-module-imports');
const template = require('@babel/template').default;

const TRACK_COMMENT_REGEX = /@autotrack:\s*([\w-]+)/;

module.exports = function ({ types: t }) {
const buildTrackerCall = template.statement(`
TRACKER_ID(EVENT_ID, {
path: window.location.pathname
});
`);

return {
name: 'babel-plugin-auto-track',
visitor: {
Program: {
enter(path, state) {
state.trackerImportId = null;
state.needInjectImport = false;
},
exit(path, state) {
// 如果该文件内确实有函数触发了插桩,且原文件没引入 SDK,统一在 exit 阶段注入 import
if (state.needInjectImport && !state.trackerImportId) {
addDefault(path, 'tracker-sdk', {
nameHint: '_tracker'
});
}
}
},

'FunctionDeclaration|FunctionExpression|ArrowFunctionExpression'(path, state) {
// 1. 查找注释
const targetNode = path.parentPath.isVariableDeclaration()
? path.parentPath.node
: path.node;

const comments = targetNode.leadingComments;
if (!comments || !comments.length) return;

let eventId = null;
for (const c of comments) {
const match = TRACK_COMMENT_REGEX.exec(c.value);
if (match) {
eventId = match[1];
break;
}
}
if (!eventId) return;

// 2. 标记需要注入模块导入
state.needInjectImport = true;

// 3. 规范化函数体
if (!path.get('body').isBlockStatement()) {
path.get('body').replaceWith(
t.blockStatement([
t.returnStatement(path.node.body)
])
);
}

// 4. 插入埋点
const bodyPath = path.get('body');
const alreadyInjected = bodyPath.node.body.some(s => s._injected);
if (alreadyInjected) return;

const callNode = buildTrackerCall({
TRACKER_ID: t.identifier('_tracker'),
EVENT_ID: t.stringLiteral(eventId)
});
callNode._injected = true;

bodyPath.unshiftContainer('body', callNode);
}
}
};
};

测试验证与编译对比

用 @babel/core 写一个简易的测试脚本跑一下看效果:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
// test.js
const babel = require('@babel/core');
const autoTrackPlugin = require('./plugins/babel-plugin-auto-track');

const sourceCode = `
/* @autotrack: click_checkout_btn */
function onCheckout(price) {
console.log('正在支付:', price);
}

/* @autotrack: submit_form */
const submitForm = (data) => post('/api/order', data);
`;

const output = babel.transformSync(sourceCode, {
plugins: [autoTrackPlugin]
});

console.log(output.code);

运行输出的代码:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
import _tracker from "tracker-sdk";

/* @autotrack: click_checkout_btn */
function onCheckout(price) {
_tracker("click_checkout_btn", {
path: window.location.pathname
});

console.log('正在支付:', price);
}

/* @autotrack: submit_form */
const submitForm = data => {
_tracker("submit_form", {
path: window.location.pathname
});

return post('/api/order', data);
};

整个过程干净利落:顶层自动按需注入了 import _tracker from "tracker-sdk",单行简写箭头函数被平滑展开并塞入了追踪调用,而业务代码里的正常参数和业务逻辑丝毫不受影响。

两个容易踩翻车的细节

在真实的工程落地中,编译器插件比日常业务代码更严苛,因为一旦写出 bug,影响的是整个工程的构建产物。

1. 递归死循环与 unshiftContainer

很多刚接触 Babel 的同学喜欢在 Visitor 里使用 path.replaceWith() 或 bodyPath.unshiftContainer() 插入新节点。
Babel 默认会把新插入的节点也当成普通的语法节点继续遍历。如果你的 Visitor 匹配规则很宽泛(比如匹配了 CallExpression),而你插入的正好也是一个 CallExpression,遍历器就会周而复始地命中你刚插入的新节点,最终导致调用栈溢出(Maximum call stack size exceeded)。

避免死循环的两种标准操作:

  • 通过 path.skip() 跳过当前路径后续子节点的遍历。
  • 在自定义生成的节点上打一个私有属性标记(如 node._injected = true),在 Visitor 入口先做短路判断。

2. 作用域遮蔽(Variable Shadowing)

在我们的例子里,如果业务代码本身在局部或者全局定义了一个叫 _tracker 的变量:

1
2
3
4
5
6
const _tracker = 'some custom value';

/* @autotrack: buy */
function buy() {
// 如果直接调用 _tracker(...),运行时就会抛错:_tracker is not a function
}

这就是为什么推荐使用 @babel/helper-module-imports 或 path.scope.generateUidIdentifier('_tracker') 的原因。Babel 的 Scope 体系会自动检查当前作用域与上层作用域的所有 Binding 绑定,如果发现同名冲突,它会生成唯一的 _tracker2,并把所有引用的标识符自动对齐,保证作用域绝对安全。

写在最后

很多人觉得“编译原理”高深莫测,非得写个词法分析器或者手撸虚拟机才算入门。其实在日常前端工程化体系里,Babel 已经把底层的词法解析、CFG 树构造等脏活累活全封装好了。

学会操纵 AST,本质上是给前端开发者打开了上帝视角:
你不再是一个被动遵从语法规则的编写者,而是拥有了把代码当作“数据结构”随意修剪、编排的能力。除了本文的无侵入自动埋点,像生产环境自动剔除特定的 console.log、根据代码特征自动补充 i18n 翻译字典、或者大规模重构时的 Codemod 脚本,底层全是同一套 Visitor + Path 变换的套路。花一两天把这套机制啃透,工程收益比多学几个 API 实在得多。

------ 有问题请 留言给我哦! 也欢迎入群讨论! 点我呀! ------

评论加载中…

0%