Go unicode/utf8 出错时怎么排查非法序列

Go 里看到乱码或连续出现 �，先别急着替换字符。真正要确认的是：输入字节是不是合法 UTF-8。unicode/utf8 已经提供了完整性判断和逐个解码能力；排查时保留原始 []byte，用 utf8.Valid 或 utf8.ValidString 先做总判断，再用 DecodeRuneInString 结合返回的宽度定位坏字节。

先确认：字符串是否真的不是合法 UTF-8

Go 的 string 可以保存任意字节，并不自动保证内容合法。把外部数据转成字符串后，len(s) 得到的仍是字节数；只有在需要按字符处理时，才进入 UTF-8 解码语义。

整段输入先做一次判断，能把“显示效果异常”和“编码序列非法”分开：

package main

import (
    "fmt"
    "unicode/utf8"
)

func checkText(raw []byte) {
    // 保留原始字节，避免先转字符串后丢失排查线索。
    fmt.Printf("valid bytes: %v\n", utf8.Valid(raw))
    text := string(raw)
    // ValidString 只判断 UTF-8 合法性，不判断业务文本是否可读。
    fmt.Printf("valid string: %v, bytes: %d\n", utf8.ValidString(text), len(text))
}

utf8.Valid 与 utf8.ValidString 都只回答“是否全部为合法 UTF-8”。返回 false 后，再继续定位；返回 true 也不代表文本一定符合业务字符集，例如控制字符、不可见字符仍需要单独处理。

为什么看到 RuneError 还不能直接判定非法

utf8.RuneError 是 Unicode replacement character，既可能是输入中真实存在的合法 U+FFFD，也可能是解码器用来表示坏字节的结果。关键在第二个返回值：对非空且非法的编码，DecodeRuneInString 返回 RuneError 和宽度 1；合法的 U+FFFD 使用 UTF-8 编码时宽度为 3。

因此，下面这种判断不可靠：

if r == utf8.RuneError {
    // 这里只能说明解出的码点是替换字符，不能证明原始字节非法。
}

还要结合 size 判断。RuneCountInString 也不是校验器：官方文档明确说明，错误或短编码会按一个宽度为 1 的 rune 计数，所以它适合统计，不适合找坏数据。

用字节偏移定位非法序列

定位时不要按 rune 下标切片，因为问题发生在字节边界。每次从当前偏移解码，并按返回的 size 前进；当出现 RuneError, 1，记录当前位置和原始字节，就能把日志交给上游排查。

package main

import "unicode/utf8"

func invalidOffsets(s string) []int {
    var bad []int
    for offset := 0; offset 

拿到偏移后，建议同时打印固定长度的十六进制上下文，而不是把整条用户文本写进日志。重点看三类情况：多字节字符只收到前半段，来源其实是 GBK 等非 UTF-8 编码，以及中间层把二进制字段误当成文本。定位到坏字节不等于已经修复了来源。

生产环境的处理边界怎么定

对 API、消息队列和文件导入，最好在边界层完成校验，并把“原文不可接受”的错误和“允许替换”的策略写成明确契约。修复后重新用 utf8.Valid 检查；不要用 strings.ReplaceAll 把所有 � 删除，因为那会把真实字符和解码错误混在一起。

常见问题

Go 的 string 是不是一定是 UTF-8？

不是。string 是字节序列；源码中的字符串字面量通常是 UTF-8，但运行时接收的外部字节仍需显式校验。

为什么 range 也能遍历坏字符串？

range 会按 UTF-8 解码，遇到非法序列时产生 RuneError 并前进一个字节。它能继续遍历，不代表输入已经合法。

utf8.RuneStart 能不能直接找非法字节？

不能。它只能判断一个字节是否可能是 rune 的起始字节，不能完成完整的 UTF-8 合法性检查；完整判断应使用 Valid 或解码结果。

官方参考：https://pkg.go.dev/unicode/utf8。需要记住的排查顺序很短：保留原始字节、先做整体校验、再用 RuneError + size 定位，最后回到输入协议修复来源。