Go ast.CommentMap 为什么格式化后注释会移动

ast.CommentMap 只记录“某组注释与哪个 AST 节点相关”，并不会改写注释的 token.Pos。当你删除、替换或重排节点后直接调用 format.Node，go/printer 仍会根据 ast.File.Comments 中的原始位置把注释穿插到 token 之间，于是注释可能贴到相邻声明、留在旧位置，或者随已删除节点一起消失。

解决思路不是“格式化前再建一次 CommentMap”，而是按变换类型处理：删除节点后用 cmap.Filter(file).Comments() 重建注释列表；原位替换节点时先用 cmap.Update(old, new) 转移关联；真正把节点移动到别处时，还必须同步相关位置，因为 Update 不负责搬动 CommentGroup.Pos()。

官方文档：https://pkg.go.dev/go/ast

影响面：注释还在，却贴到了下一个声明

我第一次遇到这个问题是在一个小型源码重写器里。程序把某个顶层声明删除，再交换另外两个声明的顺序，输出能够重新解析，缩进也完全符合 gofmt 风格，但原来写在声明上方的解释性注释却跑到了下一个函数前面。最迷惑的是，我已经创建了 ast.CommentMap，所以最初把问题归咎于 format.Node。

后来把数据结构拆开看才发现，ast.File 同时保留节点树和按词法顺序排列的 Comments 列表。节点切片被我改了，注释对象里的位置却还是解析原文件时的偏移。格式化器没有丢失注释关联，它只是面对一棵“节点顺序已变、位置仍旧”的树，按已有位置做了尽可能合理的排版。

时间线：问题发生在 AST 变换之后

单纯把一份未修改的 AST 交给 format.Node，通常只会规范空白、缩进和文档注释格式。真正的触发点往往位于它之前：删除了声明却没有清理对应注释，创建了新节点却没有把旧节点的注释关联转过去，或者只交换了节点指针却保留原有 token.Pos。

下面这种写法看起来只是交换声明，但声明节点和注释都仍携带原文件的位置。输出顺序、节点位置与注释位置之间已经不再一致：

package main

import "go/ast"

