Go ast.File.Pos 为什么跳过文件头注释

ast.File.Pos() 返回的是 package 声明的位置，所以文件头注释和此前空白位于它之前。这不是解析器丢失了注释。需要完整文件的起点时，应使用 FileStart；需要包文档注释时，再读取 Doc 并判断是否为空。

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

位置转换文档：https://pkg.go.dev/go/token

先确定需要的是文件起点还是语法节点起点

给源码加版权头、保留构建约束或抽取包文档，虽然都接触文件顶部，却有不同的范围需求。把 Pos() 一律理解成“文件第一个字节”，会使拷贝结果从 package 开始，看上去像头部被截掉。

FileStart 描述整个文件的开始，File.Pos() 描述 package 声明的开始。File.Doc 是与文件关联的文档注释组，它不是“文件前面所有内容”的容器；空白、分隔的注释组以及构建约束需要按各自语义处理。开启 parser.ParseComments 可以保留供工具处理的注释信息，但不会把 Pos 的含义改成注释起点。

用同一份源码比较三个位置

下面的完整示例使用内存源码，避免磁盘文件变动影响比较。它展示文件起点、package 起点和关联文档注释起点的区别，读者可保存为 Go 程序运行观察；图片不表示执行记录。

package main

import (
    "fmt"
    "go/parser"
    "go/token"
    "log"
)

func main() {
    // 保留这份原始字节，后续所有偏移都对应它。
    src := []byte("// Package sample 演示文件头。\npackage sample\nvar Count = 1\n")
    fs := token.NewFileSet()
    f, err := parser.ParseFile(fs, "sample.go", src, parser.ParseComments)
    if err != nil {
        log.Fatal(err) // 解析失败时不把部分 AST 当作完整文件。
    }
    tf := fs.File(f.FileStart)
    if tf == nil || !f.Pos().IsValid() {
        log.Fatal("缺少有效的文件位置")
    }
    start, pkg := tf.Offset(f.FileStart), tf.Offset(f.Pos())
    if start  len(src) {
        log.Fatal("源码范围不匹配")
    }
    // %q 保留换行等转义，方便观察 package 前的原始内容。
    fmt.Printf("文件起点偏移=%d，package 偏移=%d\n", start, pkg)
    fmt.Printf("文件头=%q\n", src[start:pkg])
    if f.Doc != nil {
        fmt.Printf("文档注释起点偏移=%d\n", tf.Offset(f.Doc.Pos()))
    }
}

这份输入以注释开头，随后紧接 package 声明。观察时，文件头切片应包含注释及换行，package 起点应落在注释之后。若删掉头部注释，使输入直接从 package 开始，两个起点的字节偏移就可以相同。二者相同或不同，都不能单独说明解析有误。

token.Pos 是文件集中的位置值，不能直接用 int(f.Pos()) 当作源码数组下标。使用所属 token.File 的 Offset 方法，才能得到对应文件内的字节偏移。这里的范围判断服务于示例输入契约，并不把来自任意文件集的 AST 自动修复为可信数据。

按保留文件头的目标选择范围

如果目标是取得 package 之前的原始头部，就使用同一次解析的源字节和区间 [FileStart, File.Pos())。该区间包含 package 前面的所有字节，包括空白；它不是“只包含注释”的抽取器。提取特定注释组时，应依据注释组自己的 Pos 和 End。

如果目标是保留整份源码，最直接的做法是持有并使用原始 src；不必借 AST 节点范围重建原文件。FileEnd 与 FileStart 面向完整文件，而 File.End() 的含义是最后一个声明的末尾，不能据此假定文件末尾空白与游离注释也包含在内。

把位置语义纳入源码工具的处理约定

源码工具可以采用一个固定约定：读取后持有字节快照，用同一 FileSet 解析，按照任务选择文件范围、声明范围或注释范围，再把位置换成该快照的偏移。只要重写或重新读取了源码，就应重新建立相关位置关系，避免拿旧 AST 的偏移切新文本。

修改包注释时，还要区分“改注释的语义内容”和“保留原有排版”。注释对象不能保存原文件的所有空白。使用打印器或格式化工具输出属于另一种重建策略；需要字节级保留时，应保留未修改的原始区间。不要为补回文件头而硬减一个固定行数，头部长度和换行编码并没有这样的保证。

速查表与常见问题

增加 ParseComments 后，Pos 会移到注释开头吗？

不会。解析模式影响注释信息的保留，Pos 仍表达 package 声明的位置。

File.Doc 为空就能认定文件没有注释吗？

不能。文件可能含有其他位置或未关联为包文档的注释。是否保留完整注释列表，还与解析模式有关。

手工构造的 ast.File 也可以直接读取 FileStart 吗？

字段可以未设置。官方解析器产生的位置语义不能替代你对手工节点的初始化约定；读取前应检查必要位置和文件归属，不能把零值当有效字节范围。