Go token.FileSet.AddFile 的 base 重叠时为什么会得到错误位置

在源码分析、代码生成或多文件诊断工具里，token.FileSet.AddFile 的 base 不是“第几个文件”，而是这个文件在整个 FileSet 中的绝对起始位置。多个文件如果复用了旧的 base，或者把文件内 offset 直接当成全局 token.Pos，就会看到位置落到错误文件、行列错位，甚至直接触发 panic。

正确做法是：把每个文件看成闭区间 [base, base+size]，新增文件优先使用 fset.Base()，再用 file.Pos(offset) 把文件内偏移转换成全局位置。

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

先把 base、size 和 EOF 对齐

AddFile(filename, base, size) 注册的是一个位置区间。文件内偏移 offs 会映射为 base + offs，其中偏移范围包含 0 到 size，所以 EOF 也占一个位置。比如 base=1、size=10 时，文件区间是 [1, 11]，下一个可用 base 是 12，而不是 11。

这也是很多“位置重叠”误判的来源：工程代码只按正文字节数相加，却忘了 AddFile 更新下一个 base 时还会额外加一。反过来，如果手工给出小于当前 FileSet.Base() 的 base，当前 Go 实现会拒绝这个注册，而不是默默帮你修正。

为什么复用 base 会让位置看起来错了

先看一个容易出错的注册方式：

package main

import "go/token"

func badFileSet() {
	set := token.NewFileSet()
	first := set.AddFile("first.go", -1, 20)
	// 错误示例：第二个文件复用了第一个文件的起点，区间会重叠。
	second := set.AddFile("second.go", first.Base(), 8)
	_, _ = first, second
}

这里的问题不是文件名，而是 first.Base() 表示第一个文件的全局起点；它没有包含第一个文件的结束位置。按照当前标准库的约束，第二次调用的 base 小于 set.Base() 时会 panic。若代码绕过了这个约束，或者从别的结构中拼出了重复区间，后续用 FileSet.File(pos) 查找时就无法得到可靠的文件归属。

另一个常见错误是把解析器返回的 token.Pos 当作文件内字节偏移。Pos 已经带有 FileSet 的全局 base，再次加 base 会把位置推到另一个区间。文件内偏移应使用 file.Pos(offset) 创建位置；已有位置则直接交给 fset.Position 或 fset.File。

多文件注册应当怎样分配 base

最稳妥的分配方式是让 FileSet 自己提供下一个最小 base。传入负数也会触发“使用当前 base”的特殊规则，但显式调用 set.Base() 更容易读懂，也方便日志排查：

package main

import (
	"fmt"
	"go/token"
)

func addFiles() {
	set := token.NewFileSet()

	// 让 FileSet 选择第一个可用区间起点，避免手工猜测全局位置。
	first := set.AddFile("first.go", set.Base(), 20)
	// FileSet.Base() 已经越过 first 的 EOF，第二个区间不会与它重叠。
	second := set.AddFile("second.go", set.Base(), 8)

	// 文件内 offset 必须通过对应 File 转成全局 Pos。
	pos := second.Pos(3)
	where := set.Position(pos)
	fmt.Printf("%s:%d:%d\\n", where.Filename, where.Line, where.Column)
	_ = first
}

如果文件内容后来变长，不能把已注册文件的 size 当作可随时修改的容量。应在知道真实大小后注册，或重新建立一套 FileSet；否则原先分配给后续文件的区间仍然依据旧的结束位置，位置映射自然会错位。

排查错误位置时按这四项核对

遇到诊断位置落错文件或行列异常，可以先打印每个文件的三个稳定量：Name()、Base()、Size()。然后确认所有文件按 base 递增，并检查相邻区间是否满足“后一个 base 大于前一个文件的结束位置”。

• 如果第二次 AddFile 直接 panic，优先看传入 base 是否小于 FileSet.Base()。
• 如果 FileSet.File(pos) 返回 nil，检查这个 pos 是否来自另一个 FileSet，或是否被重复加了一次 base。
• 如果文件名正确但列号偏移，检查传入的 offset 是否是字节偏移，并确认对应文件的 size 不是估算值。
• 如果使用 AddExistingFiles 组合外部 File，调用方必须自己保证区间不重叠；这和连续调用 AddFile 的分配策略不同。

常见问题

base 可以从 0 开始吗？

可以，只要它不小于当前 FileSet.Base()。实际项目通常直接使用 set.Base()，不依赖初始值。

size 是字符数还是字节数？

它对应位置偏移，因此应按源码的字节长度规划，而不是按中文字符数或 rune 数估算。

为什么相邻文件要多留一个位置？

因为每个区间包含 EOF，标准库把下一个最小 base 设为 base + size + 1，这样 EOF 不会落入下一个文件的区间。

记住一句话：base 管全局起点，size 管当前文件区间，文件内偏移交给 File.Pos 转换；多文件场景让 FileSet.Base() 负责递进，位置错位问题通常就能在注册阶段解决。