Go unicode/utf8.DecodeRuneInString 遇到非法字节怎么走：RuneError 与前进长度

处理用户昵称、导入文件或日志里的字符串时，最容易漏掉的不是“中文怎么显示”，而是非法 UTF-8 字节会怎样被消费。Go 的 utf8.DecodeRuneInString 把“空输入”和“编码损坏”拆成了两个不同的长度信号：前者返回 (RuneError, 0)，后者返回 (RuneError, 1)。只要循环按 size 前进，坏字节不会让程序卡住，后面的合法字符也还能继续检查。

判断是否继续扫描，不要只看返回的 rune 是否等于 utf8.RuneError；先看 size。非空输入的非法编码固定消费 1 个字节，空字符串才是 0。

同一个 RuneError，实际代表两种现场

RuneError 是 Unicode 替换字符。它既可能是输入里本来就存在的合法字符 U+FFFD，也可能是解码器发现非法字节后的返回值，所以不能仅凭 rune 值判断“这里一定坏了”。真正有区分度的是第二个返回值。

package main

import (
    "fmt"
    "unicode/utf8"
)

func main() {
    samples := []string{"", "A", string([]byte{0xff}) + "好", "�"}
    for _, s := range samples {
        r, size := utf8.DecodeRuneInString(s)
        fmt.Printf("%q: %U size=%d\n", s, r, size)
    }
}

空字符串没有第一个字节，所以长度是 0；0xff 不是合法 UTF-8 起始字节，解码器返回替换字符并只消费 1 个字节；而字符串字面量里的 � 本身是合法编码，通常会得到它自己的 3 字节长度。这个区别正是后续清洗逻辑的分水岭。

为什么非法序列只前进一个字节

UTF-8 一个字符最多占 4 个字节。解码器看到起始字节后，还要检查续字节范围、编码长度是否足够，以及结果是否落在合法 Unicode 范围内。任何一处不满足，返回的宽度都设为 1，而不是把整个疑似序列一次吞掉。

这样做有一个很实际的好处：错误恢复不会误删紧跟在坏字节之后的 ASCII 或合法多字节字符。下面的扫描函数把每个 rune、起始偏移、字节宽度和是否非法一起打印出来：

func scan(s string) {
    for offset := 0; len(s) > 0; {
        r, size := utf8.DecodeRuneInString(s)
        invalid := r == utf8.RuneError && size == 1
        fmt.Printf("offset=%d rune=%U size=%d invalid=%t\n", offset, r, size, invalid)
        offset += size
        s = s[size:]
    }
}

这里的 size == 1 只表示“这一段无法按合法 UTF-8 解码”，不表示所有单字节字符都有问题。ASCII 字符也会返回宽度 1，所以判断非法必须把 r == utf8.RuneError 一起带上。

整体校验和定位扫描该怎么分工

如果业务只接受干净文本，先用 utf8.ValidString(s) 做一次整体判断更直观：返回 false 就拒绝入库或进入后续解析。如果需要给用户指出第几个字节损坏，或者要把坏字节替换成安全占位符，再使用上面的逐段扫描。

不要用“遇到 RuneError 就停止”的写法。它会把合法的替换字符和真正的非法字节混在一起，也会让坏字节后面的内容完全不再检查。相反，扫描函数每轮都必须保证 size > 0；标准库对非空输入的非法编码已经保证返回 1，因此切片操作可以稳定结束。

几个容易写错的边界

• 把字节长度当字符数量。 size 是 UTF-8 字节宽度，不是 rune 序号；偏移量应按字节累加。
• 把合法 RuneError 判成脏数据。 只有 RuneError + size=1 组合才是解码失败信号。
• 忽略空输入。 RuneError + size=0 代表扫描结束，不能再次切片或当作坏字节记录。
• 先替换再校验。 如果要保留问题位置，应先记录 offset，再决定替换策略，否则后续定位会偏移。

相关问答

DecodeRuneInString 会返回错误对象吗？

不会。它只返回 rune 和字节宽度；需要区分非法编码时，使用 RuneError 与 size == 1 的组合判断。

非法 UTF-8 会一次跳过四个字节吗？

不会。标准库对非法编码返回宽度 1，让调用方可以从下一个字节继续恢复扫描。

字符串本身能不能包含非法 UTF-8？

能。Go 字符串是任意字节序列，不要求必须是 UTF-8；只有在解码、校验或输出到特定协议时，编码合法性才会成为业务约束。

什么时候直接使用 utf8.ValidString？

只关心“整段能不能接受”时使用它；需要精确记录损坏位置、统计坏字节或做定制替换时，再用 DecodeRuneInString 逐段扫描。

把判断写成可复查的规则

这类问题最终只需要记住一条规则：先读 rune，再读 size。空输入是 RuneError, 0，非法非空输入是 RuneError, 1，合法字符则按真实 UTF-8 宽度前进。把这三个状态写进测试用例，清洗昵称、解析日志和校验导入文件时就不会因为一个替换字符而误报，也不会在坏字节处停住。