Go utf8.RuneLen 怎样判断 rune 占用几个字节

在 Go 中，rune 是一个 Unicode 码点值，而 UTF-8 是把这个值编码成字节序列的方式。要判断一个 rune 编码后占几个字节，直接使用 utf8.RuneLen：合法值返回 1 到 4，不能编码成合法 UTF-8 的值返回 -1。

官方文档：https://pkg.go.dev/unicode/utf8#RuneLen

记住一个边界：RuneLen 只回答“一个 rune 编码后有多宽”，不统计字符串长度，也不判断一段字节是否已经是合法 UTF-8。字符串总字节数看 len，rune 数量看 utf8.RuneCountInString，整段编码是否合法看 utf8.ValidString。

• ASCII 字符通常占 1 字节，中文等常见字符通常占 3 字节，部分补充平面字符占 4 字节。
• 返回 -1 只表示传入的 rune 不能被合法编码，不等于字符串里出现了一个错误字节。
• utf8.RuneError 是合法的替换字符，它本身可以编码为 3 字节，不能和非法 rune 混为一谈。

先分清 rune、字节和字符串长度

Go 的字符串本质上是只读字节序列，索引字符串得到的是一个字节，不是一个完整字符。一个 rune 是 Unicode 码点；它经过 UTF-8 编码后，可能变成 1、2、3 或 4 个字节。因此，RuneLen 的参数是单个 rune，而不是字符串或字节切片。

package main

import (
    "fmt"
    "unicode/utf8"
)

func main() {
    // 这里比较单个 rune 的编码宽度，以及整段字符串的字节数和 rune 数。
    text := "Go界面🙂"
    for _, r := range text {
        fmt.Printf("%q: rune=%d bytes=%d\n", r, r, utf8.RuneLen(r))
    }

    // len 统计 UTF-8 字节数，RuneCountInString 统计解码出的 rune 数。
    fmt.Println("string bytes =", len(text))
    fmt.Println("rune count =", utf8.RuneCountInString(text))
}

例如同一段文本里，G 和 o 各占 1 字节，中文字符通常占 3 字节，表情符号可能占 4 字节。不能用“字符个数乘以某个固定宽度”估算字符串容量。

用返回值判断单个 rune 的 UTF-8 宽度

RuneLen 的返回值非常适合放进容量预估、协议字段长度计算和分段缓冲逻辑中。返回值为 1 到 4 时，可以安全地把它视为该 rune 的编码宽度；返回 -1 时，说明该值超出 Unicode 合法范围，或者落在不能编码的代理项范围内。

func encodedWidth(r rune) (int, error) {
    // RuneLen 不会把非法 rune 静默转换成 RuneError，-1 要由调用方明确处理。
    width := utf8.RuneLen(r)
    if width 

这里不要把返回值当成“显示宽度”。中文、拉丁字母和表情符号在终端或网页中的视觉宽度，还会受到字体、组合字符和渲染环境影响；RuneLen 只描述编码层的字节宽度。

RuneError 合法，但非法 rune 返回 -1

utf8.RuneError 的值是 U+FFFD，也就是 Unicode replacement character。它是一个合法的 Unicode 值，utf8.RuneLen(utf8.RuneError) 会返回 3。相反，超出 utf8.MaxRune 的值，或 UTF-16 代理项等不能合法编码的值，会返回 -1。

func classifyRune(r rune) string {
    // 先区分“合法的替换字符”和“不能编码的 rune”。
    if r == utf8.RuneError {
        return "合法的 U+FFFD 替换字符，UTF-8 宽度为 3"
    }
    if !utf8.ValidRune(r) {
        return "非法 rune，不能直接编码"
    }
    return fmt.Sprintf("合法 rune，UTF-8 宽度为 %d", utf8.RuneLen(r))
}

如果非法字节已经被解码流程替换成了 U+FFFD，后续代码通常无法仅靠这个 rune 判断它原来是否是坏字节。需要保留输入质量信息时，应在字节层先调用 utf8.Valid 或使用返回宽度的解码函数记录错误。

把 RuneLen 放进字节缓冲区容量预估

如果要把一组 rune 编码到字节缓冲区，可以先累加每个 rune 的宽度，再一次性预留容量。预估阶段必须决定非法 rune 的策略：下面的示例选择直接报错，避免悄悄把非法值替换成另一个字节序列。

func estimateUTF8Capacity(rs []rune) (int, error) {
    // 累加每个 rune 的编码宽度，避免用固定倍数估算而浪费容量。
    total := 0
    for _, r := range rs {
        width := utf8.RuneLen(r)
        if width 

如果业务明确允许替换非法输入，可以先把非法 rune 归一化为 utf8.RuneError，再按 3 字节计入容量；如果输入来自协议、文件或数据库，建议保留“拒绝”与“替换”的策略差异，不要只因为最终能生成字符串就认为数据合法。

最后用三个 API 做核对

单个 rune 的宽度、整段字符串的字节数和 rune 数是三个不同问题。可以用下面这张速查表避免 API 用错：

常见问题是把 RuneLen 用在字符串上，或者把它的返回值理解成屏幕显示宽度。只要先明确层次：rune 是值、UTF-8 是编码、字符串是字节序列，选择 API 就不会混乱。

常见问题

为什么中文通常是 3 字节？

因为常见中文 Unicode 码点落在 UTF-8 的三字节编码区间。具体仍应对实际 rune 调用 utf8.RuneLen，不要按语言或字符类别写死。

RuneLen 返回 -1 时能直接转成字符串吗？

不建议。先明确是拒绝、替换为 RuneError，还是记录错误后跳过；否则会把输入数据质量问题隐藏在转换过程中。

RuneLen 能判断一段 []byte 是否合法 UTF-8 吗？

不能。它只接收一个 rune。对字节切片应使用 utf8.Valid，对逐个解码则使用 DecodeRune 并同时处理返回的宽度和错误情况。