Go x/text/encoding/unicode UTF16 代理项为什么不能单独解码

Go 里用 golang.org/x/text/encoding/unicode 解码 UTF-16 时，代理项不能单独解码，根因不是 Go 把字符“截断”了，而是代理项本身只是一个 16 位代码单元：高代理项和低代理项组合后，才构成补充平面的 Unicode 标量值。孤立代理项不是合法标量值，解码器会把它转换成 U+FFFD（�）；如果输入正好停在不完整的字节或代理项边界，流式 Transformer 还可能返回 transform.ErrShortSrc，等待下一块数据。

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

代理项是 UTF-16 的代码单元，不是独立字符

UTF-16 先把基本多文种平面的字符表示成一个 16 位代码单元；补充平面的字符则使用两个代码单元。第一个是高代理项，第二个是低代理项。以表情符号为例，U+1F600 会编码成 D83D DE00，在 UTF-16LE 字节流中就是 3D D8 00 DE。其中任意两字节都不能单独代表这个表情。

因此，看到输出中的替换字符时，先不要把问题归因于字体或终端。输入可能只包含了高代理项，也可能把低代理项放在了前面，或者在分块读取时误把块边界当成字符边界。

先把字节序与 BOM 策略选对

unicode.UTF16 接收两个关键参数：默认字节序和 BOM 策略。协议已经明确是 UTF-16LE/BE 时，通常用对应的 IgnoreBOM；数据可能携带 BOM 且需要它覆盖默认字节序时，用 UseBOM；协议要求必须有 BOM 时才用 ExpectBOM。没有“本机字节序”这个安全默认值，不能把操作系统架构当成文件字节序。

用最小样例观察完整与孤立代理项

下面的例子把同一个解码器分别用于完整代理项对和只有高代理项的输入。transform.Bytes 会在结束时把结果交给 UTF-16 Transformer；代码注释只解释关键边界，便于把示例替换为文件读取。

package main

import (
    "fmt"

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

func main() {
    decoder := unicode.UTF16(unicode.LittleEndian, unicode.IgnoreBOM).NewDecoder()

    // U+1F600 的 UTF-16LE：高代理项 D83D + 低代理项 DE00。
    pair := []byte{0x3d, 0xd8, 0x00, 0xde}
    ok, _, err := transform.Bytes(decoder, pair)
    fmt.Printf("完整配对：%q，错误：%v\\n", string(ok), err)

    // 只有高代理项；它不是独立 Unicode 标量值，结果会是 U+FFFD。
    lone := []byte{0x3d, 0xd8}
    bad, _, err := transform.Bytes(decoder, lone)
    fmt.Printf("孤立代理项：%q，错误：%v\\n", string(bad), err)
}

这个结果的关键不是“是否返回 error”。孤立代理项可能被正常消费并输出替换字符；如果业务必须拒绝损坏输入，应在解码后检查 utf8.RuneError，或者在协议层增加更严格的输入校验。不要把所有 U+FFFD 都当成网络传输失败，它也可能来自源文件本身的非法代理项。

流式读取时不要丢掉跨块状态

文件和网络输入经常按任意大小分块。若第一块末尾只有一个字节，Transformer 会返回 ErrShortSrc，这表示源数据暂时不足以完成转换，不等于内容一定错误。若第一块刚好包含高代理项、下一块才包含低代理项，必须继续使用同一个包装后的 Reader 或同一个有状态 Transformer，让它看到连续输入。

实务上优先使用 decoder.Reader(r) 交给上层读取；不要每次 Read 都重新创建 Decoder，也不要把每块单独转成字符串后再拼接。前者会丢弃端序、BOM 和代理项状态，后者会把合法的跨块代理项误变成两个孤立单元。

五项检查清单

1. 确认源数据确实是 UTF-16，而不是 UTF-8 或 UTF-16LE/BE 判断相反。
2. 检查输入长度是否为偶数；奇数字节尾部通常说明截断或读取不完整。
3. 检查高代理项后是否紧跟低代理项，不能只按两个字节转成 rune。
4. 流式转换遇到 ErrShortSrc 时保留状态，等下一块继续。
5. 根据业务决定是接受 U+FFFD、记录告警，还是直接拒绝非法文本。

常见问题

为什么把 UTF-16 的两个字节直接转成 rune 会出错？

那只得到一个代码单元。代理项范围不是合法 Unicode 标量值，必须让 UTF-16 解码器完成配对和组合。

ExpectBOM 能修复孤立代理项吗？

不能。它只约束开头是否存在 BOM，并决定端序；代理项是否合法仍取决于后续代码单元的顺序和配对。

为什么完整代理项没有产生两个字符？

因为两个 UTF-16 代码单元描述的是一个补充平面字符。解码到 UTF-8 后，它会变成一个 rune，但占用四个 UTF-8 字节。