Go unicode/utf8.RuneError 怎样识别非法 UTF-8 解码结果

Go 里看到 utf8.RuneError，不能马上把它当成非法 UTF-8。它既是 Unicode 的替换字符 U+FFFD，也是解码失败时返回的 rune。真正有区分度的是第二个返回值：utf8.DecodeRune 对空输入返回 (utf8.RuneError, 0)，对非空但非法的字节返回 (utf8.RuneError, 1)；合法编码出来的 U+FFFD 通常占 3 个字节。

因此，单点判断可以写成 r == utf8.RuneError && size == 1，整段判断则直接使用 utf8.Valid 或 utf8.ValidString。下面把这三种状态和两类 API 放在一起说明。

RuneError 为什么不能单独当作错误

utf8.RuneError 的值是 U+FFFD，也叫 Unicode replacement character。它可能来自两种完全不同的情况：

• 输入本身就是合法的 U+FFFD 字符，解码结果是一个真实字符。
• 输入包含不能组成合法 UTF-8 的字节，解码器用 RuneError 表示无法还原。

这两种情况的共同点是第一个返回值相同，区别在于输入是否为空以及本次消耗的字节数。对非空输入来说，非法编码返回的 size 是 1；合法的三字节 U+FFFD 会返回正常的三字节宽度。

用 DecodeRune 定位非法字节

如果需求是指出“第几个字节开始异常”，就逐个调用 DecodeRune，并按返回的 size 前进。判断时先处理空输入，再处理 RuneError + size=1，这样不会把结束状态误报成坏字节。

package main

import (
    "fmt"
    "unicode/utf8"
)

// firstInvalidUTF8 返回第一个非法字节的偏移；没有非法字节时返回 -1。
func firstInvalidUTF8(data []byte) int {
    for offset := 0; offset 

这里的偏移是字节偏移，不是 rune 序号。一个合法中文字符可能消耗 3 个字节，因此循环必须使用 offset += size，不能固定加 1。遇到非法字节时返回当前位置，调用方可以据此记录日志、截断输入或交给上层处理。

合法 U+FFFD 与非法字节怎样区分

可以把合法的替换字符写进字符串，再和一个非法字节切片分别解码：

package main

import (
    "fmt"
    "unicode/utf8"
)

func main() {
    // 这是合法 UTF-8：U+FFFD 的 UTF-8 编码占 3 个字节。
    validReplacement := []byte("\uFFFD")
    r1, n1 := utf8.DecodeRune(validReplacement)

    // 0xff 不能作为独立的 UTF-8 起始字节。
    invalidBytes := []byte{0xff, 'x'}
    r2, n2 := utf8.DecodeRune(invalidBytes)

    fmt.Printf("合法替换字符: %U, size=%d\n", r1, n1)
    fmt.Printf("非法字节结果: %U, size=%d\n", r2, n2)
}

第一个结果虽然也是 RuneError，但 size=3，说明它是完整的合法编码。第二个结果是 RuneError 且 size=1，才符合非法非空输入的判断条件。

整段校验优先使用 utf8.Valid

如果只需要知道一段字节是否全部由合法 UTF-8 rune 组成，不需要错误偏移，就不必手写循环。utf8.Valid 接收字节切片，utf8.ValidString 接收字符串，返回值直接表达整段结论。

package main

import (
    "fmt"
    "unicode/utf8"
)

func main() {
    good := "订单-上海"
    bad := string([]byte{'o', 'k', 0xff})

    // ValidString 适合已经是 string 的输入，避免先转换成 []byte。
    fmt.Println(utf8.ValidString(good)) // true
    fmt.Println(utf8.ValidString(bad))  // false

    // Valid 适合网络缓冲区、文件块等 []byte 输入。
    fmt.Println(utf8.Valid([]byte(good)))
}

需要错误位置时选择逐点扫描；只需要在入口拒绝坏数据时选择整段校验。两者都不会替你把输入转换成目标编码，也不会告诉你业务字段是否符合要求。

常见误区与选择建议

尤其要避免把 for range 中得到的 RuneError 直接判为错误。范围遍历同样会把非法字节替换成 RuneError，但它不会把“这是合法 U+FFFD”与“这是非法输入”自动区分开。需要精确诊断时，保留原始字节并使用 DecodeRune。

总结

判断 Go 的 UTF-8 解码结果，可以记住三个组合：

1. (RuneError, 0)：输入为空。
2. (RuneError, 1) 且输入非空：当前位置的字节无法组成合法 UTF-8。
3. RuneError 配合正常字节宽度：可能是合法的 U+FFFD，不能直接报错。

文章中的技术事实以 Go 官方 unicode/utf8 文档为准：RuneError 是替换字符常量，DecodeRune 负责单点解码，Valid 和 ValidString 负责整段合法性判断。

相关问题

utf8.Valid 和 utf8.ValidString 有什么区别？

它们判断的规则相同，区别在输入类型：前者接收 []byte，后者接收 string。按现有数据形态选择即可。

size=1 就一定是非法 UTF-8 吗？

在本文讨论的 DecodeRune 返回组合里，要与 r == utf8.RuneError 一起判断，并且输入必须是非空。ASCII 字符也可能合法地占 1 个字节。

RuneError 能用来修复乱码吗？

不能。它只是解码器用于表示替换字符或错误结果的 rune。是否转码、丢弃或保留原始字节，应由上层业务决定。