Go mime.WordDecoder.DecodeHeader 怎么解析邮件主题编码

邮件主题出现 =?utf-8?q?...?= 或 =?utf-8?b?...?= 时，不要直接对整行做 Base64 解码。Go 标准库的 mime.WordDecoder.DecodeHeader 会扫描一个头字段中的多个 RFC 2047 encoded-word，按声明的字符集还原文本，并把结果交给调用方继续展示。

先区分 DecodeHeader 和 Decode 的输入边界

一个主题可能由普通文本、空格和多个 encoded-word 混合组成。例如显示名后面还可能跟着尖括号地址。Decode 只接收一个编码词；遇到完整主题时，应该让 DecodeHeader 处理整行。它会保留普通文本，也会按 RFC 2047 规则处理相邻编码词之间仅用于分隔的空白。

用 DecodeHeader 解析 Q 编码和 Base64 主题

最小用法是创建 mime.WordDecoder，把原始头字段传给 DecodeHeader，并始终检查返回的错误。下面的示例同时放入 Q 编码和 Base64 编码，便于确认调用方不需要先猜测编码方式。

package main

import (
	"fmt"
	"mime"
)

func main() {
	decoder := new(mime.WordDecoder)
	header := "=?utf-8?q?项目周报_=E2=80=94_第3周?="
	header += " / =?utf-8?b?5p2O5Lq65LiA5Liq?="

	// DecodeHeader 会识别整行中的多个 RFC 2047 encoded-word。
	decoded, err := decoder.DecodeHeader(header)
	if err != nil {
		// 生产代码应保留原始头或记录字段名，避免静默丢弃主题。
		fmt.Printf("主题解码失败: %v\\n", err)
		return
	}

	// decoded 已是 UTF-8 文本，可交给日志、模板或通知层。
	fmt.Println(decoded)
}

这里的 q 表示 Q 编码，等号十六进制片段代表字节；b 表示 Base64。两种编码混在同一个头字段里时，调用方式不变。不要把展示层的 UTF-8 转换再做一次，否则容易得到乱码。

遇到未知字符集时配置 CharsetReader

WordDecoder 默认处理 utf-8、iso-8859-1 和 us-ascii。encoded-word 声明其他字符集时，CharsetReader 会收到小写字符集名称和原始字节 Reader；转换器必须返回能够产生 UTF-8 的 Reader。字符集转换库的选择属于应用依赖，不能把“能读出字节”误当成“已经完成编码转换”。

package main

import (
	"fmt"
	"io"
	"mime"
)

func main() {
	decoder := &mime.WordDecoder{
		CharsetReader: func(charset string, input io.Reader) (io.Reader, error) {
			// charset 已被标准库规范化为小写，按支持清单路由转换器。
			switch charset {
			case "utf-8", "us-ascii", "iso-8859-1":
				return input, nil
			default:
				// 不支持的字符集必须显式报错，不能把原始字节冒充 UTF-8。
				return nil, fmt.Errorf("unsupported charset %q", charset)
			}
		},
	}

	decoded, err := decoder.DecodeHeader("=?x-example?q?subject?=")
	if err != nil {
		fmt.Println("需要接入真正的字符集转换器:", err)
		return
	}
	fmt.Println(decoded)
}

示例故意把未知字符集拒绝掉，实际项目应在对应分支接入可信的转换器，并确保返回的 Reader 输出 UTF-8。若转换器返回 nil Reader 或直接返回错误，DecodeHeader 也会向上返回错误。

把乱码现象拆成四类检查

还要注意，DecodeHeader 只解决“头字段里的编码词如何还原”。它不会代替邮箱地址解析、MIME multipart 解析，也不会修复发件方已经损坏的字节。排障时先记录原始头，再记录解码后的结果和错误，不要只保留最终展示文本。

相关问题

普通 UTF-8 邮件主题也能调用 DecodeHeader 吗？

可以。没有 encoded-word 的普通文本会按普通字符保留，统一走该入口能减少调用方对格式的分支判断。

为什么不直接调用 WordDecoder.Decode？

因为 Decode 面向单个 encoded-word；完整主题通常包含多个词、普通文本或地址部分，整行交给 DecodeHeader 更符合输入边界。

CharsetReader 返回原 Reader 就一定正确吗？

只有输入本来就是 UTF-8 或 ASCII 时才可能正确。对于其他字符集，必须实际转换成 UTF-8，不能仅凭 Reader 可读来判断编码已经完成。