Go 字符串包含非法 UTF-8 时怎样定位来源

Go 的 string 本质上是只读字节序列，并不保证内容一定是 UTF-8。遇到日志出现乱码、JSON 下游拒收或数据库写入报编码错误时，先不要把问题归咎于显示终端：用 utf8.ValidString 确认整串，再用 DecodeRuneInString 找到第一个非法字节的偏移，最后沿着读取和拼接边界回溯来源。

这篇只处理“字符串里已经混入非法 UTF-8，怎样定位它从哪里进来”这一类问题。RuneError 本身不是充分证据，因为合法的 U+FFFD 也会解码成它。

排查顺序：确认编码状态 → 记录字节偏移 → 回溯输入边界 → 决定拒绝还是替换。

先确认：这是非法 UTF-8，还是合法的替换字符

Go 官方 unicode/utf8 包提供了直接判定方法。ValidString 返回 false 时，才能确定字符串至少包含一段不完整、过长或不符合 UTF-8 规则的编码。若只是打印出“�”，还不能直接下结论：原始数据可能本来就包含合法的 U+FFFD。

package main

import (
    "fmt"
    "unicode/utf8"
)

func main() {
    // 用字节转义构造一个可复现的非法片段，避免编辑器替换它。
    s := "订单-" + "\xE4\x28\xA1"

    // 先做整串判断，避免把显示问题误判成编码问题。
    fmt.Println("valid UTF-8:", utf8.ValidString(s))
    fmt.Printf("raw bytes: % x\n", []byte(s))
}

这里的十六进制输出比直接打印字符串更有用：它能证明问题发生在字节层，而不是字体或终端渲染层。诊断日志可以短暂保留原始字节，但不要把可能包含敏感信息的完整输入写入生产日志。

再定位：记录第一个非法字节的偏移

DecodeRuneInString 遇到非法编码时返回 (utf8.RuneError, 1)。因此判断条件要同时检查 rune 和宽度：合法的 U+FFFD 通常是一个 3 字节的 UTF-8 编码，不能被当成坏数据。

package main

import "unicode/utf8"

// firstInvalidByte 返回第一个非法编码的字节偏移和原始字节。
func firstInvalidByte(s string) (offset int, value byte, ok bool) {
    for offset 

拿到偏移后，记录它前后各几个字节即可。例如用 start := max(0, offset-4)、end := min(len(s), offset+5) 截取片段。这样能判断非法字节是单独出现，还是前一个多字节字符被截断。

沿输入边界回溯：非法字节通常在哪里进入

定位偏移只是“现象坐标”，来源通常在更早的边界。重点检查四类位置：读取二进制文件或网络响应后直接转成 string；把非 UTF-8 数据当文本反序列化；多个来源拼接时混入了原始字节；错误包装时只保留了最终字符串，丢掉了来源字段。

建议在每个边界只保留必要的上下文，例如来源名、字段名、字节长度和是否通过 Valid，不要在每层重复打印全文。把检查放在“字节转字符串”的地方，往往比在最后的 HTTP 或数据库调用处才检查更容易定位。

func textFromBytes(source string, raw []byte) (string, error) {
    // 在转换边界检查，而不是等下游报错后再猜来源。
    if !utf8.Valid(raw) {
        return "", fmt.Errorf("%s contains invalid UTF-8: %d bytes", source, len(raw))
    }
    // 通过检查后再建立文本语义，调用方可以保留 source 线索。
    return string(raw), nil
}

如果原始数据本来就是二进制，正确做法不是强行清洗，而是继续使用 []byte 或编码后的传输格式。只有业务契约明确要求文本时，才把非法输入作为错误返回。

修复策略：拒绝、替换，还是保留原始字节

三种策略不要混用。协议字段、用户昵称、JSON 文本等有明确 UTF-8 契约时，在入口拒绝并返回来源字段；日志或展示文本允许降级时，可以显式替换非法片段，但要记录发生过清洗；文件、压缩包或签名数据则保留 []byte，不要为了方便显示而转成字符串。

最后用下面这张清单复查：

• utf8.ValidString 是否在真正的输入边界执行过。
• 是否记录了第一个非法字节的偏移和有限范围的原始字节。
• 是否区分了非法序列与合法的 U+FFFD。
• 是否保留了来源字段，而不是只返回一条模糊的“乱码”错误。
• 二进制数据是否一直按 []byte 处理。

常见追问

为什么 range 没有报错？

字符串遍历会把非法编码按一个宽度为 1 的 RuneError 处理，它适合继续遍历，不等于已经完成来源诊断。需要定位时仍应检查 size == 1 并记录偏移。

把字符串转成 []rune 能修复吗？

不能恢复丢失的原始字节。转换可能把非法片段变成替换字符；它适合生成展示文本，不适合作为数据源追踪或无损修复。