用Babel插件为代码自动补全import依赖：AST分析与工程实践

先说一个我自己的经历。前年接了一个维护中的中后台项目，路由文件里密密麻麻全是 const UserManage = () => import('@/views/user/UserManage') 这种写法，新增一个页面要手动加四五处代码。后来另一个模块更夸张，业务代码里到处直接写 Message.success()、Modal.confirm()，但文件顶部一个 import 都没有——因为之前是全局挂载的，重构拆模块之后全量报错。当时我就在想：这种“用到了但没引入”的问题，能不能让构建工具自动帮我补上？答案是肯定的，而且思路远比你想的简单：用 Babel 去读代码、分析 AST、找出“被使用但没被引入”的标识符，然后在语法树里把 import 插回去。这就是“用 Babel 为代码自动引入依赖”的底层逻辑，也是本文要完整展开的内容。

这篇内容适合三类人：一是被重复 import 折磨的业务开发者，二是想入门 Babel 插件开发的前端工程师，三是准备在团队里做工程化基建的工具链维护者。不需要你有多深的编译原理基础，只要写过 JavaScript、见过 Babel 配置文件，就能跟着一步步实现一个可用的自动补依赖插件。

1. 先搞清楚：哪些场景值得写一个“自动引入依赖”的 Babel 插件

1.1 三种最典型的真实需求

先说结论：不是所有“缺 import”的场面都适合用 Babel 自动补。我梳理了三个最典型、也是团队里被验证过真正能落地的场景。

场景一：按需引入 UI 组件库或工具函数库。

这是最经典的需求。组件库动辄几百个组件，全量引入会让打包体积爆炸，手动按需引入要么写一长串 import { Button } from 'antd'，要么用官方提供的 babel-plugin-import 之类的插件做样式和模块的按需加载。其实这种需求的核心也是“自动引入依赖”——你在 JSX 里写了 <Button>，插件帮你从组件库里引入这个组件，并顺带处理样式。

场景二：旧项目从全局变量迁移到模块化时的批量修复。

开头说的那个项目就属于这类。以前很多人图省事，用 Vue.use(Message) 或者直接把工具函数挂到 window 上，代码里直接用 Message.success()。后来要拆模块、做 SSR、做 Tree Shaking，这些全局变量就不能用了。你当然可以手动一个文件一个文件地加 import，但几十个文件、每个文件缺十几个依赖的时候，手工操作的效率和正确性都很成问题。这时候写一个临时的一次性 Babel 插件，自动把用到的全局标识符替换成从正确模块导入，会快得多。

场景三：基于约定的框架式开发，自动补全本应存在的导入。

比如某些业务框架约定，页面组件都放在某个目录下，只要在 JSX 里写了 <UserCard />，就自动从 @/components/UserCard 引入。这种“约定优于配置”的思路在内部脚手架里很常见。维护一个 Babel 插件比让每个人都记住手动 import 的规则可靠得多。

1.2 什么情况下不值得用 Babel 硬凑

有几种情况我不建议用 Babel 自动引入，容易把简单问题复杂化。

• 只缺一两个 import 的小文件：直接手动补上，收益不高，还亏了插件维护成本。
• 模块路径需要复杂计算才能确定：比如动态拼接路径、依赖运行时信息，Babel 是静态分析，做不了。
• 和现有的 ESLint、TS 检查规则冲突：自动引入的代码如果和团队 lint 规则不一致（比如 import 顺序、空行规范），反而会引入一堆新的 lint 报错。
• 需要读取文件系统内容才能判断：Babel 插件本身可以借助 Node.js API 读写文件，但这会显著拖慢编译速度，且缓存失效问题不好处理。能通过 AST 和静态约定解决的问题，不要拉到文件系统层。

把这些边界确认清楚，再决定是否值得动手。这里有一个判断标准：如果“缺依赖”的问题是系统性的、大范围的、有明确规律的，Babel 方案就值得做；如果只是偶发的小修小补，别折腾。

2. 写插件前必懂的 Babel 工作拆解：AST 三阶段与 Visitor 模型

2.1 代码从文本到 AST 再变回文本的完整旅程

很多人用 Babel 只用过预设和插件，比如 @babel/preset-env，平时不太关心它内部是怎么工作的。但写自定义插件，必须理解 Babel 处理代码的三个阶段：解析（Parse）、遍历（Traverse）、生成（Generate）。

解析阶段把源代码字符串变成一棵 AST（抽象语法树）。可以把 AST 理解成代码的“解剖图”：一个 const a = 1 不再是字符串，而是一个 VariableDeclaration 节点，它里面挂着 VariableDeclarator、Identifier（变量名 a）、NumericLiteral（数字 1）。遍历阶段会从上到下、从左到右访问这棵树里的每一个节点，你的插件代码就是在这个阶段被调用的。生成阶段再把修改后的 AST 重新变成代码字符串。

我常用一个生活类比：AST 就像是菜谱的分步清单，而不是“把菜名念一遍”。Babel 要做的，是在这张清单上找到某一行的“番茄”，把它改成“圣女果”，然后再把整张清单重新誊写一遍。修改的是清单本身，而不是文字替换。

为什么要基于 AST 而不是字符串替换？因为 AST 能精准区分“这是变量声明里的名字”和“这是使用处的名字”。同样是 Message，可能是变量名、对象的属性、导入的标识符，字符串硬替换很容易误伤。AST 不会，它知道每个节点的身份。比如 foo.Message.success() 里的 Message 是属性，不是独立的标识符，字符串替换会把 Message.success 错改成别的名称，但 AST 可以精准限定只处理 MemberExpression 里没被其他对象承接的属性访问。

2.2 Visitor 机制：为什么你不能只写一个 UnaryExpression 就覆盖所有情况

Babel 遍历 AST 时采用“访问者模式”（Visitor）。你的插件定义要监听哪些节点类型，Babel 在遍历到对应节点时会调用你注册的回调函数。

javascript复制module.exports = function ({ types: t }) {
  return {
    visitor: {
      Identifier(path) {
        // 每遇到一个标识符节点就会进来
      },
      JSXOpeningElement(path) {
        // 每遇到一个 JSX 开始标签就会进来
      }
    }
  };
};

每个节点类型都对应一种访问器。关键在于，Identifier 是一个非常笼统的类型，const a = 1 里的 a 是 Identifier，a + 1 里的 a 也是 Identifier，甚至 import { a } from 'x' 里的 a 还是 Identifier。如果你在 Identifier 里无脑收集名字，会把所有的声明、属性、关键字都收进来，然后就会把根