Go token.File.SetLines 返回 false 时怎样定位行偏移错误

在 Go 的源码分析、格式化或诊断工具里，token.File.SetLines 返回 false，通常不是方法本身不稳定，而是传入的行首偏移表不满足约束。先记住一个判断：它接收的是文件内容里的字节偏移，偏移必须按行首顺序严格递增，并且每个值都要落在文件长度范围内。

官方地址：https://pkg.go.dev/go/token#File.SetLines

排查时先看三个量：行偏移是否递增、最后一个偏移是否小于文件长度、空文件是否被单独处理。把这三项分开，通常就能很快定位失败原因。

SetLines 接收的到底是什么

token.File 维护的是一个文件名、大小和行偏移表。这里的“偏移”是源文件字节序列中的位置，不是 FileSet 给多个文件分配的全局 token.Pos。例如文本为 ab\nc\n 时，两行的起始字节位置是 0 和 3。

建立文件并设置行表时，可以把文件长度与行首偏移放在同一个数据模型里理解：

package main

import "go/token"

func buildFile() (*token.File, bool) {
	// size 是源文件的字节长度，base 只负责给 FileSet 分配位置区间。
	const size = 5
	set := token.NewFileSet()
	file := set.AddFile("sample.go", -1, size)

	// 每个元素表示一行第一个字节的偏移，必须从小到大排列。
	lines := []int{0, 3}
	ok := file.SetLines(lines)
	return file, ok
}

这里的 -1 表示让 FileSet 自动选择 base；它和 SetLines 的输入不是一回事。不要把 base、token.Pos 与文件内偏移混成同一个坐标系。

按约束构造合法的行首表

官方文档给出的关键限制可以转换成三个可操作的判断：

• 偏移从第一行的起点开始，通常第一个值是 0；
• 后一个偏移必须大于前一个偏移，重复值和倒序都会使设置失败；
• 每个偏移必须小于文件大小，不能把文件末尾或越界位置当成新行起点。

因此，下面几种输入都应该被视为坏数据：

// 这些示例只展示约束，不执行本地文件读取。
invalidA := []int{0, 0, 3} // 相邻行首重复，无法形成递增表。
invalidB := []int{0, 4, 3} // 后一个偏移回退，行顺序已经不成立。
invalidC := []int{0, 3, 5} // 5 等于文件长度，超出最后一个有效字符位置。

_ = invalidA
_ = invalidB
_ = invalidC

多字节 UTF-8 字符也要注意：这里按字节偏移计数，而不是按“看起来有几个字符”计数。若行表来自字符串扫描，必须和实际编码后的字节切片使用同一套偏移口径。

返回 false 时怎样定位哪一个偏移有问题

SetLines 只返回布尔值，不会告诉你第几个元素出错，所以定位逻辑应放在调用前。先检查空表与文件长度，再检查相邻元素：

func validLineOffsets(lines []int, size int) bool {
	// 空文件没有可用行首；非空文件的第一行从字节 0 开始。
	if size == 0 {
		return len(lines) == 0
	}
	if len(lines) == 0 || lines[0] != 0 {
		return false
	}
	for i := 1; i = size {
			return false
		}
	}
	return true
}

这个前置判断不是替代 SetLines，而是把一个没有细节的 false 拆成可记录的原因。工程上可以在返回 false 时记录索引、前后两个偏移和文件大小，避免把问题归咎于后续的 AST 或位置查询。

行表设置成功后怎样查询位置

行表建立后，File.Pos 和 File.Offset 负责在文件内偏移与 token.Pos 之间转换，File.Line 可以得到行号，File.PositionFor 则把位置组织成包含文件名、行号和列号的 token.Position。adjusted 只影响是否考虑位置调整信息，不会改变 SetLines 对原始行表的约束。

func describe(file *token.File, offset int) token.Position {
	// 先把文件内字节偏移转换成属于该 File 的 token.Pos。
	pos := file.Pos(offset)
	line := file.Line(pos)
	byteOffset := file.Offset(pos)
	_ = line
	_ = byteOffset

	// true 表示允许 PositionFor 使用已登记的位置调整信息。
	return file.PositionFor(pos, true)
}

这条链路的重点是坐标转换顺序：先确认行表合法，再从文件内偏移取得 Pos，最后查询行列。若一开始就把错误的行表交给 SetLines，后面的查询函数即使调用方式正确，也没有可靠的行列基础。

常见问题

SetLines 的偏移按字符还是按字节计算？

按文件内容的字节偏移计算。包含多字节 UTF-8 字符时，不要用字符数量代替字节位置。

最后一行没有换行符，行表还要加一个文件长度吗？

不需要。行表记录的是每一行的起点，最后一个起点必须小于文件长度；文件长度本身不是新的有效行首。

SetLines 返回 false 后应该改用 PositionFor 吗？

不应该。PositionFor 负责查询位置，不能修复非法行偏移表；先修正输入，再进行位置查询。

归纳起来，SetLines 的排查顺序就是“统一字节口径、确认第一个偏移、检查严格递增、排除文件长度边界”。把这些约束显式写进生成行表的代码里，源码位置映射就更容易维护。