Go x/text/encoding/traditionalchinese Big5 怎样转换繁体字节文本

我在接入一份旧的繁体中文数据时，最容易写反的是“谁要被转换”。外部文件里的 Big5 字节要先变成 Go 内部通常使用的 UTF-8 字符串，这时使用 traditionalchinese.Big5.NewDecoder()；如果要把 UTF-8 文本写回 Big5 文件，则使用 NewEncoder()。

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

最小做法是：Big5 输入走 Decoder，UTF-8 输入走 Encoder；完整数据用 Bytes 或 String，文件和网络流用 Reader 或 Writer。编码遇到目标字符集没有的字符要检查错误，解码异常字节则要留意替换字符。

先把 Big5、UTF-8 和转换方向分开

golang.org/x/text/encoding/traditionalchinese 提供的 Big5 是一个 encoding.Encoding，官方文档把它标为 Big5，也称 Code Page 950。它本身不直接提供一个“把任意字符串变成另一种编码”的顶层函数，而是通过 NewDecoder 和 NewEncoder 创建两个方向不同的转换器。

可以把方向记成下面这张静态关系图：外部 Big5 字节进入 Decoder 后得到 UTF-8；UTF-8 字节进入 Encoder 后得到 Big5。transform 包负责把这些转换器接到切片、字符串或 I/O 包装器上。

完整字节一次转换：优先用 Bytes

如果文件已经完整读入内存，Bytes 最直观。下面的示例同时展示 Big5 解码和反向编码；示例中的 rawBig5 代表从旧文件或接口读到的原始字节，不要先把它当成 UTF-8 字符串转换。

package main

