Go x/text/encoding/unicode UseBOM 为什么改变默认字节序选择

我第一次遇到这个问题，是把一批 UTF-16 文件交给同一个解码器处理：文件有时以小端 BOM 开头，有时没有 BOM。代码里明明传入了默认字节序，带 BOM 的文件却表现得像“改了配置”。这不是随机行为，而是 UseBOM 的设计目的。

官方地址：https://pkg.go.dev/golang.org/x/text/encoding/unicode

UseBOM 的规则是：如果 UTF-16 输入流以 BOM 开头，就用 BOM 指示的字节序覆盖默认值；如果没有起始 BOM，就继续使用传入的默认字节序。它只看流开头，后续出现的 BOM 不会再次切换字节序。

UseBOM 为什么会改变默认字节序

unicode.UTF16(e, b) 的第一个参数是默认字节序，第二个参数是 BOM 策略。把第二个参数设成 UseBOM 后，解码器会先检查输入最开始的两个字节：

• FE FF 表示 UTF-16BE；
• FF FE 表示 UTF-16LE；
• 没有起始 BOM 时，仍按 UTF16 调用传入的默认字节序解码。

因此，“默认字节序”不是对所有输入都强制生效的固定开关。它更像没有 BOM 时的后备方案；只要输入携带 BOM，BOM 就拥有更高优先级。起始 BOM 会被消费，不会作为普通字符写入 UTF-8 输出。

用一个最小示例看出两条路径

下面把默认值设为大端，再准备一段带小端 BOM 的 UTF-16 字节流。即使默认值是大端，FF FE 仍会让解码器按小端读取后续字符。

package main

import (
    "fmt"

    "golang.org/x/text/encoding/unicode"
    "golang.org/x/text/transform"
)

func main() {
    // 默认按大端处理，但输入开头的 FF FE 会声明为小端。
    withBOM := string([]byte{0xff, 0xfe, 0x41, 0x00, 0x42, 0x00})
    decoded, err := transform.String(
        unicode.UTF16(unicode.BigEndian, unicode.UseBOM).NewDecoder(),
        withBOM,
    )
    if err != nil {
        // 解码错误要立即返回，避免把错误文本继续写入业务数据。
        panic(err)
    }
    fmt.Printf("%q\n", decoded) // 输出 "AB"

    // 没有 BOM 时，UseBOM 回到调用方提供的默认大端字节序。
    withoutBOM := string([]byte{0x00, 0x41, 0x00, 0x42})
    decoded, err = transform.String(
        unicode.UTF16(unicode.BigEndian, unicode.UseBOM).NewDecoder(),
        withoutBOM,
    )
    if err != nil {
        // 第二次转换同样检查错误，避免静默接受截断输入。
        panic(err)
    }
    fmt.Printf("%q\n", decoded) // 输出 "AB"
}

这个例子里发生了两种不同的选择：

如果第二段无 BOM 的数据实际是小端排列，例如 41 00，而调用方仍传入 BigEndian，它就不能凭空猜出小端，结果自然会错误。UseBOM 解决的是“有标记时优先相信标记”，不是无标记数据的自动探测。

UseBOM、ExpectBOM 和 IgnoreBOM 怎么选

三种策略的差别不在名字，而在输入契约。官方文档把 UseBOM 定义为“可以有 BOM”，把 ExpectBOM 定义为“必须有 BOM”，而 IgnoreBOM 则完全不使用 BOM 选择字节序。

实践中最容易犯的错误，是把 UseBOM 当成“永远按 BOM 解码”。它并不要求 BOM 存在；如果业务必须拒绝缺少标记的文件，应使用 ExpectBOM 并单独处理 unicode.ErrMissingBOM。

编码方向也会受到 BOMPolicy 影响

上面的例子是 UTF-16 转 UTF-8。反方向从 UTF-8 编码为 UTF-16 时，规则更直接：UseBOM 和 ExpectBOM 会在输出开头插入 BOM，IgnoreBOM 不会插入。UTF-8 输入本身不需要先带 BOM。

package main

import (
    "fmt"

    "golang.org/x/text/encoding/unicode"
    "golang.org/x/text/transform"
)

func main() {
    // UseBOM 会让 UTF-16 输出从 FF FE（小端 BOM）开始。
    encoded, err := transform.String(
        unicode.UTF16(unicode.LittleEndian, unicode.UseBOM).NewEncoder(),
        "AB",
    )
    if err != nil {
        // 编码失败时不继续使用不完整的字节流。
        panic(err)
    }
    fmt.Printf("% x\n", []byte(encoded)) // 预期前缀为 ff fe
}

这意味着读写两端要共享同一个协议约定：一端自动写 BOM，另一端应该用能够识别 BOM 的策略读取。如果接收方已经通过文件格式或传输协议明确了字节序，继续让 BOM 参与选择反而会增加隐含行为，此时可以考虑 IgnoreBOM。

我会怎样排查“字节序被改了”

1. 先把输入开头的两个原始字节打印成十六进制，不要先把它转成字符串；
2. 确认调用的是 NewDecoder 还是 NewEncoder，读写方向会影响 BOM 的处理方式；
3. 记录 UTF16 的默认字节序和 BOMPolicy，重点看是否用了 UseBOM；
4. 若策略是 ExpectBOM，把 ErrMissingBOM 视为输入契约不满足，而不是改成随意猜测；
5. 检查 BOM 是否只出现在流开头。中途出现的 U+FEFF 或 U+FFFE 不会再次切换字节序。

我后来把“默认值”和“实际选择”分开记录，问题就不再像配置漂移：默认字节序描述无 BOM 时的兜底，起始 BOM 描述这一次输入自己的声明。两者本来就不是同一层信息。

最后的选择建议

• 文件来源混杂，既可能有 BOM 又可能没有：用 UseBOM，同时明确无 BOM 时的默认字节序。
• 协议要求 BOM 是必需字段：用 ExpectBOM，将 ErrMissingBOM 作为输入错误处理。
• 协议已经规定固定字节序，BOM 只是普通数据或不应参与决策：用 IgnoreBOM。

相关问题还可以继续追问：为什么无 BOM 的 UTF-16 不能可靠自动识别？答案是它缺少告诉解码器字节序的外部信息；为什么文件首部 BOM 被丢掉？因为 UseBOM 和 ExpectBOM 把它当作控制输入而不是正文字符；为什么 UTF-8 的 BOM 规则不同？因为 UTF-8 没有字节序问题，BOM 更多是文件签名约定。