Go mime.WordEncoder.Encode 怎样把中文主题编码成邮件头可用格式

处理中文邮件主题时，真正需要解决的是“邮件头字段怎样表示”，不是把正文先转成 Base64。Go 标准库的 mime.WordEncoder.Encode 专门负责 RFC 2047 encoded-word：输入是 ASCII 且没有特殊字符时原样返回，包含中文或需要转义的字符时才生成编码词。

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

我的经验是先把编码和发送拆开：Encode 只返回一个适合放进邮件头的字符串，SMTP 连接、正文 MIME 结构和最终投递仍由邮件发送层负责。

先判断这段文本是否真的需要编码

Encode 的第一个容易忽略的特点是“能不编码就不编码”。普通 ASCII 文本没有控制字符和特殊字符时，返回值就是原字符串；不要为了格式统一而把所有主题强制包成 encoded-word。

package main

import (
	"fmt"
	"mime"
)

func main() {
	encoder := mime.QEncoding
	// ASCII 普通主题保持原样，便于日志阅读和兼容旧的邮件头。
	plain := encoder.Encode("utf-8", "Build report")
	// 中文主题需要 RFC 2047 encoded-word，字符集要与输入字符串匹配。
	encoded := encoder.Encode("utf-8", "构建报告：今晚发布")

	fmt.Printf("plain=%s\nencoded=%s\n", plain, encoded)
}

这里的 utf-8 不是“把字符串转换成 UTF-8”的开关，而是告诉邮件接收方这段 encoded-word 的字符集名称。Go 字符串通常保存 UTF-8 字节，但如果输入来自其他编码数据源，应该先完成字符集转换，再把实际字符集传给编码器。

QEncoding 和 BEncoding 应该怎么选

Go 提供两个常用编码器：

两者都返回 RFC 2047 encoded-word，差别主要在编码方式，不在于“一个用于主题、一个用于显示名”。选择时看字段内容和接收方兼容性，不要把 BEncoding 误认为邮件正文的通用编码。

package mailheader

import "mime"

// EncodeDisplayName 把显示名编码成可放入 From 等邮件头的位置。
func EncodeDisplayName(name string) string {
	// Q 编码通常更容易观察 ASCII 与中文混合内容的边界。
	return mime.QEncoding.Encode("UTF-8", name)
}

// EncodeSubject 把主题编码成单个邮件头值，不负责发送邮件。
func EncodeSubject(subject string) string {
	// B 编码只改变 encoded-word 的表示方式，不改变原始主题字符。
	return mime.BEncoding.Encode("utf-8", subject)
}

字符集名称大小写不敏感，UTF-8 和 utf-8 都表示同一个 IANA 字符集名称。为了让日志和测试稳定，项目中最好统一写法，并把编码策略集中在一个小函数里。

把返回值放入主题和显示名，而不是重复编码

编码函数返回的是完整的 encoded-word 或原文。组装邮件头时，把它当作字段值使用即可；不要先手写 =?utf-8?q?，也不要对已经编码的返回值再次调用 Encode。

package mailheader

import (
	"fmt"
	"mime"
)

// BuildHeaders 只组装邮件头字符串，SMTP 投递由调用方负责。
func BuildHeaders(subject, displayName, address string) string {
	// 每个字段只编码一次，避免出现嵌套的 encoded-word。
	encodedSubject := mime.QEncoding.Encode("utf-8", subject)
	encodedName := mime.QEncoding.Encode("utf-8", displayName)
	return fmt.Sprintf("Subject: %s\r\nFrom: %s ", encodedSubject, encodedName, address)
}

如果主题本身是普通英文，encodedSubject 仍可能只是原文；这正是标准库的预期行为。真正发送时还要遵守邮件头的折行、字段注入防护和消息整体格式要求，不能因为 Encode 返回了字符串就跳过上层检查。

长文本、特殊字符和错误边界

长中文主题不应由业务代码手工切分。Go 的实现会在需要时拆分 UTF-8 encoded-word，并避免把多字节字符从中间切开；调用方只需把完整字符串交给 Encode。

• 主题或显示名来自用户输入时，先阻止换行符混入字段值，避免把普通字符串拼成额外邮件头。
• 输入若不是 UTF-8 文本，先转换为目标字符串，再选择对应字符集名称；不要只改参数大小写来伪造转换。
• 不要混用“邮件头编码”和“正文传输编码”。正文可能需要 multipart 或 quoted-printable 等另外的 MIME 结构。
• 编码后的字符串只应作为一次组装结果保存，避免把它当作下一轮输入反复编码。

排查时可以按“输入是否含非 ASCII、字符集是否真实匹配、选择了哪种编码器、是否重复编码、发送层是否又改写字段”五项查看。这样能把乱码问题定位到数据源、头部编码或发送层，而不是笼统归咎于 SMTP。

相关问题

ASCII 英文主题需要调用 Encode 吗？

可以统一调用，标准库会在没有特殊字符时原样返回；是否统一调用取决于项目希望把编码策略集中管理还是保留简单字段。

QEncoding 和 BEncoding 哪个更好？

没有脱离场景的绝对答案。ASCII 与中文混合且希望可读时可优先考虑 QEncoding；更看重统一的 Base64 表示时可选择 BEncoding。

Encode 能解决邮件发送失败吗？

不能。它只负责 encoded-word 表示，连接、认证、正文结构、折行和服务端响应仍属于邮件发送流程。

记住一个边界就够了：mime.WordEncoder.Encode 把“字符字符串”转换成“可放入邮件头的 RFC 2047 词”，它不会替你完成字符集转换、SMTP 投递或正文 MIME 组织。用真实字符集调用一次，再把返回值放进对应字段，中文主题和显示名就能保持清晰的职责分层。