Go x/text/encoding/unicode UTF16 怎样配置字节序与 BOM 策略

Go 处理 UTF-16 时，先确定两个问题：数据协议默认采用大端还是小端，以及文件开头是否允许或要求 BOM。golang.org/x/text/encoding/unicode 把这两个决定拆成 UTF16(e, b) 的两个参数：e 是默认字节序，b 是 BOM 策略。写出协议文件通常选 UseBOM 或 ExpectBOM；协议已经明确字节序且不使用 BOM 时选 IgnoreBOM。

最容易记住的规则是：没有外部协议保证时，让 BOM 参与识别并统一写出；协议已经明确 UTF-16BE 或 UTF-16LE 时，忽略 BOM，避免把数据中的 U+FEFF 当成字节序信号。

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

先把字节序和 BOM 拆成两个决定

字节序决定一个 UTF-16 码元的两个字节如何排列。BigEndian 表示 UTF-16BE，LittleEndian 表示 UTF-16LE。它只是“没有被 BOM 覆盖时”的默认值，不代表系统本机字节序；官方包没有所谓 native endian。

BOMPolicy 则决定输入开头的 BOM 怎么处理，以及编码输出时要不要写 BOM：

三种 BOMPolicy 解决的是不同协议

IgnoreBOM 不是“自动判断没有 BOM 的 UTF-16”，而是明确告诉解码器：输入类型已经由外部协议确定，任何 BOM 都不要拿来切换字节序。此时输入中的 U+FEFF 和 U+FFFE 会按普通 UTF-8 字节序列输出。

UseBOM 比较适合兼容性优先的文件交换：编码端主动写 BOM，解码端如果看到起始 BOM 就使用它指示的字节序，否则回退到传入的默认值。ExpectBOM 更严格，缺少 BOM 就停止转换并给出 ErrMissingBOM，适合协议把 BOM 作为必选头部的场景。

下面的构造函数只是配置，不依赖本机大小端，也不会替你判断业务协议：

package main

import "golang.org/x/text/encoding/unicode"

func main() {
	// 文件协议明确要求 UTF-16LE，且不使用 BOM 时，固定小端并忽略 BOM。
	withoutBOM := unicode.UTF16(unicode.LittleEndian, unicode.IgnoreBOM)

	// 允许文件用 BOM 指示实际字节序；没有 BOM 时回退到大端。
	optionalBOM := unicode.UTF16(unicode.BigEndian, unicode.UseBOM)

	// 协议要求必须有 BOM，缺少时解码会返回 unicode.ErrMissingBOM。
	requiredBOM := unicode.UTF16(unicode.BigEndian, unicode.ExpectBOM)

	_, _, _ = withoutBOM, optionalBOM, requiredBOM
}

用 Encoder 和 Decoder 读写 UTF-16

编码对象实现了 encoding.Encoding。实际转换时可以取它的 NewEncoder 或 NewDecoder，再配合 transform.Bytes 一次性处理内存字节。下面示例把 UTF-8 字符串编码成带 BOM 的 UTF-16LE，再按同一规则解码回来。

package main

import (
	"fmt"

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

func main() {
	enc := unicode.UTF16(unicode.LittleEndian, unicode.UseBOM)

	// 编码端从 UTF-8 字符串生成 UTF-16LE；UseBOM 会在输出开头写 BOM。
	raw, _, err := transform.Bytes(enc.NewEncoder(), []byte("配置文件：默认小端"))
	if err != nil {
		// 转换失败时立即停止，避免把不完整字节流当成成功结果保存。
		panic(err)
	}

	// 解码端会识别起始 BOM，并让它覆盖默认字节序。
	text, _, err := transform.Bytes(enc.NewDecoder(), raw)
	if err != nil {
		// 读取外部文件时应把错误返回给调用方，而不是静默替换乱码。
		panic(err)
	}
	fmt.Println(string(text))
}

如果数据量很大，不要一次性把整份文件放进内存，可以把 NewDecoder() 或 NewEncoder() 接到 transform.NewReader、transform.NewWriter，让转换随着读取或写入进行。

混合输入用 BOMOverride 处理

有些入口接收的是未知编码文本：常见输入可能是 UTF-8、UTF-16BE 或 UTF-16LE，且开头的 BOM 比外部配置更可靠。此时可以用 BOMOverride 包住一个 fallback transformer。它只检查输入开头的 BOM，识别到 UTF-8、UTF-16BE 或 UTF-16LE 后切换到对应 Unicode 解码；没有 BOM 时继续使用 fallback。

package main

import (
	"fmt"

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

func decodeText(data []byte) ([]byte, error) {
	// 无 BOM 时按 UTF-8 处理；已知输入首字符不会伪装成 BOM 时才适合这样回退。
	fallback := encoding.Nop.NewDecoder()
	decoder := unicode.BOMOverride(fallback)

	// BOMOverride 负责选择解码器，transform.Bytes 负责完成字节转换。
	decoded, _, err := transform.Bytes(decoder, data)
	if err != nil {
		// 保留原始错误，让上层决定是否拒绝这份输入。
		return nil, err
	}
	return decoded, nil
}

func main() {
	text, err := decodeText([]byte("普通 UTF-8 输入"))
	if err != nil {
		panic(err)
	}
	fmt.Println(string(text))
}

兼容注意：不要把乱码都归因于 BOM

第一，确认数据真的是 UTF-16。UTF-8 文件中的 BOM 是三字节序列，不能直接按 UTF-16 解码。第二，确认 BOM 出现在整个输入的开头；如果前面已有包装协议、空白或自定义头部，BOMOverride 不会在任意偏移处扫描。第三，ExpectBOM 的 ErrMissingBOM 是协议不满足的信号，不应该用替换字符掩盖。

如果业务已经从文件头、HTTP 头或协议字段拿到了明确的 UTF-16BE/LE 类型，优先使用 IgnoreBOM，并把字节序写进接口契约。相反，如果文件可能来自不同工具且 BOM 是约定入口，就使用 UseBOM；只有在 BOM 缺失必须拒绝时才使用 ExpectBOM。

• 明确协议：UTF16(unicode.BigEndian, unicode.IgnoreBOM) 或小端对应配置。
• 可选 BOM：用 UseBOM，默认字节序只负责无 BOM 的回退。
• 强制 BOM：用 ExpectBOM，把 ErrMissingBOM 当成输入错误处理。
• 多种 Unicode 输入：用 BOMOverride，并为无 BOM 输入明确 fallback。

常见问题

LittleEndian 是不是当前机器的本机字节序？

不是。它只是 UTF-16 没有被 BOM 覆盖时使用的默认字节序，代码应按数据协议选择。

UseBOM 和 ExpectBOM 的主要区别是什么？

两者编码时都会写 BOM；解码时 UseBOM 缺少 BOM 会回退到默认字节序，ExpectBOM 缺少 BOM 会返回 ErrMissingBOM。

IgnoreBOM 会自动丢弃文件开头的 BOM 吗？

不会。它不让 BOM 影响字节序，输入中的相关码元会按普通字符参与输出；只有 UseBOM 或 ExpectBOM 才把起始 BOM 当作字节序信号并从 UTF-8 输出中排除。

什么时候应该使用 BOMOverride？

当输入可能是带 BOM 的 UTF-8、UTF-16BE 或 UTF-16LE，并且无 BOM 时有一个可信的 fallback 编码时使用。它适合兼容多种 Unicode 文件，不适合把未知的任意编码都交给 BOM 猜测。