Go token.File.SetLinesForContent 怎样为内存源码建立行表

做源码分析工具时，输入经常不是磁盘上的文件，而是一段已经在内存里的 []byte。这时只把文件名和长度交给 token.FileSet 还不够：如果没有行偏移表，后续位置只能停留在字节偏移层面，难以稳定地显示为“第几行、第几列”。

处理这件事的直接方法是：用同一份源码字节数创建 token.File，再调用 SetLinesForContent(content)。它会根据内容里的换行字节建立每一行首字符的偏移表；之后通过 File.Position 或 File.PositionFor 把 Pos 转成可读位置。

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

官方源码：https://go.dev/src/go/token/position.go

关键是“同一份字节内容、同一个文件大小、同一张行表”必须保持一致。SetLinesForContent 只负责根据 content 扫描换行，不会替你修正错误的文件大小，也不会把 //line 注释转换成位置重映射。

先把内存源码和 File 绑定到同一份字节数据

token.File 是 FileSet 中一个文件的句柄，内部至少要有文件名、起始位置范围和文件大小。内存源码没有天然的磁盘路径，所以通常给它一个诊断用文件名，例如 memory.go，但大小必须使用实际字节长度。

这里的长度是 len(content)，不是字符数，也不是把 UTF-8 文本先转成 rune 后得到的数量。token.Pos 与 File.Offset 的关系建立在字节偏移上；这一点决定了注册文件和后续查询必须围绕同一份 []byte。

调用 SetLinesForContent 建立行偏移表

SetLinesForContent 的职责很窄：它扫描传入内容，把第一行的起点和每个换行符之后的下一个字节偏移记录下来，然后把这些偏移保存为 File 的行表。它不解析 Go 语法，也不需要 AST。

下面的示例把一段内存源码注册成 token.File，再建立行表。代码只展示调用关系；如果接入真实工具，应继续让解析器和位置查询使用这同一份 source。

package main

import (
	"fmt"
	"go/token"
)

func main() {
	// 内存源码就是位置系统的唯一字节来源，后续不要另造一份文本。
	source := []byte("package demo\n\nfunc Run() {}\n")

	fset := token.NewFileSet()
	// 负 base 表示使用 FileSet 当前可用的起始位置；文件大小必须匹配 source。
	file := fset.AddFile("memory.go", -1, len(source))
	// 按换行字节建立行首偏移表，不解析语法，也不执行源码。
	file.SetLinesForContent(source)

	fmt.Printf("行数=%d，行表=%v\n", file.LineCount(), file.Lines())
	for _, offset := range []int{0, 12, 14} {
		// Pos 先绑定到这个 File，再转换成文件名、行号和列号。
		position := file.Position(file.Pos(offset))
		fmt.Printf("offset=%d -> %s:%d:%d\n",
			offset, position.Filename, position.Line, position.Column)
	}
}

这段代码中，LineCount 反映行表条目数，Lines 返回行首偏移表，Pos 把文件内偏移映射到当前文件区间，最后由 Position 负责展示层的位置结构。它们解决的是同一件事的不同层次，不应该把行号直接当成 Pos。

用 Position 和 Lines 读取结果

行表记录的是每行首字符的字节偏移，而不是“这一行有多少字符”。例如内容中第一个换行字节后紧跟的偏移就是下一行的起点；如果连续出现两个换行，第二个空行也会有自己的起点。

如果需要定位 AST 节点，通常使用节点的 Pos() 和 End()，再交给 FileSet.Position 或 File.Position。如果只是给内存缓冲区中的某个字节偏移生成诊断信息，则可以使用 file.Pos(offset) 再查询位置。这样做比手算行号更不容易在连续换行、空文件和多字节字符上出错。

需要留意列号的含义：Go 的 token.Position.Column 按字节计数。源码含有中文或其他多字节 UTF-8 字符时，列值不是用户界面意义上的“第几个可见字符”。如果编辑器需要屏幕列或 grapheme 列，应在展示层另行换算，不能修改 token 的基础偏移语义。

处理空内容、换行和 UTF-8 边界

空内容不会凭空产生一行

官方文档对 SetLines 的说明是：空文件使用空的行偏移表。不要看到“空文件在编辑器里常显示第一行”就自行把 0 塞进 SetLines；token 层记录的是它定义的行表，而不是某个编辑器的光标体验。

尾部换行不等于新增一条内容行

SetLinesForContent 只在扫描到换行后，等下一次遍历到内容字节时才把新的行首偏移加入表中。因此内容以换行符结束时，不要把换行后的空位置自动当成一条已有内容行。做诊断展示时，是否显示尾部空行应由展示层决定。

CRLF 的列和偏移仍按字节保存

Windows 风格换行包含 \r\n，真正触发行表变化的是 \n。\r 仍然占一个字节，位于上一行的末尾。若工具要高亮源码片段，切片边界应使用原始字节偏移，避免先做换行风格转换后再拿旧偏移查询。

在自动行表与 SetLines 之间做选择

如果行边界就是内存源码中实际的 \n，优先使用 SetLinesForContent，因为它不会让调用方重复实现扫描逻辑。若行边界来自预处理器、拼接文件、外部映射或已经计算好的偏移数组，则可以考虑 SetLines。

SetLines 接收的是每行首字符的偏移数组，并检查偏移必须递增且小于文件大小；调用方在方法返回后也不能继续修改传入切片。相比之下，SetLinesForContent 直接依据给定内容建立表，它不会理解位置改变型 //line 注释。

把行表放进源码工具的生命周期

我在设计这类工具时，最容易忽略的不是 API 名字，而是“源码副本”问题：读取内容时保存了一份切片，注册 File 时却拿另一份格式化后的文本计算长度，最后 AST、诊断消息和高亮范围各自引用不同的字节坐标。这样即使每个 API 单独调用正确，组合结果也会漂移。

更稳妥的工作流是先确定一个不可变的 []byte：用它计算文件大小、建立行表、交给解析器，并保存给需要输出片段的诊断层。若确实要改写源码，改写后应把新内容视为新的坐标空间，重新创建或重新配置对应的 File，不要把旧行表继续套在新内容上。

最后记住三个检查点：FileSet.AddFile 的 size 是否等于内容字节数，SetLinesForContent 的输入是否就是解析器使用的内容，位置查询是否区分字节偏移与用户界面字符列。三者一致时，内存源码也能拥有稳定的文件名、行号和列号。

常见问题

SetLinesForContent 会解析 Go 语法吗？

不会。它只扫描字节内容中的换行并设置行偏移表；语法解析应由 go/parser 等工具完成。

调用 SetLinesForContent 后还需要 SetLines 吗？

同一份真实源码通常不需要。只有当行边界来自外部映射或调用方已经拥有合法偏移数组时，才考虑使用 SetLines，不要无目的地覆盖自动建立的表。

为什么 //line 注释没有改变这个行表？

因为 SetLinesForContent 明确忽略位置改变型 //line 注释。需要遵循这类指令的源码位置，应使用解析器和 FileSet 提供的调整后位置，而不是把注释当成普通换行规则。

UTF-8 中文会让行号错误吗？

不会影响换行边界，但列与偏移按字节计数。只要切片和 File 大小都基于同一份 UTF-8 字节内容，行号和字节位置仍然可以稳定对应。