demo地址

当前 /dom-source-lab/ast Demo 中，页面标题最终被渲染为：

<h2 data-source-id="ast_77e4b5c037">
  源码位置由 AST 自动采集。
</h2>

DOM 里没有文件路径，也没有行号。完整位置保存在独立映射表中：

{
  "ast_77e4b5c037": {
    "file": "src/app/dom-source-lab/ast/Fixture.source.tsx",
    "start": { "line": 17, "column": 9 },
    "end": { "line": 17, "column": 33 },
    "nodeId": "ast_77e4b5c037",
    "tagName": "h2",
    "confidence": 1
  }
}

用户选择标题时，工具先从 DOM 读取 ast_77e4b5c037，再用它查询映射表，最终定位到原始 TSX 的第 17 行。

这就是当前 AST 方案的核心：在源码仍然具有完整语义时生成节点身份，再让这个身份进入运行时 DOM。

1. 为什么需要 AST

手工行号标记可以直接这样写：

<h2
  data-source-file="Fixture.tsx"
  data-source-line="17"
  data-source-column="9"
>
  源码位置
</h2>

它简单，但代码前面增加一行后，后续行号都可能发生偏移。

AST 方案不要求开发者手工填写位置。解析器可以直接从语法节点中得到文件、起止行列和节点类型：

node.loc.start.line
node.loc.start.column
node.loc.end.line
node.loc.end.column

开发者只需要编写正常的 JSX：

<h2>源码位置由 AST 自动采集。</h2>

转换脚本负责生成节点 ID 和位置映射。

2. 当前 Demo 的处理流程

当前实现没有修改 Next.js 全局编译器，而是使用一个独立预编译脚本：

Fixture.source.tsx
  → Babel Parser
  → JSX AST
  → 遍历宿主节点
  → 注入 data-source-id
  → Fixture.generated.tsx
  → fixture-map.json

页面渲染的是生成文件：

import { AstFixture } from './Fixture.generated';

源码面板展示的仍然是原始 Fixture.source.tsx。这样既能让浏览器获得节点 ID，也不会让用户看到注入后的中间代码。

3. 解析 TSX

转换脚本首先读取原始 Fixture，然后使用 Babel Parser 解析：

const sourceCode = await readFile(
  path.join(projectRoot, sourceFile),
  'utf8',
);

const ast = parse(sourceCode, {
  sourceType: 'module',
  sourceFilename: sourceFile,
  plugins: ['jsx', 'typescript'],
});

解析结果不再是一段普通文本，而是一棵包含语法关系和位置信息的树。

下面这段 JSX：

<section>
  <h2>标题</h2>
</section>

可以简化理解为：

JSXElement: section
  ├── JSXOpeningElement
  ├── JSXElement: h2
  │   ├── JSXOpeningElement
  │   └── JSXText
  └── JSXClosingElement

AST 知道 h2 是 JSX 元素，而不是字符串、注释或属性值。这是它比正则表达式可靠的主要原因。

4. 寻找宿主节点

不是所有 JSX 节点都会生成真实 DOM。

下面这些小写标签通常会生成宿主元素：

<div />
<button />
<svg />
<path />

而这些节点不一定对应 DOM：

<UserCard />
<Fragment />
<>...</>

当前转换器只处理名称以小写字母开头的 JSXIdentifier：

traverse(ast, {
  JSXOpeningElement(nodePath) {
    const { name } = nodePath.node;

    if (!t.isJSXIdentifier(name)) return;
    if (!/^[a-z]/.test(name.name)) return;

    // 生成映射
  },
});

自定义组件调用不会被直接标记，但它实现内部真正渲染到 DOM 的小写标签仍然会参与转换。

5. 生成确定性节点 ID

节点 ID 不能使用运行时随机数。如果服务端和客户端分别生成不同值，可能导致水合不一致，重新构建后也无法稳定查询映射。

当前 Demo 使用以下信息生成 ID：

源码文件路径
+ JSX 标签名
+ AST 结构路径

生成过程：

const identity =
  `${sourceFile}:${tagName}:${structuralPath}`;

const nodeId = `ast_${createHash('sha1')
  .update(identity)
  .digest('hex')
  .slice(0, 10)}`;

最终得到：

ast_77e4b5c037

节点 ID 不直接依赖行号。在文件前方增加普通代码时，ID 有机会保持不变，映射位置则会自动更新。

它也不是绝对稳定的。如果插入同级 JSX、移动节点或改变嵌套关系，AST 结构路径可能变化，节点 ID 也会变化。

6. 记录原始位置

Babel 节点的 loc 保存了语法位置。转换器将它写入映射表：

