Go token.File.Pos 怎样从字节偏移取得源码位置

在源码分析工具里，常见输入不是 token.Pos，而是某个文件内容中的字节偏移。例如扫描器知道第 18 个字节出现了问题，但日志需要输出“main.go:2:7”。这时应先调用 token.File.Pos(offset) 得到文件范围内的 token.Pos，再交给 token.FileSet.Position 转成文件名、行号和列号。

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

关键点是：offset 是相对于当前文件起点的字节偏移，Pos 是放进 FileSet 后使用的全局位置值，两者不能直接混用。负数会落到文件起点，超过文件大小的值会落到文件终点。

offset、Pos 和 FileSet 是怎样衔接的

token.File 在文件集合里保存一段位置范围。它有自己的 Base、Size 和 End：前者是注册文件时的起始位置，Size 是文件大小，End 是末尾位置。offset 不包含这个全局基址，只表示从该文件第一个字节开始数了多少字节。

最小转换链路可以写成下面这样。示例中的注释解释了文件内坐标和全局位置的分工。

package main

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

func main() {
    const source = "package demo\n\nfunc main() {}\n"

    fset := token.NewFileSet()
    file, err := parser.ParseFile(fset, "main.go", source, 0)
    if err != nil {
        // 解析失败时先停止，避免使用不完整的语法树位置。
        fmt.Println(err)
        return
    }

    // 这里的 18 是相对于 main.go 第一个字节的文件内偏移。
    offset := 18
    pos := fset.File(file.Pos()).Pos(offset)

    // FileSet.Position 把 token.Pos 展开为文件名、行号和列号。
    location := fset.Position(pos)
    fmt.Println(location.String())
}

实际使用时也可以先保存 *token.File，不要每次通过语法树节点重新查找。只要这个偏移属于该文件，file.Pos(offset) 就是明确的反向映射。

从 token.Pos 继续得到行号和列号

File.Pos 只负责返回位置值，不负责生成可读文本。源码工具通常还需要一个 FileSet，因为同一个集合中可以登记多个文件，FileSet.Position 才能根据全局 Pos 找到对应文件。

// 将文件内偏移转换为可用于日志的 Position。
func positionAt(fset *token.FileSet, file *token.File, offset int) token.Position {
    // Pos 只接收当前 file 的相对字节偏移，不要传入 file.Base()+offset。
    pos := file.Pos(offset)

    // Position 会返回文件名、行号和列号，适合直接写入诊断信息。
    return fset.Position(pos)
}

这里最容易犯的错误是把 file.Base()+offset 再传给 Pos。Pos 内部已经会把文件偏移加到文件的起点上，重复加基址会让结果偏向文件末尾，甚至直接被钳制到 End。

越界 offset 会被怎样处理

File.Pos 不会为负数或超大偏移返回错误。它会把负数调整为文件起始位置，把超过文件大小的值调整为文件结束位置。这种设计适合诊断工具做容错，但如果偏移来自不可信输入，仍应在业务层保留原始值并单独记录越界。

func clampPosition(file *token.File, offset int) token.Pos {
    // 让 token.File 负责统一处理负数和超过文件大小的偏移。
    return file.Pos(offset)
}

func offsetRoundTrip(file *token.File, pos token.Pos) (int, token.Pos) {
    // Offset 会把文件外的位置收敛到 0 或 Size，适合做边界归一化。
    offset := file.Offset(pos)

    // 对归一化后的 offset 再调用 Pos，可以得到稳定的文件内位置。
    return offset, file.Pos(offset)
}

需要注意，文档里保证的是 file.Offset(file.Pos(offset)) == offset 对结果偏移成立；反方向的 file.Pos(file.Offset(pos)) == pos 只对文件范围内的有效位置成立。token.NoPos 和其他文件的 Pos 不应当当作当前文件的位置使用。

用 Offset 做双向映射时的边界

如果工具同时维护字节偏移和 token.Pos，可以把转换集中在一处：入口只接收文件内 offset，输出统一的 token.Position；需要回写源码片段时，再用 Offset 取得相对偏移。这样能避免把全局位置值误当数组下标。

如果源码包含多字节 UTF-8 字符，offset 仍然按字节计算，列号则由 go/token 的位置逻辑产生。不要用字符串的 rune 下标替代文件字节偏移。

常见问题

为什么不能直接把 offset 转成 token.Pos？

因为 token.Pos 还要落在对应 token.File 的全局范围内，直接转换会丢失文件的基址和文件归属。

File.Pos 是否会检查 offset 是否有效？

它会对越界值做边界调整，但不会返回错误。是否把越界当作异常，需要由调用方根据扫描器或业务协议决定。

什么时候应该使用 File.Position？

当手里已有 token.Pos，并希望得到当前文件的文件名、行号和列号时使用 File.Position；如果需要让 FileSet 在多个文件中查找归属，则使用 FileSet.Position。

总结一下：文件内字节偏移先交给 token.File.Pos，全局位置再交给 FileSet.Position；输入输出都要明确是相对坐标还是全局位置。把这条转换链路固定下来，源码分析、错误定位和编辑器跳转都会更稳定。