Go token.File.SetLines 为什么会拒绝一组行偏移

token.File.SetLines 返回 false，不是因为它要求传入“每一行的长度”，而是因为它接收的是每一行起始位置的字节偏移。这组数字必须同时满足两个条件：从前到后严格递增，并且每个数字都小于文件大小。只要出现重复、倒序或等于文件大小的偏移，整次设置就会被拒绝。

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

例如，文件内容是 ab\nc\n，文件大小为 5，行起始偏移是 [0, 3]。偏移 0 指向第一行的第一个字节，偏移 3 指向第二行的第一个字节；最后一个换行符之后如果没有新的字符，就不会凭空增加一个起始偏移。

先把 SetLines 的返回值看成契约

我在给源码分析工具补位置表时，最容易误解的是把 SetLines 当作“把我提供的行号存起来”。实际上，它的参数名虽然叫 lines，每项表达的却是某一行第一个字符在文件中的偏移。Go 官方实现的判断可以概括成下面两句：

• 当前偏移必须大于前一项，不能相等，也不能回退。
• 当前偏移必须严格小于 token.File 的文件大小。

因此，文件大小为 10 时，[0, 3, 5] 可以接受；[0, 3, 10] 会失败，因为 10 已经是文件末端；[0, 5, 3] 也会失败，因为 3 不大于前一项 5。函数返回的是布尔值，调用方应把 false 当成输入数据没有建立成功，而不是继续使用这张表。

从换行边界构造行偏移

如果行表来自内存中的源码，最稳妥的思路是扫描字节内容：第一行从偏移 0 开始；每遇到一个换行字节，就把下一个字节的偏移作为下一行起点，但只有这个偏移仍然小于内容长度时才加入。下面的示例展示自定义文件对象的构造方式，注释只解释关键边界。

package main

import (
    "fmt"
    "go/token"
)

func main() {
    content := []byte("ab\nc\n")
    fset := token.NewFileSet()
    file := fset.AddFile("memory.go", -1, len(content))

    // 每一项是行首字节偏移，不是行号，也不是行长度。
    lines := []int{0, 3}
    if ok := file.SetLines(lines); !ok {
        fmt.Println("行偏移表无效")
        return
    }

    // Pos 使用 File 的基址加偏移，Offset 再还原为文件内字节位置。
    pos := file.Pos(3)
    fmt.Println(file.Lines(), file.Offset(pos))
}

这里的 3 是第二行的起点：字符串的字节位置依次是 a=0、b=1、换行符为 2、c=3。如果源码包含非 ASCII 字符，偏移仍按字节计算，不要把 Unicode 字符数直接当成偏移。

定位最常见的拒绝原因

遇到 SetLines 返回 false 时，可以先按数据形状排查，而不必立即怀疑 FileSet 的基址：

最后一种边界特别容易被忽略：对空文件来说，文件大小就是 0，而 SetLines 要求每一项严格小于文件大小，所以 []int{0} 反而无效。空文件应传入空切片，或者直接让文件对象保持它的空行表状态。

按用途选择 SetLines 或 SetLinesForContent

如果行偏移来自完整的源内容，SetLinesForContent 更不容易漏掉边界。它会根据内容计算行首，并忽略会改变显示位置的 //line 注释。只有在行表来自外部格式、虚拟文件或经过特殊变换时，才更适合调用 SetLines 手工提供偏移。

// 从完整内容建立行表，避免手工计算重复或越界的偏移。
file.SetLinesForContent([]byte("package demo\n\nvar n = 1\n"))

// 手工行表用于虚拟内容时，先保证偏移已排序且仍在文件范围内。
lines := []int{0, 13, 14}
if !file.SetLines(lines) {
    // 失败后不要继续把这张表交给 LineStart 或 Position 使用。
    return
}

两种方法都不会改变源码字节，也不会自动替调用方修正错误数据。若要在构造前做自己的检查，可以复用同一契约：遍历切片，比较当前项与上一项，并比较当前项与文件大小。检查通过后再调用 API，失败时保留原始数据，便于定位是扫描、拼接还是长度计算出了问题。

小结

SetLines 拒绝一组行偏移，核心原因只有一个：这组数据不符合 token.File 的行表契约。行首偏移按字节计算，必须严格递增，并且全部小于文件大小；空文件使用空表。完整源码优先使用 SetLinesForContent，虚拟或变换后的内容才手工构造 SetLines 参数。

常见问题：行偏移能不能传行号？不能，参数表示源文件字节偏移。最后一行没有换行符怎么办？只要它有首字符，就记录它的起始偏移。调用失败后能否继续查位置？不建议，应先修复或替换无效行表。非 ASCII 文本要按字符数计算吗？不要，token.File 的偏移是字节单位。