Go x/text/encoding/simplifiedchinese GB18030 怎样转换四字节字符

处理 GB18030 文件时，最容易踩的坑是把“字符占几个字节”和“Go 字符串怎么保存”混为一谈。Go 字符串通常承载 UTF-8 字节，golang.org/x/text/encoding/simplifiedchinese.GB18030 则负责在 GB18030 字节流与 UTF-8 之间转换。四字节字符不需要手工拆分，应该交给编码器处理。

先区分 GB18030 字节和 Go 字符串

simplifiedchinese 包同时暴露了 GB18030、GBK 和 HZGB2312。其中 GB18030 是本文要用的编码对象；GBK 适合另一套字符范围，不能因为文件“也是中文”就互换。GB18030 中有些字符使用四字节序列，转换时不要按“两个字节一组”自行切片，否则很容易把后续字节错位。

安装依赖后，直接从编码对象创建解码器。解码结果是 UTF-8，后续可以交给 strings、encoding/json 或模板渲染继续处理。

# 添加文本编码转换依赖，版本由当前项目的 go.mod 管理
go get golang.org/x/text

用 Decoder 转换包含四字节字符的输入

如果数据已经在内存中，Bytes 最直接；如果需要传入字符串容器，也可以调用 String。下面的示例不假设某个字符固定对应某组十六进制字节，而是用一段来自 GB18030 文件的原始字节演示转换边界，并用 utf8.ValidString 检查结果。

package main

import (
    "fmt"
    "unicode/utf8"

    "golang.org/x/text/encoding/simplifiedchinese"
)

func decodeGB18030(raw []byte) (string, error) {
    // Decoder 把 GB18030 字节转换成 Go 侧使用的 UTF-8 字符串。
    text, err := simplifiedchinese.GB18030.NewDecoder().Bytes(raw)
    if err != nil {
        return "", fmt.Errorf("解码 GB18030 失败: %w", err)
    }
    if !utf8.Valid(text) {
        // 正常的 Decoder 结果应当是 UTF-8，这里用于尽早暴露异常输入链路。
        return "", fmt.Errorf("解码结果不是有效 UTF-8")
    }
    return string(text), nil
}

func main() {
    // 这里的 raw 应替换为文件或接口读出的 GB18030 原始字节。
    raw := []byte{0xD6, 0xD0, 0xCE, 0xC4}
    text, err := decodeGB18030(raw)
    if err != nil {
        panic(err)
    }
    fmt.Printf("文本=%s，rune 数量=%d\\n", text, utf8.RuneCountInString(text))
}

示例中的 raw 只是常见中文片段的演示数据；真正的四字节字符应直接保留文件读取到的完整序列。解码器会按 GB18030 规则消费字节，不需要先判断当前字符是单字节、双字节还是四字节。

用 Encoder 写回 GB18030，并处理不可表示字符

反向转换从 UTF-8 出发。Encoder 对目标编码无法表示的 rune 返回错误，因此生产代码不要把错误静默忽略。四字节字符是否能被当前转换表表示，应以编码调用的结果为准，而不是只看 UTF-8 中占几个字节。

func encodeGB18030(text string) ([]byte, error) {
    // Encoder 接收 UTF-8 字符串，输出可以写入旧系统的 GB18030 字节。
    encoded, err := simplifiedchinese.GB18030.NewEncoder().String(text)
    if err != nil {
        // 目标编码无法表示某个 rune 时保留错误，避免静默丢字。
        return nil, fmt.Errorf("编码为 GB18030 失败: %w", err)
    }
    return []byte(encoded), nil
}

func roundTrip(text string) error {
    encoded, err := encodeGB18030(text)
    if err != nil {
        return err
    }
    decoded, err := simplifiedchinese.GB18030.NewDecoder().Bytes(encoded)
    if err != nil {
        return fmt.Errorf("回读 GB18030 失败: %w", err)
    }
    // 回读只比较 UTF-8 文本，不能把不同编码的原始字节直接比较。
    if string(decoded) != text {
        return fmt.Errorf("回读文本不一致: %q", decoded)
    }
    return nil
}

如果业务必须继续输出而不是失败，可以显式选择替换策略，但要知道 ReplaceUnsupported 只适合兼容旧系统的遗留处理，可能造成信息损失；能使用 UTF-8 时仍应优先使用 UTF-8。

大文件改用 Reader，四字节边界交给流式转换

文件或 HTTP 响应较大时，不要先把全部字节拼成一个切片。Decoder.Reader 会包装输入流，调用方只需要继续读取 UTF-8 结果；同理，Encoder.Writer 可以把 UTF-8 写入转换成 GB18030 的输出流。

func copyGB18030ToUTF8(src io.Reader, dst io.Writer) error {
    // Reader 负责跨读取块保存转换状态，避免切块时拆散四字节序列。
    reader := simplifiedchinese.GB18030.NewDecoder().Reader(src)
    if _, err := io.Copy(dst, reader); err != nil {
        return fmt.Errorf("流式解码失败: %w", err)
    }
    return nil
}

排查乱码时重点看三项：输入是否确实是 GB18030、是否误用了 GBK、解码结果中是否出现 �。需要写回旧系统时，再额外检查 Encoder 的错误；这比先把四字节字符截断后再猜编码可靠得多。

常见问题

GB18030 四字节字符需要手工计算字节吗？

不需要。使用 GB18030.NewDecoder() 或 NewEncoder()，让转换器处理序列边界；手工按字节数切分只会增加错位风险。

为什么解码后出现替换字符？

通常说明输入并非预期的 GB18030，或字节序列不完整。先确认上游文件和读取链路没有把二进制内容当 UTF-8 重编码，再记录原始字节位置。

编码失败时能不能自动替换？

可以显式使用兼容包装，但它可能丢失原字符。只要下游允许，优先让接口和文件统一使用 UTF-8。