Go token.Pos 为什么不能直接当字节偏移使用

在 Go 的 AST、语法扫描器或代码检查工具里，节点通常只给出一个 token.Pos。它看起来像整数，却不是当前文件的字节下标：这个值属于整个 token.FileSet 的位置空间，里面还包含文件基址和其他文件的区间。直接把它拿去切片，轻则定位偏移，重则把另一个文件的坐标当成当前文件使用。

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

token.Pos 属于 FileSet 坐标，不是文件切片下标

token.Pos 的底层表示确实是整数，但这个整数的含义是“在 FileSet 中的位置”。添加文件时，token.FileSet.AddFile 会为它分配一个基址；对于文件内偏移 offset，位置关系可以理解为 int(pos) = base + offset。多个文件因此拥有不重叠的整数区间。

这也是直接写 src[int(node.Pos()):] 不可靠的原因。即使只有一个文件，基址也未必是零；如果是多个文件，位置值更不可能直接对应某一个 []byte。token.NoPos 还代表无效位置，不能被当成源文件开头。

先定位所属文件，再转换文件内偏移

拿到 AST 节点位置后，推荐把“归属判断”和“偏移转换”写成一个小函数。FileSet.File 会根据位置所在区间返回对应的 *token.File；找不到文件时返回 nil。确认文件后，Offset 才是适合访问源内容的从零开始字节偏移。

// locatePosition 把 FileSet 位置转换为当前文件可用的字节偏移。
func locatePosition(fset *token.FileSet, pos token.Pos) (string, int, token.Position, bool) {
    // NoPos 没有对应文件，先挡住无效位置。
    if !pos.IsValid() {
        return "", 0, token.Position{}, false
    }

    file := fset.File(pos)
    if file == nil {
        return "", 0, token.Position{}, false
    }

    // Offset 会扣除 FileSet 基址，返回文件内的字节偏移。
    offset := file.Offset(pos)
    position := file.Position(pos)
    return file.Name(), offset, position, true
}

这里的 offset 才能用于 src[offset:] 这类字节切片。官方文档还规定了越界处理：位置在文件起点之前时返回 0，超过文件末尾时返回文件大小。因此它适合做边界收敛，但不代表调用方可以跳过位置归属检查。

行列信息要区分 Position 和 PositionFor

如果目标是报错信息，通常需要 filename:line:column，此时可以使用 fset.Position(pos)。它等价于带调整的 PositionFor(pos, true)。源码中存在 //line 指令时，调整后的文件名、行号和列号可能与物理源码位置不同。

代码分析器若需要保留真实源码坐标，应明确写成 PositionFor(pos, false)，忽略这类位置替换。无论选择哪种方式，行列展示和字节切片是两个结果：前者服务于人读的诊断，后者服务于源内容访问。

Unicode、NoPos 和跨文件是最容易漏掉的边界

第一，Offset 返回的是字节偏移，不是 Unicode 字符数。若要取得第几个 rune，应先用字节偏移切出字符串，再配合 utf8.DecodeRune 或 utf8.RuneCount 处理，不能把它直接当成 Go 字符串的“字符下标”。第二，任何可能来自缺失节点、解析错误或可选字段的位置都要先判断 IsValid。

第三，不要缓存一个文件的 int(pos) 并在另一个 FileSet 中复用。更稳妥的做法是保存文件名、文件内 offset 或节点本身；需要重新绑定到新的 FileSet 时，再通过对应的 file.Pos(offset) 生成位置。

// byteSpan 返回源内容中的字节范围；调用方仍需检查范围是否来自同一文件。
func byteSpan(file *token.File, start, end token.Pos, src []byte) []byte {
    // Pos 必须属于 file，否则 Offset 只能给出边界化结果。
    if !start.IsValid() || !end.IsValid() {
        return nil
    }
    begin, finish := file.Offset(start), file.Offset(end)
    if begin > finish || finish > len(src) {
        return nil
    }
    return src[begin:finish]
}

常见问题

为什么单文件示例里 int(pos) 有时看起来能用？

因为示例恰好只有一个文件，且位置值与偏移的差异没有触发明显错误。代码一旦加入第二个文件、换了 FileSet 或遇到 NoPos，这个假设就会失效。

File.Offset 返回的是字符位置还是字节位置？

它返回文件内容的字节偏移。需要按字符或 rune 处理时，要在这个偏移基础上再做 UTF-8 解码。

什么时候应该用 PositionFor(pos, false)？

当工具需要记录物理源码位置，不希望 //line 指令改变文件名、行号和列号时，使用未调整的结果。

token.NoPos 能不能当作文件开头？

不能。它表示没有有效位置；文件开头应使用对应 token.File 的 Pos(0)。