Babel插件开发需精准控制AST节点识别与替换，关键在选对节点类型、避免污染标准语法、保留源码可读性，并协同运行时模块处理副作用。
直接说结论：Babel 插件开发不是“配个 preset 就完事”，而是要精准控制 AST 节点的识别与替换，业务语法转译成败取决于你是否能准确捕获自定义结构、避免污染标准语法、并在生成阶段保留源码可读性。
怎么写一个能识别业务 DSL 的 visitor
Babel 插件本质是 AST 访问器（visitor）函数集合，关键不是“写逻辑”，而是“选对节点类型”。比如你要转译 @api 装饰器或 query: { user: 'id' } 这类业务标记，不能只监听 CallExpression——它会误伤普通函数调用。
- 先用
@babel/parser把目标代码 parse 成 AST，用ast-explorer.net看真实节点结构，确认是Decorator、ObjectProperty还是自定义JSXElement - 装饰器需开启
plugins: ["decorators-legacy"]或["decoratorAutoAccessors"]，否则Decorator节点根本不会进 visitor - 匹配带特定注释的节点？得结合
path.node.leadingComments判断，比如识别// @inject-api后面的FunctionDeclaration - 别在
Program级别做全量扫描，优先用path.findParent定位上下文，减少遍历开销
@babel/plugin-transform-runtime 和自定义插件冲突吗
会，而且冲突点很隐蔽：当你的插件生成了 Promise、Object.assign 等辅助代码，而项目又启用了 @babel/plugin-transform-runtime，就可能产生重复注入或运行时引用错误。
- 你的插件里如果手动调用
path.replaceWith插入新节点，且新节点含 ES6+ 内置 API，必须显式调用addHelper（来自@babel/helper-module-imports），而不是直接写Promise.resolve() -
@babel/plugin-transform-runtime默认不处理非 Babel 官方插件生成的代码，所以你的插件要自己负责 helper 注入逻辑，或统一关闭该插件改用core-js全局 polyfill - 调试时注意
console.log(path.hub.file.opts.filename)，确认插件执行顺序——插件数组越靠前，visitor 越早执行，但 helper 注入必须在所有转换完成后才生效
为什么本地测试通过，CI 里却报错 “Unknown node type”
大概率是 Babel 版本不一致导致 AST 结构变化。2026 年主流已用 Babel 8.x，其 Decorator、ImportAttributes 等节点格式和 7.x 完全不同，而很多 CI 镜像仍默认装 7.x。
- 检查
package.json中@babel/core是否锁死版本，比如"@babel/core": "8.5.0"，而非^7.24.0 - 在插件入口加兼容判断：
if (t.isDecorator && !path.node.expression) { /* 处理 8.x 的 decorator 结构 */ } - CI 中运行
npx babel --version和node -e "console.log(require('@babel/core').version)"双验证实际加载版本 - 不要依赖
.babelrc，改用babel.config.json并启用rootMode: "root"，避免 monorepo 下子包误读父级配置
最易被忽略的一点：业务语法往往带副作用（比如自动注册路由、收集埋点字段），这类操作不能只靠 AST 替换，必须配合运行时辅助模块。你的插件生成的代码，得和 __API_REGISTRY 这样的全局对象或 import { registerApi } from './runtime' 协同工作——否则转译完只是“看起来对”，实际运行时根本没触发业务逻辑。
