Go unicode/utf8 RuneError 怎样区分替换字符和解码错误

排查 UTF-8 文本时，看到 utf8.RuneError 不等于已经发现坏字节。它既是 Unicode 的替换字符 U+FFFD，也可能是解码器遇到非法编码时返回的标记。真正有用的是同时看第二个返回值：对非空输入来说，RuneError + size == 1 才表示当前位置的 UTF-8 编码非法；合法的 U+FFFD 通常占 3 个字节。

官方 API：https://pkg.go.dev/unicode/utf8@go1.27.3#DecodeRuneInString

这篇只讨论标准库解码结果的判断，不展开文本清洗策略。先把“字符本身是替换字符”和“字节序列解码失败”分开，后面的日志定位和协议校验才不会误报。

RuneError 为什么有两种含义

现场最容易出现的误判是只写 if r == utf8.RuneError。这个判断无法区分三种输入：空字符串、合法编码的 U+FFFD，以及真正非法的 UTF-8。DecodeRuneInString 的返回宽度正好提供了区分线索。

用 size 判断是合法字符还是非法字节

下面的最小示例故意构造了三种输入。判断顺序应先看 size，再结合 r 做日志展示；不要把显示出来的替换符直接当作原始字节已经合法。

package main

import (
	"fmt"
	"unicode/utf8"
)

func inspect(label, s string) {
	// size 是当前 UTF-8 编码占用的字节数，不能省略。
	r, size := utf8.DecodeRuneInString(s)
	switch {
	case size == 0:
		// 空输入没有当前位置，RuneError 只是占位返回值。
		fmt.Printf("%s: 空输入\n", label)
	case r == utf8.RuneError && size == 1:
		// 非空输入返回宽度 1，说明当前字节编码非法。
		fmt.Printf("%s: 非法 UTF-8，首字节=%#02x\n", label, s[0])
	default:
		// size 大于 1 时，RuneError 也可能是合法的 U+FFFD。
		fmt.Printf("%s: rune=%U，size=%d\n", label, r, size)
	}
}

func main() {
	inspect("empty", "")
	inspect("replacement", string(utf8.RuneError))
	inspect("invalid", string([]byte{0xff, 'A'}))
}

在这个判断里，string(utf8.RuneError) 的三个字节是合法编码，所以不会进入非法分支；0xff 则会以一个字节的错误宽度返回。解码器这样设计还有一个实际好处：遍历时每次都能向前推进，不会因为坏字节卡在原地。

整段文本先校验，再定位坏字节

如果业务只关心整段文本能不能作为 UTF-8 使用，优先调用 utf8.ValidString，表达会比手写循环更直接。如果需要把坏位置写入日志，再按字节偏移遍历，每次增加解码器返回的 size。

package main

import (
	"fmt"
	"unicode/utf8"
)

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

这里的偏移是字节下标。中文字符可能占多个字节，因此不能把它当作“第几个字符”。若只需要真假结果，可以省略循环；若要保留上下文，则记录偏移后再截取原始字节更稳妥。

几个容易误判的边界

不要先转成 []rune 再判断。Go 会把非法 UTF-8 替换成 RuneError，原来的坏字节边界就丢失了。需要做协议校验或错误定位时，应先用 ValidString 或按字节扫描，再决定是否转换。

range 也会看到 RuneError。它适合正常遍历文本，但如果要解释错误原因，仍要看每次迭代给出的字节区间，不能仅凭展示字符判断。

空字符串是特殊返回。(RuneError, 0) 表示没有输入，不是“一个宽度为零的错误字符”。处理循环时要以 size 推进，并让空输入自然跳过。

可以把排查口诀记成三句：先看整段是否有效；看到 RuneError 再看 size；需要定位时记录字节偏移。这样既能接受合法的 U+FFFD，也不会把非法输入悄悄当成正常文本。

相关问题

为什么非法 UTF-8 返回的 size 是 1？

标准库把当前非法字节当作一个错误宽度处理，保证调用方继续向前推进。它不是说这个字节已经组成了一个合法字符。

只判断 utf8.ValidString 够不够？

如果需求只是拒绝非法文本，够用；如果还要记录哪一段输入损坏，就需要按字节遍历并保存偏移。

合法的 U+FFFD 需要被替换吗？

不应仅因为它的显示效果像“�”就替换。它可能是业务数据中的真实字符，是否清洗要由协议或业务规则决定。