Go mime.WordDecoder CharsetReader 怎样接入自定义字符集转换

处理邮件主题时，最容易误判的一类问题是：mime.WordDecoder 能解开常见的 UTF-8 编码词，但遇到某个历史字符集就返回 mime: unhandled charset。这时不需要重新实现 RFC 2047 解析，应该把“字符集识别”和“字节转换”接到 CharsetReader 这一层。

本文用一个可落地的排障路径说明这条边界：先确认回调收到的参数，再接入 Windows-1252 转换 Reader，最后把未知字符集和转换错误交给 DecodeHeader 的调用方处理。

官方文档：https://pkg.go.dev/mime#WordDecoder

先看为什么默认解码会失败

故障通常出现在邮件主题或显示名进入业务层之前。代码调用 Decode 或 DecodeHeader，UTF-8、ISO-8859-1、US-ASCII 等内置路径可以继续走；一旦编码词声明了默认实现不认识的字符集，解码器就缺少“把原始字节变成 UTF-8”的办法。

影响面有两个：单个编码词调用 Decode 时会失败，包含多个编码词的整段主题调用 DecodeHeader 时也可能因为其中一个字符集无法转换而失败。不要在业务层先按空格切分主题再分别猜编码，这会破坏编码词之间的原始边界。

正确的修复入口是给解码器配置：

decoder := &mime.WordDecoder{
    CharsetReader: charsetReader,
}

之后由 CharsetReader 只负责字符集转换，仍然让标准库负责编码词的格式解析、Q/B 内容解码和多个编码词的拼接。

CharsetReader 回调到底收到什么

CharsetReader 的函数签名是 func(charset string, input io.Reader) (io.Reader, error)。第一个参数是字符集名称，标准库会把它规范成小写；第二个参数不是整个原始邮件头，而是当前编码词完成 Q/B 解码后的字节流。回调返回的 Reader 必须产生 UTF-8 字节，或者返回一个能说明转换失败原因的错误。

这一区分很重要：回调不负责识别 =?charset?encoding?text?= 外壳，也不应该把 input 当作尚未解码的 ASCII 文本。只要把“字符集名到转换 Reader”的映射做好，DecodeHeader 就能继续处理同一行中其它编码词。

建议在回调入口保留一个明确的字符集分支，并把不认识的值变成可定位的错误。因为名称已经是小写，分支里不必再对同一个字符串做大小写猜测。

用 charmap 接入 Windows-1252

对于 Windows-1252 这类单字节字符集，可以使用 golang.org/x/text/encoding/charmap 提供的解码器。它的 NewDecoder().Reader(input) 会包装输入流，读取时将源字节转换为 UTF-8；回调本身不需要把全部内容读进内存。

package main

import (
    "fmt"
    "io"
    "mime"
    "strings"

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

func charsetReader(charset string, input io.Reader) (io.Reader, error) {
    // 标准库传入的字符集名称已经是小写。
    switch strings.TrimSpace(charset) {
    case "windows-1252", "cp1252":
        return charmap.Windows1252.NewDecoder().Reader(input), nil
    default:
        return nil, fmt.Errorf("unsupported MIME charset %q", charset)
    }
}

func decodeSubject(header string) (string, error) {
    decoder := &mime.WordDecoder{CharsetReader: charsetReader}
    // DecodeHeader 负责多个编码词的顺序与空白拼接。
    return decoder.DecodeHeader(header)
}

这里的关键不是记住某个库的调用形式，而是守住两个返回约束：成功时返回非空的 UTF-8 Reader 和空错误；失败时返回错误，并且不要返回一个看似可读但实际丢失字节的空 Reader。这样调用方可以区分“成功解码”和“字符集不受支持”。

为什么返回字符串或吞掉错误会出问题

第一，接口需要的是 io.Reader，不是字符串。直接把输入读完、拼成字符串再返回，会让回调承担不必要的内存压力，也容易在未知字节上发生隐式替换。

第二，不能把所有字符集都兜底当作 UTF-8。这样做可能让页面“看起来有内容”，但字符已经损坏，后续无法判断是原始邮件的问题还是转换器的问题。

第三，不要在回调里打印并吞掉错误后返回 nil, nil。标准库需要一个可读的结果；错误应该沿着 DecodeHeader 返回给调用方，由调用方决定是记录原始主题、降级展示，还是拒绝这一条输入。

一个实用的调用层可以把错误和原始头同时保留：

subject, err := decodeSubject(rawHeader)
if err != nil {
    // 保留 rawHeader，便于后续定位未知字符集或坏字节来源。
    return fmt.Errorf("decode mail subject: %w", err)
}
fmt.Println(subject)

上线前按这张表检查

如果只需要支持一两种历史字符集，保持显式映射比引入“任意字符集都尝试”的黑盒更容易维护。以后增加映射时，为每个新增字符集补一个包含混合编码词的回归样例，并确认未知字符集仍然能返回错误，这样修复不会变成新的静默数据损坏点。

常见问题

CharsetReader 的 input 需要我先调用 ReadAll 吗？

通常不需要。转换器可以直接包装 Reader，按需读取；只有业务确实需要一次性审计原始字节时，才在更高层明确承担缓存成本。

为什么回调里没有看到完整的邮件主题？

因为回调的职责是单个字符集转换。完整主题的编码词遍历、顺序和空白处理属于 DecodeHeader，不要把两层职责混在一起。

未知字符集应该忽略还是报错？

默认建议报错并保留原始头。忽略会把“暂时不支持”伪装成“已经正确解码”，只有在产品明确接受降级展示时，才在调用层决定降级策略。

总结：WordDecoder 已经替你处理了 MIME 编码词的结构；自定义 CharsetReader 只需完成字符集到 UTF-8 Reader 的适配。把小写字符集分支、转换错误和 DecodeHeader 的调用边界写清楚，历史编码的兼容就能成为一个可测试、可扩展的局部能力。