import (
	"fmt"

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

func main() {
	// rawBig5 应来自 Big5 文件或接口，不能先按 UTF-8 解码。
	rawBig5 := []byte{/* 外部 Big5 字节 */}

	text, err := traditionalchinese.Big5.NewDecoder().Bytes(rawBig5)
	if err != nil {
		// 解码失败时保留错误，调用方再决定是否拒绝整份输入。
		panic(err)
	}
	fmt.Println(string(text))

	// Encoder 的输入必须是 UTF-8 字节，输出才是 Big5 字节。
	encoded, err := traditionalchinese.Big5.NewEncoder().Bytes([]byte("繁體中文"))
	if err != nil {
		// 目标编码无法表示某个字符时，这里会返回错误。
		panic(err)
	}
	fmt.Printf("Big5 bytes: % x\n", encoded)
}

Decoder.Bytes 返回转换后的字节切片；为了在 Go 中继续处理文本，通常把结果转成 string。反向写文件时不要把 encoded 当作可读的 UTF-8 文本打印，它只是目标编码的字节序列。

String 适合文本变量，但不改变字节语义

当数据已经放在 Go 的 string 中，可以使用 Decoder.String 或 Encoder.String。这里的关键仍然是输入的实际编码：传给 Decoder 的字符串只是承载原始 Big5 字节的容器，传给 Encoder 的字符串则应当是有效 UTF-8 文本。

package main

import (
	"fmt"

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

func convertText(rawBig5 string) (string, error) {
	// string 可以承载任意字节；这里明确它的内容是 Big5，而不是 UTF-8。
	decoded, err := traditionalchinese.Big5.NewDecoder().String(rawBig5)
	if err != nil {
		return "", fmt.Errorf("解码 Big5：%w", err)
	}
	return decoded, nil
}

func toBig5(text string) (string, error) {
	// Encoder.String 返回的 string 承载 Big5 字节，写文件时应按原样写出。
	encoded, err := traditionalchinese.Big5.NewEncoder().String(text)
	if err != nil {
		return "", fmt.Errorf("编码 Big5：%w", err)
	}
	return encoded, nil
}

不要用 string([]byte(...)) 来“猜测”编码。Go 的 string 不会自动携带字符集标签；是否是 Big5，要由数据来源和转换器的方向共同决定。

文件较大时，把 Decoder 接到 Reader

完整读取适合小文件，较大的旧文本可以把解码器放在读取链路中。Decoder.Reader 返回一个包装后的 io.Reader，后续代码只面对 UTF-8 输出。转换器在返回的 Reader 使用期间不要再拿来做其他操作，这是官方文档特别提示的生命周期边界。

package main

import (
	"fmt"
	"io"
	"os"

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

func readBig5File(path string) ([]byte, error) {
	f, err := os.Open(path)
	if err != nil {
		return nil, fmt.Errorf("打开 Big5 文件：%w", err)
	}
	defer f.Close() // 关闭底层文件，避免文件描述符泄漏。

	// Reader 持续把底层 Big5 字节转换为 UTF-8 字节。
	decodedReader := traditionalchinese.Big5.NewDecoder().Reader(f)
	data, err := io.ReadAll(decodedReader)
	if err != nil {
		return nil, fmt.Errorf("读取并解码 Big5 文件：%w", err)
	}
	return data, nil
}

这里的 io.ReadAll 仍然会把最终结果放入内存；如果后续是逐行解析或转发到下游，可以继续把 decodedReader 交给扫描器或其他消费者，以免一次性保存全部 UTF-8 内容。

写回 Big5 时一定要关闭 Encoder Writer

反向输出时使用 Encoder.Writer。它会缓存尚未完成转换的字节，调用 Close 才会把尾部数据冲刷到底层 Writer。这个关闭动作不是可有可无的清理，它直接关系到输出是否完整。

package main

import (
	"fmt"
	"os"

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

func writeBig5File(path string, text string) error {
	f, err := os.Create(path)
	if err != nil {
		return fmt.Errorf("创建 Big5 文件：%w", err)
	}
	defer f.Close() // 即使编码或关闭失败，也要释放文件资源。

	writer := traditionalchinese.Big5.NewEncoder().Writer(f)
	if _, err := writer.Write([]byte(text)); err != nil {
		return fmt.Errorf("写入 Big5 文本：%w", err)
	}
	if err := writer.Close(); err != nil {
		// Close 负责冲刷编码器缓存，错误不能被忽略。
		return fmt.Errorf("关闭 Big5 编码器：%w", err)
	}
	return nil
}

如果目标只是得到完整的 Big5 字节切片，NewEncoder().Bytes 更简单；只有数据要持续写入文件、响应体或其他 io.Writer 时，才需要这个流式包装。

异常字节和无法表示的字符怎么处理

解码和编码的错误语义不同。官方 Decoder 文档说明，不能按该编码转写的源字节不会自动变成 Go error，而会在输出里表现为 UTF-8 的替换字符 U+FFFD。如果业务不能接受静默替换，就要在进入转换前增加来源校验、文件格式约束或替换字符检测。

Encoder 则会对目标 Big5 字符集无法表示的 rune 返回错误；这时不要无条件使用 ReplaceUnsupported。官方文档把它定位为兼容旧系统的包装，并明确提醒可能造成数据丢失，优先考虑继续使用 UTF-8。

如果输入给 Encoder 的字节本身可能不是合法 UTF-8，可以把 encoding.UTF8Validator 与 Encoder 通过 transform.Chain 组合，让非法 UTF-8 更早返回错误。对只接收 Go 字符串的常规业务，字符串通常已经是合法 UTF-8，重点应放在“目标 Big5 是否能表示所有字符”。

结论与常见问题

处理 Big5 时先按数据流向选转换器：读取旧文件用 Big5.NewDecoder()，写回旧系统用 Big5.NewEncoder()；完整数据优先 Bytes 或 String，大文件和持续 I/O 使用 Reader 或 Writer。Decoder 的替换字符和 Encoder 的不可表示字符错误要分别处理，不能用一个通用的字符串替换逻辑掩盖数据损失。

Big5 和 UTF-8 可以直接把 []byte 转成 string 吗？

不能把类型转换当成字符集转换。string(b) 只改变 Go 对这段字节的承载类型，不会重新编码；必须先使用 Big5 Decoder 把字节转换成 UTF-8，再交给文本处理逻辑。

为什么解码没有报错，却出现了�？

这是 Decoder 对不能转写的源字节使用替换 rune 的表现。若替换会影响业务字段，应在数据入口限制来源编码，或在解码后的文本中识别 U+FFFD 并把该记录标记为需要人工处理。

Encoder 遇到繁体字就一定成功吗？

不一定。Big5 不是覆盖所有 Unicode 字符的集合，目标文本中若有 Big5 无法表示的字符，Encoder 会返回错误。调用方应记录失败字段、改用 UTF-8，或在确认可接受数据损失后使用兼容包装。

为什么 Writer 写完还要 Close？

编码器可能缓存了尚未组成完整转换单元的尾部字节，Close 会触发最后的冲刷并返回相关错误。只关闭底层文件而不关闭编码 Writer，可能得到不完整的 Big5 输出。