🧩 Vue 编译核心：transform.ts 源码深度剖析

一、概念层：什么是「Transform 阶段」？

在 Vue 3 的编译流程中，transform.ts 是核心的 AST 转换阶段（Transform Phase） 。

它的任务是将模板编译生成的抽象语法树（AST）进行语义增强与结构优化，比如：

• 把指令（v-if、v-for）转为代码生成节点；
• 标记哪些节点可以静态提升（hoist）；
• 追踪组件、指令依赖；
• 为最终代码生成（Codegen）阶段做准备。

👉 总体流程：

template → parse() → transform() → generate()

而本文分析的正是中间的 transform() 逻辑。

---

二、原理层：整体流程图

export function transform(root: RootNode, options: TransformOptions): void {
  const context = createTransformContext(root, options)
  traverseNode(root, context)
  if (options.hoistStatic) {
    cacheStatic(root, context)
  }
  if (!options.ssr) {
    createRootCodegen(root, context)
  }
  root.helpers = new Set([...context.helpers.keys()])
  root.components = [...context.components]
  root.directives = [...context.directives]
  root.imports = context.imports
  root.hoists = context.hoists
  root.temps = context.temps
  root.cached = context.cached
  root.transformed = true
}

🧠 原理说明

1. createTransformContext()

   • 构建整个转换上下文（记录状态、工具函数、缓存）。
   • 内部包含各种集合：helpers、components、hoists 等。

2. traverseNode()

   • 深度优先遍历整个 AST。
   • 在遍历中执行 nodeTransforms（节点变换器）。
   • 支持插件式扩展。

3. cacheStatic()

   • 静态节点缓存优化。

4. createRootCodegen()

   • 将转换完成的 AST 根节点生成最终可被 codegen 处理的结构（VNode 调用）。

---

三、对比层：Vue 2.x vs Vue 3 Transform 差异

对比点	Vue 2.x	Vue 3
AST 表达形式	基于字符串拼接的模板语法树	结构化、类型化的 AST
转换机制	内嵌逻辑、强耦合	插件式 NodeTransform / DirectiveTransform
静态提升	局部静态提升	全局静态提升 + 缓存机制
Helper 管理	全局工具函数	按需导入、依赖追踪
自定义指令编译	内联解析	可扩展的 DirectiveTransform

Vue 3 将编译管线模块化，使每个步骤都具备独立职责、可组合性和扩展性。

---

四、实践层：核心函数逐段解析

1️⃣ createTransformContext()

export function createTransformContext(
  root: RootNode,
  options: TransformOptions,
): TransformContext {
  const context: TransformContext = {
    filename,
    root,
    helpers: new Map(),
    components: new Set(),
    directives: new Set(),
    hoists: [],
    cached: [],
    // ...
    helper(name) {
      const count = context.helpers.get(name) || 0
      context.helpers.set(name, count + 1)
      return name
    },
    hoist(exp) {
      if (isString(exp)) exp = createSimpleExpression(exp)
      context.hoists.push(exp)
      const identifier = createSimpleExpression(
        `_hoisted_${context.hoists.length}`,
        false,
        exp.loc,
        ConstantTypes.CAN_CACHE,
      )
      identifier.hoisted = exp
      return identifier
    },
  }
  return context
}

🧩 说明

• 功能：创建整个编译过程的上下文（相当于一个「编译状态机」）。
• helper() ：记录当前使用到的运行时辅助函数（如 createVNode、toDisplayString）。
• hoist() ：实现静态提升，将不变的节点提取为 _hoisted_xx。

💬 注释讲解

helper(name) {
  const count = context.helpers.get(name) || 0  // 获取当前 helper 使用次数
  context.helpers.set(name, count + 1)           // 累计引用次数
  return name                                    // 返回 helper symbol
}

---

2️⃣ traverseNode()

export function traverseNode(node, context) {
  context.currentNode = node
  const { nodeTransforms } = context
  const exitFns = []
  for (let i = 0; i < nodeTransforms.length; i++) {
    const onExit = nodeTransforms[i](node, context)
    if (onExit) exitFns.push(onExit)
  }

  switch (node.type) {
    case NodeTypes.INTERPOLATION:
      context.helper(TO_DISPLAY_STRING)
      break
    case NodeTypes.ELEMENT:
    case NodeTypes.ROOT:
      traverseChildren(node, context)
      break
  }

  while (exitFns.length) {
    exitFns.pop()()
  }
}

🧩 说明

• 按照 深度优先遍历 (DFS) 执行节点转换。
• 每个 NodeTransform 可返回一个 退出函数（Exit Function） ，用于后序清理或反向处理。

💬 注释讲解

// 1. 执行进入阶段 transform
const onExit = nodeTransforms[i](node, context)

// 2. 深度遍历子节点
traverseChildren(node, context)

// 3. 执行退出阶段 transform（类似 Vue 生命周期的 before/after）
exitFns[i]()

---

3️⃣ createStructuralDirectiveTransform()

export function createStructuralDirectiveTransform(
  name: string | RegExp,
  fn: StructuralDirectiveTransform,
): NodeTransform {
  return (node, context) => {
    if (node.type === NodeTypes.ELEMENT) {
      const exitFns = []
      for (let i = 0; i < node.props.length; i++) {
        const prop = node.props[i]
        if (prop.type === NodeTypes.DIRECTIVE && prop.name === name) {
          node.props.splice(i, 1)
          const onExit = fn(node, prop, context)
          if (onExit) exitFns.push(onExit)
        }
      }
      return exitFns
    }
  }
}

🧩 说明

• 用于注册「结构性指令」的转换器（如 v-if、v-for）。
• 它的设计让开发者可以轻松扩展自定义指令编译逻辑。

💬 注释讲解

node.props.splice(i, 1)  
// 移除结构指令，防止重复遍历或死循环

const onExit = fn(node, prop, context)
// 执行自定义转换逻辑（如展开成条件/循环语句）

---

五、拓展层：插件式编译架构的意义

Vue 3 的 transform 体系带来了极强的可扩展性：

• 📦 插件式 NodeTransform
  可注册多个节点转换器（如 v-if、v-for、v-on 分别实现）。
• 🔁 多阶段生命周期
  类似 AST 版本的「钩子」机制。
• 🧱 结构化上下文
  每个阶段可共享编译上下文状态（组件、helper、缓存等）。

这种设计理念与 Babel、Rollup 的插件架构 十分类似，保证了灵活性与可维护性。

---

六、潜在问题与注意事项

问题点	说明
🔄 节点替换的副作用	replaceNode() 若在不当时机调用可能导致 AST 不一致。
🧮 作用域追踪	addIdentifiers() 逻辑仅在非浏览器构建中执行。
🧩 多层嵌套指令	结构性指令嵌套可能触发多次变换，需要注意执行顺序。
🧰 SSR 模式	ssr 下某些 helper 不应注入（如 TO_DISPLAY_STRING）。

---

七、结语

transform.ts 是 Vue 编译系统的"中枢神经"，连接了模板解析（Parse）与代码生成（Codegen）。

通过模块化的设计、可插拔的转换器以及完善的上下文机制，Vue 3 实现了强大的模板编译能力和高可扩展性。

---

本文部分内容借助 AI 辅助生成，并由作者整理审核。