func swapFirstTwoDecls(file *ast.File) {
    if len(file.Decls) 

这也是为什么“创建了 CommentMap”仍可能无效：NewCommentMap 只返回一份映射，除非后续用它执行 Filter、Update，并把结果写回 file.Comments 或替换节点，否则打印阶段根本不会自动读取这份映射来改变位置。

触发条件：CommentMap 的关联本来就是启发式

官方规则会把注释组关联到相邻节点：注释可以从与节点结束位置相同的行、紧随节点的下一行，或者下一个节点之前的位置推断归属；实现还会尽量选择“最大”的节点。例如赋值语句末尾的行注释会倾向于关联整条赋值语句，而不是最后一个操作数。

这种规则适合帮助源码工具保持大多数注释，但它无法知道作者对所有悬浮注释的语义意图。Doc 和字段上的 Comment 有明确宿主，剩余注释则可能是自由悬浮的。节点被跨区域移动后，“原来靠近谁”和“现在想跟随谁”是变换程序必须明确回答的问题。

根因：CommentMap 管关联，printer 管位置

CommentMap 的键是 ast.Node，值是与该节点相关的 CommentGroup 列表；Comments() 返回的结果仍按源位置排序。与此同时，go/printer 会读取注释位置，在输出下一个 token 之前判断哪些注释应该先写出。两个机制相互配合，却不是同一件事。

因此，格式化后注释“移动”的准确解释是：AST 变换破坏了节点顺序、节点身份和位置元数据之间的原有一致性，printer 又按仍然有效的旧位置重新穿插注释。CommentMap 能帮助保留或转移关联，但不会替你定义跨位置移动的语义。

修复动作要按删除、替换和移动分开处理

删除节点：用 Filter 清理失效关联

创建映射要发生在修改 AST 之前。删除完成后，用变换后的文件过滤映射，再把结果写回 file.Comments。这样只保留仍能在当前树中找到宿主节点的注释：

package main

import (
    "go/ast"
    "go/token"
)

func removeVarDecl(fset *token.FileSet, file *ast.File) {
    // 修改前记录原始节点与注释组的关联
    cmap := ast.NewCommentMap(fset, file, file.Comments)

    kept := file.Decls[:0]
    for _, decl := range file.Decls {
        gen, isGen := decl.(*ast.GenDecl)
        if isGen && gen.Tok == token.VAR {
            // 示例中删除所有 var 声明，不把对应注释留成悬浮注释
            continue
        }
        kept = append(kept, decl)
    }
    file.Decls = kept

    // 只保留仍属于当前 AST 节点的注释，并按源位置重建列表
    file.Comments = cmap.Filter(file).Comments()
}

Filter 的作用不是重新猜测一次关联，而是从原映射中筛掉已不在新树里的节点项。如果某条注释应当保留为文件级说明，就不能把它简单视为“跟随被删节点”；变换器需要在删除前明确转移或重建它的归属。

原位替换：用 Update 转移节点身份

替换节点时，旧节点对象不再存在于 AST。若直接 Filter，挂在旧对象上的注释也会被过滤。可以先调用 Update，把映射键从旧节点改成新节点。下面以同一位置上的标识符替换为例：

package main

import "go/ast"

func renameIdent(cmap ast.CommentMap, old *ast.Ident, name string) *ast.Ident {
    // 原位替换时沿用旧 NamePos，让打印位置保持一致
    replacement := &ast.Ident{NamePos: old.NamePos, Name: name}

    // Update 把旧节点的注释关联转给新节点，并返回新节点
    return cmap.Update(old, replacement).(*ast.Ident)
}

这个方法适用于“语义变了，但仍处在原槽位”的替换。它并不修改注释组的 Slash 位置，也不会为跨文件、跨声明重排计算新偏移。

移动节点：同步位置，不能只调用 Update

如果把一个声明从文件尾移到文件头，Update 最多能说“这些注释现在属于哪个节点”，却不能让旧偏移自动跳到文件头。官方文档明确提醒：节点被移动时，附近的相关注释也需要通过更新位置一起移动。

标准库没有一个通用的 MoveNodeAndComments API，因为不同节点包含的关键位置字段不同，悬浮注释的归属也取决于工具语义。工程上我会优先选以下策略：

• 原位改写优先：只替换目标节点内容，保留原槽位与有效位置，配合 cmap.Update。
• 删除后过滤：明确不再需要的节点连同其关联注释一起由 Filter 清理。
• 重排时成组处理：把声明及其明确的文档注释视为一个单元，同时重建节点和注释位置。
• 复杂变换重新解析：先生成具有明确注释布局的源码片段，再用新的 FileSet 解析，避免混用旧偏移和新结构。

防复发：在格式化前检查三种一致性

我现在会在源码重写器里把注释处理放进变换设计，而不是留到最终格式化时补救。每个变换至少回答三个问题：节点对象是否仍存在、节点是否仍在原位置、注释应当跟随语义宿主还是保留在原文本区域。

还要注意解析时必须带上 parser.ParseComments，并在整个变换和打印过程中使用同一个匹配的 token.FileSet。否则 CommentMap 没有完整输入，位置换算也失去共同坐标系。

常见问题

只调用 ast.NewCommentMap 能防止注释移动吗？

不能。它只创建映射，不会修改 AST、file.Comments 或 printer 行为。必须根据变换使用 Filter、Update，并把结果接回实际语法树。

cmap.Update 会自动修改注释的 token.Pos 吗？

不会。它转移的是映射中的节点键，注释组仍保留原位置。因此它适合原位替换，不足以独立完成跨位置移动。

为什么 Filter 后有些悬浮注释消失了？

因为它们在原映射中关联的节点已经不在新 AST 里。若业务希望保留这些注释，应在删除前明确转移归属，而不是期待 Filter 判断作者意图。

format.Node 是不是注释错位的根因？

通常不是。它把已经存在的位置关系转换成规范格式。更常见的根因是 AST 已被修改，但节点身份、声明顺序、File.Comments 与 token.Pos 没有一起维护。

结论

ast.CommentMap 解决的是关联维护，不是位置重排。删除节点用 Filter，原位替换用 Update，移动节点则要把注释与位置一起纳入变换。只要把“节点身份”和“文本位置”当作两套必须同步的数据，格式化后的注释就不再像是随机移动。