Go unicode/utf8 无效字节的替换策略

Go 的 string 可以保存任意字节，并不保证内容一定是 UTF-8。处理外部文本时，推荐先用 utf8.ValidString 判断：关键字段校验失败就拒绝；面向用户的展示文本可用 strings.ToValidUTF8 替换；只有业务明确允许丢失内容时才传空替换串删除无效片段。

官方文档：https://pkg.go.dev/unicode/utf8；字符串替换接口：https://pkg.go.dev/strings#ToValidUTF8。

先判断输入究竟是文本还是字节

无效 UTF-8 不等于“字符串损坏”。如果字段本来就是压缩包、图片、加密结果或协议帧，它应继续以 []byte 处理，不能为了通过文本校验而替换字节。只有接口契约明确要求 UTF-8 文本时，替换才有意义。

通常可以按用途分成四类：

最小可用写法是 ValidString 加 ToValidUTF8

utf8.ValidString 只负责判断，不修改内容。strings.ToValidUTF8 会把每一段连续的无效 UTF-8 字节替换成指定字符串，替换串可以为空。对于页面或日志预览，使用 Unicode 替换字符 U+FFFD 比静默删除更容易发现问题。

package textclean

import (
    "strings"
    "unicode/utf8"
)

func ForDisplay(s string) (clean string, changed bool) {
    // 有效文本直接返回，避免无意义的清洗分支。
    if utf8.ValidString(s) {
        return s, false
    }

    // 每段连续无效字节替换为一个可见的 Unicode 替换字符。
    return strings.ToValidUTF8(s, "\uFFFD"), true
}

如果业务允许删除无效片段，可把替换串改为 ""。但删除后用户无法从展示结果看出原始异常，适合搜索索引的辅助字段，不适合姓名、订单备注或法律留存文本。

关键字段应该拒绝，而不是悄悄修复

对用户名、唯一键、路径片段、签名原文等参与比较的内容，替换会把不同原始输入合并为相同结果。例如两段不同的无效字节都可能变成同一个 �。这类字段应返回可识别错误，让上游重新编码或重新提交。

package textclean

import (
    "errors"
    "unicode/utf8"
)

var ErrInvalidUTF8 = errors.New("输入不是有效 UTF-8 文本")

func RequireUTF8(s string) error {
    // 标识符不做替换，避免清洗后发生值碰撞。
    if !utf8.ValidString(s) {
        return ErrInvalidUTF8
    }
    return nil
}

接口层可把错误转换成明确的客户端提示，日志则记录字段名、来源和字节长度。不要直接把完整原文写入日志；它可能包含隐私，也可能破坏日志采集链路。

RuneError 不能单独证明编码无效

utf8.DecodeRuneInString 遇到无效编码时返回 utf8.RuneError，宽度为 1。但合法文本本身也可以包含真正的 U+FFFD，它的 UTF-8 编码宽度是 3。因此要同时判断“返回值是 RuneError”与“宽度等于 1”，不能只看 rune 值。

需要统计每个无效字节或输出自定义占位串时，可以显式扫描：

package textclean

import (
    "strings"
    "unicode/utf8"
)

func ReplaceEachInvalidByte(s, replacement string) (string, int) {
    var b strings.Builder
    invalidCount := 0

    for len(s) > 0 {
        r, size := utf8.DecodeRuneInString(s)
        if r == utf8.RuneError && size == 1 {
            // width=1 才表示当前字节不能组成有效 UTF-8 编码。
            b.WriteString(replacement)
            s = s[1:]
            invalidCount++
            continue
        }

        // 有效 rune 按原始字节写回，合法的 U+FFFD 也会保留。
        b.WriteString(s[:size])
        s = s[size:]
    }
    return b.String(), invalidCount
}

这段代码与 strings.ToValidUTF8 的语义不同：前者可以按每个无效字节替换，后者按每段连续无效序列替换一次。对用户界面通常后者更自然；对协议诊断或计数，前者更精确。

展示文本还要考虑可读性

� 能明确提示字符不可解码，但连续出现时会影响阅读。面向普通用户的备注可使用一个短占位词，例如“[无法识别]”；搜索摘要可以删除；管理员诊断页则应同时显示清洗文本和经过访问控制的十六进制摘要。

替换只保证输出是有效 UTF-8，不会把 GBK、Big5 等其他编码“猜”成中文。如果输入来源已知使用其他字符集，应先按明确编码转码；来源未知时不要凭内容猜测后覆盖原始数据。

大文本不要重复扫描

ValidString 与替换都需要读取输入。若无效文本很少，先校验再替换可以让正常路径保持简单；如果业务规定所有展示文本都必须生成副本，也可以直接调用 ToValidUTF8，避免在无效输入上先扫一遍再扫一遍。

流式读取时还要避免把多字节 rune 从缓冲区中间切开。不要把每个网络分片单独当作完整字符串验证；应使用能保留尾部不完整序列的解码器，或在完整消息边界上校验。

一份可直接采用的判断清单

• 字段是二进制数据：不做 UTF-8 替换。
• 字段参与身份、签名或唯一性比较：校验失败直接拒绝。
• 字段只用于展示：以 U+FFFD 或明确占位词替换。
• 字段允许信息损失：可以删除，但记录修改次数与来源。
• 字段需要审计：原始字节与清洗副本分开保存。
• 输入是已知其他编码：执行确定性转码，不把替换当转码。

相关问题

for range 遇到无效 UTF-8 会怎样？

遍历会产生 RuneError，无效编码对应的宽度为 1。若需要区分合法的 U+FFFD，使用 DecodeRuneInString 同时检查宽度。

ToValidUTF8 会把每个坏字节都替换一次吗？

不会。它按连续无效字节序列替换一次。需要逐字节占位或计数时，应显式解码并检查 RuneError 与 size == 1。

替换后能恢复原始文本吗？

不能。替换和删除都会丢失信息。需要恢复或重放时，必须在清洗前单独保存原始字节。