Go token.File 的列号为什么不是中文字符数量

如果你用 go/token 做 AST 分析，看到中文源码后很容易产生一个疑问：为什么 token.File 返回的列号和肉眼数出来的中文字符数量对不上？原因很明确：Position.Column 不是“第几个 Unicode 字符”，而是当前行内从 1 开始计算的 UTF-8 字节列号。

官方资料：https://pkg.go.dev/go/token#File

这一区别不会影响 Go 自己的语法位置判断，但会影响诊断器、源码索引、IDE 插件把位置展示给用户的方式。下面先给最小配方，再处理中文显示和 //line 的边界。

Column、Offset 和 Pos 其实是同一条字节坐标链

token.File 的核心坐标是文件字节偏移。FileSet.AddFile 为文件登记大小和基准位置，File.Pos(offset) 把文件内字节偏移变成紧凑的 token.Pos，再由 File.Offset(pos) 还原偏移，最后通过 Position(pos) 得到文件名、行号和列号。

行号来自行首偏移表。源码中列号的计算可以概括为“当前位置偏移减去本行起点，再加一”。因此同一行前面多了一个三字节的中文字符，后续位置的 Column 就会比按单字节字符估算多出两个。

用中文标识符看出字节列与字符数的差异

Go 源码使用 UTF-8。中文字符通常占用三个字节，所以一个中文标识符从起点到终点的 Pos 区间会比它的 rune 数量更宽。下面的示例只展示如何从 AST 取出起点和终点；代码块中的输出是位置关系示意，不应把它当成某个编辑器的实际截图。

package main

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

func main() {
	// 中文标识符用于展示：每个汉字在 UTF-8 中通常占用 3 个字节。
	const src = "package main\n\nvar 名称 = 1\n"
	fset := token.NewFileSet()
	file, err := parser.ParseFile(fset, "demo.go", src, 0)
	if err != nil {
		// 解析失败时不要继续读取不完整的 AST 位置。
		panic(err)
	}

	ast.Inspect(file, func(n ast.Node) bool {
		ident, ok := n.(*ast.Ident)
		if !ok || ident.Name != "名称" {
			return true
		}

		// Pos/End 是源码字节坐标；Position.Column 也是字节列。
		start := fset.Position(ident.Pos())
		end := fset.Position(ident.End())
		fmt.Printf("start=%d:%d end=%d:%d\n", start.Line, start.Column, end.Line, end.Column)
		return false
	})
}

如果把 Column 直接当作字符下标，中文标识符之后的诊断位置就可能向右偏移。尤其是给编辑器画光标、给用户返回选区，不能只保存 Position.Column，还要明确这一列采用的是字节、rune 还是屏幕显示宽度。

需要字符列时，另做一层显示坐标

官方坐标不应该被改写成“字符列”。更稳妥的做法是保留 token.Position 作为源代码事实，再从原始行首切片到目标字节偏移，用 UTF-8 解码计算面向用户的字符列。

package position

import "unicode/utf8"

// RuneColumn 把行内字节偏移转换成从 1 开始的 rune 列。
func RuneColumn(line []byte, byteOffset int) int {
	// 先限制边界，避免诊断位置超出当前行造成切片错误。
	if byteOffset  len(line) {
		byteOffset = len(line)
	}

	// 只在完整 UTF-8 前缀上计数；无效字节会按 RuneError 解码。
	return utf8.RuneCount(line[:byteOffset]) + 1
}

这里的结果适合“第几个 Unicode 码点”这种显示需求，但它仍不等于终端或编辑器的视觉宽度：全角字符、组合字符和制表符可能有不同的渲染宽度。如果产品要求光标和屏幕像素对齐，还需要采用目标界面的宽度规则。

遇到 //line 时，先决定要哪一种位置

File.Position(p) 等价于 PositionFor(p, true)，可能应用位置替换型 //line 注释。若工具需要报告源文件的原始物理位置，应使用 PositionFor(p, false)；若工具要遵循编译器对外呈现的替代文件名、行号和列号，则使用默认调整后的结果。

// 选择位置语义，而不是把所有位置都当成同一种坐标。
func reportPosition(f *token.File, p token.Pos, adjusted bool) token.Position {
	// adjusted=true 遵循 //line；false 保留原始文件坐标。
	return f.PositionFor(p, adjusted)
}

无论是否调整，Column 的基础语义仍然是字节计数。//line 改变的是文件名、行号以及替代位置基准，不会把字节列自动变成中文字符数量。

给源码工具的四条速查规则

记住一句话即可：token.File 负责稳定的源码字节坐标，字符列和屏幕列是上层展示模型。把这两层分开，中文源码、源码映射和编辑器光标就不会互相污染。

相关问题

为什么行号通常没有中文偏差？因为行号来自换行符所在的字节偏移表，中文只会影响同一行后续位置的列偏移。

能不能直接用 len(string) 计算字符列？不能把它当字符数；Go 的 len(string) 返回 UTF-8 字节数。需要 rune 数量时使用 UTF-8 解码计数，需要屏幕宽度时再采用界面规则。