sourceMap[nodeId] = {
  file: sourceFile,
  start: {
    line: loc.start.line,
    column: loc.start.column + 1,
  },
  end: {
    line: end.line,
    column: end.column + 1,
  },
  nodeId,
  tagName: name.name,
  confidence: 1,
};

Babel 的列号从 0 开始，而编辑器通常从 1 开始展示，因此这里需要加 1。

相比只保存一个行号，起止位置可以支持更多能力：

• 高亮完整 JSX 节点；
• 定位元素的开始和结束；
• 修改对应源码区间；
• 判断多个节点是否存在包含关系。

7. 向 JSX 注入短 ID

得到节点 ID 后，转换器向 JSXOpeningElement 添加属性：

attributes.push(
  t.jsxAttribute(
    t.jsxIdentifier('data-source-id'),
    t.stringLiteral(nodeId),
  ),
);

转换前：

<h2>源码位置由 AST 自动采集。</h2>

转换后：

<h2 data-source-id="ast_77e4b5c037">
  源码位置由 AST 自动采集。
</h2>

DOM 中只携带短 ID，不包含 data-source-file、data-source-line 和 data-source-column。这可以减少 DOM 体积，也能避免直接暴露项目目录结构。

8. 生成代码和映射表

转换完成后，Babel Generator 将 AST 重新输出为 TSX：

const output = generate(
  ast,
  { comments: true },
  sourceCode,
);

脚本会生成两个文件：

Fixture.generated.tsx
fixture-map.json

源代码：

编译后的代码：

映射表：

项目通过生命周期脚本确保产物存在：

{
  "scripts": {
    "generate:dom-source-ast":
      "node scripts/generate-dom-source-ast.mjs",
    "predev":
      "npm run generate:dom-source-ast",
    "prebuild":
      "npm run generate:dom-source-ast"
  }
}

运行开发服务或生产构建前，AST 产物都会重新生成。

9. 从 DOM 查询映射

运行时映射器不需要解析源码，只需读取节点 ID：

const sourceElement =
  element.closest<HTMLElement>('[data-source-id]');

const nodeId = sourceElement?.dataset.sourceId;

取得 ID 后，映射器调用查询接口：

const query = new URLSearchParams({ id: nodeId });

const response = await fetch(
  `/api/dom-source-lab/ast-location?${query}`,
);

服务端从生成的 JSON 中查找位置，源码面板再根据返回的 file 和 start.line 读取原始文件并高亮目标行。

10. 动态列表如何映射

源码中的循环只有一个 JSX 模板节点：

{items.map((item, index) => (
  <div key={`${item}-${index}`}>
    <span>{index + 1}</span>
    <strong>{item}</strong>
  </div>
))}

无论循环渲染多少个 DOM 实例，它们都携带相同的 sourceNodeId。这符合“跳转到源码”的语义，因为这些实例来自同一个模板节点。

如果工具还需要区分运行时实例，就要额外记录：

sourceNodeId：源码模板节点
instanceId：具体渲染实例

AST 只能建立源码身份，不能自动解决运行时实例身份。

11. AST 方案的优势

11.1 位置自动生成

开发者不再手工维护 data-source-line。源码前面增加代码后，只需重新运行转换脚本，位置映射就会自动更新。

11.2 能理解语法结构

AST 可以区分 JSX 元素、自定义组件、宿主标签、Fragment、属性、表达式、文本和 SVG 节点。正则表达式只能看到字符，无法可靠处理跨行属性、嵌套表达式和字符串中的特殊符号。

11.3 DOM 信息更少

手工行号方案需要输出文件、行、列和 ID，AST 方案只输出：

data-source-id="ast_77e4b5c037"

完整位置保存在独立映射表中。

11.4 映射结果确定

运行时文本匹配可能遇到多个相同按钮，XPath 也可能因为结构变化而失效。显式注入的节点 ID 不需要在运行时猜测来源。

11.5 可以承载更多源码信息

映射表还可以继续记录：

{
  nodeId,
  tagName,
  componentName,
  start,
  end,
  parentNodeId,
  attributes,
  framework
}

这为源码跳转、可视化编辑、组件树分析和代码修改提供了扩展空间。

11.6 与选择器解耦

DomPicker 仍然只负责返回 Element：

DomPicker
  → AstMapper
  → Mapping API
  → SourceLocation

后续增加 Source Map 或运行时匹配时，不需要修改 DOM 选择器。

12. AST 方案的劣势

12.1 增加构建复杂度

项目多了一条生成链路：

原始源码
→ AST 转换
→ 生成源码
→ 映射表
→ Next.js 编译

