Go go-runewidth 怎样补齐包含宽字符的表格列

终端表格出现“中文列向右跑、英文列看起来又正常”的错位时，问题通常不在制表符，而在把字符串长度当成了屏幕宽度。Go 的 len 统计 UTF-8 字节，utf8.RuneCountInString 统计 rune，都不能直接代表终端占用的显示单元格。解决办法是用 go-runewidth.StringWidth 计算显示宽度，再用 FillRight 或 FillLeft 补齐。

官方地址：https://pkg.go.dev/github.com/mattn/go-runewidth

先按显示单元格确定每列的目标宽度，再补空格；字段是中文、英文或包含符号，都不要手工用 len(s) 决定补几个空格。

先把字符串长度换成终端显示宽度

我排查这类错位时，第一步会把同一字段的三种长度放在一起看。中文通常一个字符占两个显示单元格，而 ASCII 字母通常占一个；emoji、组合字符和东亚宽度模糊字符还会增加边界情况。go-runewidth 的 RuneWidth 与 StringWidth 就是为这种“终端格子宽度”准备的。

package main

import (
    "fmt"
    "unicode/utf8"

    "github.com/mattn/go-runewidth"
)

func main() {
    samples := []string{"Go", "服务", "状态✓"}
    for _, text := range samples {
        // len 是 UTF-8 字节数，RuneCount 是 rune 数；表格应使用显示单元格数。
        fmt.Printf("%-8q bytes=%d runes=%d cells=%d valid=%t\n",
            text, len(text), utf8.RuneCountInString(text),
            runewidth.StringWidth(text), utf8.ValidString(text))
    }
}

这段代码的重点不是输出格式，而是比较三个概念：字节数只适合描述存储，rune 数适合描述 Unicode 码点数量，StringWidth 才适合决定终端列边界。库的 README 也提醒，部分 Latin 模糊宽度字符在 CJK 环境下仍按窄字符处理，所以不要把“所有非 ASCII 都算 2”写成自己的规则。

用 FillRight 和 FillLeft 统一补齐

确定目标列宽后，不必自己写 strings.Repeat(" ", width-len(text))。FillRight 会在右侧补空格，适合名称、状态等左对齐字段；FillLeft 会在左侧补空格，适合数量、耗时等右对齐字段。两个函数的宽度参数表示目标显示宽度。

package main

import (
    "fmt"

    "github.com/mattn/go-runewidth"
)

func main() {
    const nameWidth = 12
    const countWidth = 6

    rows := []struct {
        name  string
        count int
    }{
        {name: "服务", count: 7},
        {name: "worker-api", count: 128},
    }

    // 名称右侧补齐，数字左侧补齐，二者都以显示单元格为准。
    fmt.Println(runewidth.FillRight("服务", nameWidth) + " | " + runewidth.FillLeft("数量", countWidth))
    fmt.Println("-------------+-------")
    for _, row := range rows {
        // Sprintf 只负责拼接；列宽由 go-runewidth 先处理好。
        name := runewidth.FillRight(row.name, nameWidth)
        count := runewidth.FillLeft(fmt.Sprint(row.count), countWidth)
        fmt.Println(name + " | " + count)
    }
}

如果字段本身已经超过目标宽度，补齐函数不会替你截断。生产日志里更稳妥的顺序是“先限制内容，再补齐”，否则某一行仍可能把后面的分隔符推走。

把列宽、截断和环境策略放在一个小函数里

表格来自用户输入时，建议把宽度规则集中起来。Truncate 的第二个参数也是显示单元格宽度，尾部可以放省略号；空字符串则会被正常补到目标宽度。若程序需要明确模拟东亚宽度环境，可用 NewCondition 创建独立条件，而不是在全局运行途中反复修改默认值。

func tableCell(text string, width int) string {
    // 负宽度没有业务意义，先降为零，避免把错误配置继续传到布局层。
    if width 

用边界样例复查，别只测英文

最后用空字符串、一个汉字、英文混合串、带符号文本和 emoji 各测一行。重点看的是每个分隔符是否落在同一显示列，而不是 HTML 预览里字符串是否等长。go-runewidth 还提供 IsCombiningWidth、IsAmbiguousWidth 等判断函数；遇到特殊符号时，先确认自己的终端字体和区域设置，再决定是否启用特定 Condition。

常见问题

为什么 Go 的 len 不能直接用于表格补空格？

因为 len 返回 UTF-8 字节数。中文、emoji 等字符的字节数与终端占用的显示单元格不是同一件事。

FillLeft 和 FillRight 的 width 是字节数吗？

不是。它表示目标显示宽度，函数会根据 runewidth 的宽度规则计算还需要补多少空格。

字段超过列宽时应该用哪个函数？

先用 Truncate 按显示单元格截断，再调用补齐函数；不要把超长内容直接交给拼接逻辑。

把“字符长度”和“显示宽度”分开后，Go 终端表格的修复路径就很固定：StringWidth 负责测量，Truncate 负责限制，FillRight/FillLeft 负责对齐，最后用混合字符边界样例复查。