Python ast.NodeTransformer 修改语法树后怎么补齐位置信息

我在写 AST 重写器时最容易漏掉的不是节点类型，而是位置字段。NodeTransformer 返回一个新节点后，如果它或它的后代没有可用的 lineno、col_offset，最后在 compile() 边界才暴露问题。稳妥的处理顺序是：替换节点先用 ast.copy_location() 对齐原节点，再对整棵树调用 ast.fix_missing_locations()，最后才编译或生成代码。

官方文档地址：https://docs.python.org/3/library/ast.html#ast.fix_missing_locations

先确认缺失位置信息出现在哪个节点

这类问题通常发生在“新建了一个节点，但没有把它放回原来的源码范围”。AST 节点的位置至少要从两个角度看：起点是 lineno 与 col_offset，较新的语法树还可能带有 end_lineno 与 end_col_offset。不要只盯着最外层节点，BinOp、Call 这类新建节点的子节点也可能是空的。

用 copy_location 继承被替换节点的位置

如果新节点代表的是原节点同一段源码的改写，先复制原位置最清楚。下面的变换把名称 price 换成乘法表达式；新表达式的根节点继承原名称的位置，内部常量则交给后续补齐。

import ast

class PriceToCents(ast.NodeTransformer):
    def visit_Name(self, node):
        # 先继续处理子节点，再只替换目标名称。
        node = self.generic_visit(node)
        if node.id != "price":
            return node
        replacement = ast.BinOp(
            left=node,
            op=ast.Mult(),
            right=ast.Constant(value=100),
        )
        # 让新表达式继承 price 原来的源码起止位置。
        return ast.copy_location(replacement, node)

tree = ast.parse("total = price")
tree = PriceToCents().visit(tree)
# 为新建的 Constant、Mult 等后代节点补齐缺失位置。
tree = ast.fix_missing_locations(tree)
code = compile(tree, filename="", mode="exec")

这里的关键不是把每个字段手工填一遍，而是明确“谁代表原来的源码片段”。若替换节点只是同一片段的另一种表达，copy_location 应该作用在替换根节点上；如果是插入了全新的语句，就不能假定它天然拥有合理的源码范围。

用 fix_missing_locations 补齐后代节点

copy_location 只处理被调用的那个节点，不会替你递归处理所有新建后代。fix_missing_locations 会从已有的父节点位置向下填充缺失字段，因此应在所有变换完成后统一调用，而不是每创建一个小节点就调用一次。

我会把它放在发布或编译边界前，形成一条固定收口：

tree = Transformer().visit(tree)
# 位置补齐只负责缺失字段，不会修复错误的节点类型。
tree = ast.fix_missing_locations(tree)

try:
    # compile 是结构和位置要求的最终边界。
    compiled = compile(tree, "", "exec")
except (TypeError, ValueError, SyntaxError) as exc:
    # 记录异常类型，区分位置问题与字段/结构问题。
    raise RuntimeError("AST 变换结果无法编译") from exc

要注意，补齐函数不会替你校验语义。例如一个 Call 缺少必须的 func，或者把表达式节点放进了语句列表，即使位置字段齐全，compile 仍然会失败。修复时先看节点结构，再看位置传播。

在 compile 边界前做反向检查

排查时可以按下面的顺序缩小范围：第一，确认 NodeTransformer 的返回值是节点、节点列表或原节点，而不是意外的 None；第二，确认替换根节点是否调用了 copy_location；第三，确认所有变换结束后才调用 fix_missing_locations；第四，再用 compile 暴露真正的结构错误。

我的经验是不要把 fix_missing_locations 当成“AST 修复器”。它只解决位置缺口，不能替换字段检查，也不能证明生成代码的语义正确。把它固定放在变换管线最后，反而更容易看清每个阶段的责任。

常见问题

copy_location 和 fix_missing_locations 能只用一个吗？

简单替换且新节点没有复杂后代时可能只够用一个，但组合使用更稳：前者表达“继承哪段源码”，后者负责补齐树中剩余的空位置。

为什么位置齐了仍然编译失败？

通常是节点字段、父子层级或返回类型不符合 AST 语法约束。位置字段只是编译条件的一部分。

是否应该给每个新节点手写行列号？

除非你在做精确的源映射工具，否则不建议。优先复制可信的原节点位置，再让补齐函数处理后代，维护成本更低。