任何一步没有执行，都可能导致生成文件缺失或映射表过期。

12.2 存在生成文件管理问题

当前 Demo 同时存在：

Fixture.source.tsx
Fixture.generated.tsx
fixture-map.json

开发者必须明确哪个文件可以编辑。误改生成文件后，下一次生成会覆盖修改，代码审查中也可能出现较大的生成代码差异。

12.3 开发期间不会自动持续更新

当前脚本会在 predev 执行一次，但开发服务启动后继续修改 Fixture.source.tsx，生成文件不会自动变化。

需要手工执行：

npm run generate:dom-source-ast

更完整的开发体验需要增加文件监听，或者把转换逻辑接入 Babel、SWC 或 Webpack。

12.4 节点 ID 不是绝对稳定

当前 ID 包含 AST 结构路径。插入同级 JSX、移动节点或改变嵌套关系后，节点 ID 可能变化。

如果 ID 被用于持久化协作状态，还需要引入局部内容哈希、相似度匹配或 ID 迁移策略。

12.5 只能直接标记宿主元素

自定义组件不一定生成单个 DOM，也不一定会把未知属性传给内部元素。因此当前转换器跳过自定义组件调用，只处理其实现内部的小写标签。

AST 方案能够回答“这个 DOM 来自哪个宿主 JSX 节点”，但不能天然回答“它属于哪个业务组件实例”。

12.6 DOM 与 AST 仍然不是一一对应

条件渲染会让 AST 节点没有 DOM，循环会让一个节点产生多个 DOM，Fragment 不产生实体节点，Portal 会把 DOM 渲染到其他容器，虚拟列表只渲染可见实例。

AST 提供了可靠的源码身份，但不能单独描述完整运行时关系。

12.7 映射表必须与生成代码同步

如果 DOM 来自新版本生成代码，而服务端仍加载旧映射表，节点 ID 可能查询不到，或者指向错误位置。

生成代码和映射表应该被视为同一批构建产物。正式系统最好增加 buildId，避免跨版本误匹配。

12.8 多语言需要不同解析器

当前实现处理 Babel 能够解析的 TSX。如果项目还包含 Vue、Svelte、Angular 模板、原生 HTML 或自定义 DSL，就需要对应的解析器和转换插件。

AST 是一种映射思路，不是一套可以直接覆盖所有前端语言的统一语法树。

12.9 仍然存在源码泄露风险

DOM 不再包含文件路径，但映射 API 仍然能够返回源码位置，源码读取接口也能返回文件内容。

因此仍然需要文件白名单、权限校验、开发环境开关、构建版本校验，并在生产环境默认关闭源码接口。

13. 与手工行号方案对比

手工方案适合验证产品交互，AST 方案适合继续构建正式能力。

14. 为什么当前选择独立预编译

更彻底的方案是编写 Babel 或 SWC 插件，让业务文件在 Next.js 编译期间自动完成转换。

当前 Demo 没有直接这样做，因为全局插件还会带来服务端和客户端重复编译、热更新、并行构建写入、编译缓存、多入口产物合并和 Next.js 编译器兼容性等问题。

独立预编译只处理一个 Fixture，影响范围明确，生成结果也容易观察。等映射模型、节点 ID 和运行时查询稳定后，再升级为正式编译插件，成本会更可控。

15. 下一步演进

第一步是增加监听模式：

Fixture.source.tsx 发生变化
→ 自动重新生成代码和映射表

第二步是为映射表增加构建版本：

{
  buildId: '20260821-abc123',
  nodes: {
    ast_77e4b5c037: { ... }
  }
}

第三步是增强节点身份稳定性，结合文件路径、AST 结构路径、标签类型、局部属性和附近文本。

第四步是接入 Source Map，让映射链继续穿过多阶段转换：

DOM
→ AST nodeId
→ 生成代码位置
→ Source Map
→ 原始源码位置

最后再考虑组件实例、循环 key 和运行时上下文：

sourceNodeId
+ componentInstanceId
+ listKey
+ buildId

16. 结论

AST 方案解决的不是“如何在页面中搜索一个相似标签”，而是“如何在源码仍然具有完整语义时，为节点建立身份”。

当前 Demo 的核心链路是：

原始 TSX
→ AST 解析
→ 确定性节点 ID
→ 生成代码和映射表
→ DOM 携带短 ID
→ 运行时查询源码位置

它比手工行号更可靠，也更适合扩展源码编辑能力，但代价是引入构建流程、生成产物和节点稳定性问题。

如果目标只是做一次演示，手工行号更便宜。如果目标是持续维护的源码定位、可视化编辑器或低代码平台，AST 才是更值得继续建设的主链路。