Go range 字符串遇到非法 UTF-8 会返回什么

Go 对字符串执行 for range 时，如果遇到非法 UTF-8 序列，第二个迭代值会返回 U+FFFD，也就是 utf8.RuneError；对应的索引仍是该无效序列起始字节的位置，下一轮只前进一个字节。它不会 panic，也不会跳过整段剩余字符串。

Go 语言规范：https://go.dev/ref/spec#For_statements

unicode/utf8 文档：https://pkg.go.dev/unicode/utf8

记住三个值即可：非法输入得到 r == utf8.RuneError，该次非法解码宽度按 1 字节处理，下一次迭代从后一个字节继续。

range 会返回 RuneError 并前进一个字节

Go 的 string 可以保存任意字节，并不保证内容一定是合法 UTF-8。只有在对字符串使用 range 时，运行时才按 UTF-8 编码逐个解码 rune。下面用 \xff 在字符串中放入一个非法字节：

package main

import "fmt"

func main() {
	// \xff 单独出现时不是合法 UTF-8 编码。
	s := "A\xffB"

	// i 是当前 rune 起始位置的字节索引，r 是解码后的 rune。
	for i, r := range s {
		fmt.Printf("i=%d r=%#U\n", i, r)
	}
}

按照语言规范，这段字符串的三个字节分别是 0x41、0xFF、0x42，对应的迭代结果应为：

i=0 r=U+0041 'A'
i=1 r=U+FFFD '�'
i=2 r=U+0042 'B'

索引 i 是字节索引，不是“第几个字符”。非法字节位于索引 1，因此这一轮返回索引 1 和 U+FFFD；非法解码只消耗一个字节，下一轮就来到索引 2。

连续或混合非法序列会怎样展开

“前进一个字节”意味着 range 不会尝试把一整段无效数据合并成一个错误。假设字节序列是 E2 28 A1：E2 看起来像三字节 UTF-8 的起始字节，但后面的 28 不是合法续字节，因此索引 0 返回 RuneError，只消耗 E2；随后 28 又能独立解码成左括号；最后 A1 单独出现仍然非法。

package main

import "fmt"

func main() {
	// E2 后面没有合法续字节，A1 单独出现也不是合法起始字节。
	s := string([]byte{0xE2, 0x28, 0xA1})

	// range 每遇到一次非法编码，只跨过当前的一个字节。
	for i, r := range s {
		fmt.Printf("i=%d r=%#U\n", i, r)
	}
}

按规范推导，结果是索引 0 的 U+FFFD、索引 1 的 U+0028，以及索引 2 的 U+FFFD。这也解释了为什么一段损坏输入可能产生多个替换字符：range 是按无效字节逐次恢复，而不是把整段坏数据折叠为一个值。

RuneError 不一定代表原始数据非法

只写 if r == utf8.RuneError 不能断定输入存在非法 UTF-8。原因是替换字符 U+FFFD 本身也是合法 Unicode 码点，它的合法 UTF-8 编码是 EF BF BD。合法替换字符与非法字节解码失败，都可能让 range 返回同一个 rune 值。

package main

import (
	"fmt"
	"unicode/utf8"
)

func main() {
	// 第一个字符串包含合法编码的 U+FFFD，第二个包含非法字节。
	validReplacement := "\uFFFD"
	invalidByte := "\xff"

	// 两次 range 都会观察到 RuneError，不能只凭 rune 值区分来源。
	for _, s := range []string{validReplacement, invalidByte} {
		for _, r := range s {
			fmt.Println(r == utf8.RuneError)
		}
	}
}

另一个容易误判的点是 utf8.RuneLen(utf8.RuneError)。它返回的是 RuneError 自身编码所需的宽度，也就是 3，而不是原始输入被 range 消耗的字节数。因此它也不能反推出输入是否非法。

需要拒绝非法 UTF-8 时先校验

如果接口、配置文件或数据库字段要求“输入必须是合法 UTF-8”，最简单的做法是在业务处理之前调用 utf8.ValidString。它检查整个字符串，只返回是否合法，不改变原始内容。

package main

import (
	"errors"
	"unicode/utf8"
)

func acceptText(s string) error {
	// 业务要求文本必须完整有效时，在 range 之前整体校验。
	if !utf8.ValidString(s) {
		return errors.New("输入包含非法 UTF-8")
	}

	// 通过校验后再进行按 rune 的文本处理。
	for range s {
		// 在这里放置真正的文本业务逻辑。
	}
	return nil
}

这种写法适合用户名、消息正文、JSON 前的文本字段等明确要求 Unicode 文本的边界。若数据本来就是二进制内容，则不应强行放进 string 后当 UTF-8 处理，应该继续使用 []byte。

需要定位坏字节时手动解码

range 不直接暴露本轮解码宽度。如果需要报告具体坏字节位置，应使用 utf8.DecodeRuneInString。该函数对合法的 U+FFFD 返回 RuneError, 3，对非空非法编码返回 RuneError, 1，因此可以精确区分两者。

package main

import (
	"fmt"
	"unicode/utf8"
)

func invalidOffsets(s string) []int {
	var offsets []int

	// i 始终是待解码片段在原字符串中的字节起点。
	for i := 0; i 

这个模式适合导入文件、协议字段和日志清洗：既能保留原始字节，又能记录损坏位置。若只想得到可显示文本而不需要保留坏字节，可以使用 strings.ToValidUTF8 将连续的非法 UTF-8 片段替换为指定字符串：

package main

import (
	"fmt"
	"strings"
)

func main() {
	// 把每段连续的非法 UTF-8 替换为可见占位文本。
	clean := strings.ToValidUTF8("A\xff\xfeB", "[invalid]")
	fmt.Println(clean)
}

注意 ToValidUTF8 是修复策略，不是验证策略。替换后原始坏字节会丢失，审计、取证或协议解析场景应先保存原始 []byte，再生成用于展示的清洗版本。

常见误区

range 会在非法 UTF-8 处停止吗？

不会。它返回 U+FFFD，消耗一个字节，然后继续处理后续内容。

range 的索引是 rune 序号吗？

不是。索引是当前 rune 在原字符串中的起始字节位置。合法多字节 rune 会让下一个索引跨过多个字节，非法输入则只跨过一个字节。

看到 U+FFFD 就能确定原始字符串损坏吗？

不能。原字符串可能真的包含合法编码的 U+FFFD。整体判断用 utf8.ValidString，逐位置判断用 DecodeRuneInString 返回的 RuneError 与 size == 1 组合。

把字符串转成 []rune 能保留坏字节吗？

不能用它保留原始非法字节信息。转换过程会得到替换字符，之后无法仅凭 rune 切片恢复原始坏字节。需要保真时保留 []byte。

结论

Go range 遇到非法 UTF-8 时会返回当前字节索引和 U+FFFD，并只前进一个字节。只需要遍历文本时可以接受这个恢复行为；需要拒绝非法输入时先用 utf8.ValidString；需要区分合法 U+FFFD 和坏字节、并定位偏移时，使用 utf8.DecodeRuneInString 检查 RuneError 且 size == 1。