企业官网建设流程全解析

1. 先搞清楚这个库到底替你干了什么

第一次接触 IMAP 是在一个内部工单系统的需求里：要求把某个客服邮箱的新邮件同步到本地库，做关键词归类和工单自动生成。我当时的想法很天真——不就是 TCP 连上去敲几行字符串吗。结果第一版手写协议栈跑到第三天就崩了，日志里全是BAD Command syntax error和莫名其妙的NO [ALERT]，还有一个更难查的现象：拉取第 100 封邮件的时候，拿到的正文和标题对不上，因为中间有人删了一封信，序列号整体前移了。这三类问题——协议语法、服务端策略、序列号漂移——正好是把人从“自己动手”推向“用现成库”的三个理由。

mxk/go-imap是我后来换上的方案，它是一个用纯 Go 实现的 IMAP4rev1 协议库，同时包含客户端和服务端两套实现。客户端部分能做的事包括：建立连接、TLS/STARTTLS 握手、多种鉴权、列出与选择邮箱、条件搜索、批量 FETCH 元数据与正文、打标、移动/删除、IDLE 长连接推送；服务端部分能让你自己实现一个 Backend 接口，把邮件读写挂到任意存储上，从而对外提供一个标准 IMAP 服务。它不需要 CGO，编译出来是单个静态二进制，交叉编译到常见平台几乎没有额外配置成本。

适合读这篇内容的人大致分三类：一是要在后端服务里做邮件同步、邮件归档、邮件提醒的 Go 开发者；二是想给自己产品加一个“用邮件客户端就能访问”的接口，需要自己实现 IMAP 服务端的人；三是被各种“连上了但拿不到数据”“能收信但中文文件夹名乱码”这类问题卡住的调试者。三类人的关注点不同，但踩的坑高度重合，所以下面按“连接—目录—标识—数据—变更—长连接—服务端—排错”的顺序铺开，每一段都尽量说清“为什么这样做”。

1.1 标准库的 net/mail 只是个解析器，不是协议栈

很多人第一次找 Go 的邮件方案，会搜到net/mail，用两行代码把一封 RFC 822 格式的文本解析成mail.Message，觉得很爽，然后误以为“邮件这块标准库已经够了”。这是个典型的认知错位。net/mail的职责边界非常窄：它处理的是“一封已经拿到手的邮件文本”到“结构体”的转换，负责From、To、Subject、Date这些头字段的解析和地址列表的拆分。它不知道什么是服务器、什么是连接、什么是状态机。

真正在 IMAP 场景里耗时的是协议层：你要维护一个带标签的命令-响应配对机制（客户端发出的每条命令前面有个A001、A002这样的 tag，服务端回应时必须带上同样的 tag，而且中间可能夹杂未经请求的*开头响应）；你要处理字面量（literal）机制，也就是服务端先说“下面有 1234 字节的数据”，然后原样吐出一段二进制，这段二进制里可能有换行、可能有+号，绝对不能按行读；你要处理能力协商，先查服务端支持哪些扩展，再决定用MOVE还是COPY加STORE加EXPUNGE。

这几件事用裸 socket 自己写，工作量大概是一到两周，而且边界情况极多。库的价值就在于它把这层状态机封装好了，你只管调用方法、读 channel、处理 error。理解这个分层，后面的很多设计选择就顺了：库负责协议正确性，你负责业务语义正确性。

1.2 客户端与服务端双栈，是这个库比较少见的组合

市面上绝大多数 IMAP 库只有一个方向。要么只能当客户端连别人的服务器，要么只能当服务端被别人连。mxk/go-imap两个方向都有，而且是共用同一套协议常量和数据结构定义，这一点在做联调时特别舒服——你可以在本地起一个服务端实现，让客户端去连它，完全不依赖外部邮件服务，也不需要网络。

服务端这块的实际用途比想象中广。我见过两种典型场景：一种是做邮件归档系统，把历史邮件按项目存进对象存储，但业务方希望沿用他们习惯的邮件客户端来浏览，这时候自己实现一个 IMAP 服务端，底层接对象存储，前端用任何客户端都能看，比自己做个 Web 界面省事得多；另一种是做测试替身，CI 环境里不可能连真实邮件服务，起一个内存后端的 IMAP 服务，跑完就丢，测试稳定性和速度都上来了。

注意：服务端的AllowInsecureAuth这类开关只适合本地调试，任何对外暴露的实例都必须走 TLS。

1.3 三条路线摆在一起看，选型就没那么纠结了

我一般会把候选方案列成一张表，把“将来最可能出问题的地方”写进同一行，这样决策依据就落在风险上而不是喜好上。

第三条路线的“维护负担低”是有前提的：你得接受库对协议的抽象方式，而不是绕过它去拼命令。有些人为了图快，直接用库的原始命令发送接口去拼a001 FETCH ...，那就等于把手写协议栈的风险又抱回来了，只是换了个位置。

2. 连接这条链路要一次搭稳，别反复返工

连接层是整个功能的地基，但这部分代码最容易被草率对待——很多人在本地跑通了就直接上生产，然后在灰度期间被超时、被证书、被鉴权方式轮番教育。我现在的习惯是：连接这一段单独抽一个包，不掺任何业务逻辑，把所有可能失败的点显式处理掉，上层只拿到一个“可用或不可用”的结论。

2.1 模块引入与最小可运行骨架

先把依赖加进来。以经典的单包布局为例，客户端在client子包，协议常量与数据结构在主包：

go get github.com/mxk/go-imap go get github.com/mxk/go-imap/client

不同时期的分支在包布局上有差异，有的版本把客户端叫imapclient，能力常量也做了重命名，所以第一步永远是去看仓库里go.mod的模块路径和目录结构，别照着旧文章抄 import。我吃过这个亏：照抄一段示例代码，编译报undefined: imap.FetchRFC822，折腾了半小时才反应过来是分支版本不同。

下面这段是最小骨架，把拨号、登录、列目录、退出四件事串起来，可以当成日常的“连通性冒烟测试”：

package main import ( "crypto/tls" "fmt" "log" "net" "time" "github.com/mxk/go-imap" "github.com/mxk/go-imap/client" ) func main() { // 拨号超时一定要设，默认零值意味着无限等待 dialer := &net.Dialer{Timeout: 10 * time.Second} c, err := client.DialWithDialerTLS(dialer, "mail.example.com:993", &tls.Config{ServerName: "mail.example.com", MinVersion: tls.VersionTLS12}) if err != nil { log.Fatalf("dial: %v", err) } defer c.Logout() if err := c.Login("sync-bot", "app-specific-token"); err != nil { log.Fatalf("login: %v", err) } // 列目录用 channel 收，注意必须在另一个 goroutine 里发起 boxes := make(chan *imap.MailboxInfo, 32) done := make(chan error, 1) go func() { done <- c.List("", "*", boxes) }() for m := range boxes { fmt.Printf("name=%q delim=%q attrs=%v\n", m.Name, m.Delimiter, m.Attributes) } if err := <-done; err != nil { log.Fatalf("list: %v", err) } }

这段代码有两个细节值得说。第一，DialWithDialerTLS里显式写了ServerName，不要图省事留空。留空时 TLS 库会从地址里切出主机名来校验，看着没问题，但一旦你用了自定义 dialer 换过目标地址（比如走内网网关），校验就会失败，而且报错信息很难懂。第二，List是异步的，它把结果往 channel 里塞，塞完才通过done报错；如果你忘了读 channel 里的数据就直接等done，会直接死锁。这个模式在这个库里到处都是，Fetch、List、Search的流式变体都是同一套，习惯之后反而觉得清爽。

2.2 握手阶段先把 Capabilities 摸清楚

连上之后、登录之前，服务端一般会主动推一段* OK [CAPABILITY ...]，告诉你它支持哪些扩展。库会把这份清单缓存下来，并提供查询方法。这个清单决定了很多后续策略，比如：

• 有MOVE扩展，删除邮件可以用一次MOVE完成；没有的话就得走COPY→STORE +Deleted→EXPUNGE三步。
• 有IDLE扩展，才能做准实时推送；没有就只能轮询。
• 有UIDPLUS，APPEND之后能直接拿到新邮件的 UID，省掉一次全量查找。
• 有ENABLE+UTF8=ACCEPT，中文条件下的搜索才可能真正可用。

我会在连接初始化时打印一次能力清单并落到日志里，尤其是灰度期间。有一次线上突然出现“删除后邮件又回来了”，查了半天发现是机房调整后换了新的前端设备，不再支持MOVE，而我们的代码没有做能力探测，直接调用了移动接口，库内部降级失败但错误被我们吞掉了。从那以后，能力探测的结果我都会记一笔。

caps, err := c.Capability() if err != nil { log.Printf("capability probe failed: %v", err) } log.Printf("server caps: %v", caps)

2.3 鉴权方式的选择顺序

鉴权这块要按“服务端支持 + 安全等级”两个维度来挑，别默认用最熟的那个。

实际接入时，绝大多数账号类场景用的是“用户名 + 应用专用密码”，走Login方法就够了；对接开放平台时是“用户名 + 短期令牌”，走 SASL 的Authenticate。这里有个容易忽略的点：令牌过期时，服务端通常在SELECT或FETCH阶段才返回NO [AUTHENTICATIONFAILED]，而不是在认证阶段就报错。因为 IMAP 的会话是有状态的，认证失败可能表现为后续任意一条命令失败。所以错误处理不能只盯着登录那一步，整个会话生命周期里一旦出现带AUTHENTICATIONFAILED字样的响应，就要触发重新取令牌并重连。

3. 目录列表里藏着两个高频坑：分隔符和编码

拿到目录列表之后，很多人直接把Name存进数据库，然后按数据库里的名字去Select。这一步在英文环境下能跑通，一换中文就出问题，或者是重命名失败，或者是选择了一个不存在的邮箱。原因有两个，一个是分隔符的语义没吃透，一个是文件夹名在协议层用的是变种编码。

3.1 delimiter 不是装饰品，它决定了目录层级怎么表达

LIST的每个返回项里都带一个Delimiter字段。多数服务端返回/，也有返回.的，理论上还可能是任意单个字符。它表示“层级分隔符”，也就是说Work/2024/Q1这个字符串，用/分隔就表示三层嵌套。你在创建子目录时必须用服务端指定的那个字符去拼名字，用错了会得到一个看似成功、实际上是个平铺名字的邮箱。

更隐蔽的一点是INBOX的大小写。协议里明确规定INBOX是一个保留名，且不区分大小写，但其他邮箱名是区分大小写的。我见过有实现把inbox存库，回读时去Select("inbox")，在某些服务端上能过、在某些上失败。稳妥做法是：凡涉及收件箱，统一用大写INBOX常量，别从数据库里读用户输入的原样值。

还有一个坑在层级遍历上。想递归列出所有子目录，List的第二个参数要给*，它表示“匹配任意层级”；给%则只匹配当前层级。有人写List("", "%", ch)想做全量同步，结果只拿到第一层，还以为是服务端不支持嵌套。

// 递归列全部 go func() { done <- c.List("", "*", boxes) }() // 只看第一层 go func() { done <- c.List("", "%", boxes) }()

3.2 中文文件夹名走的是 modified UTF-7，不做转换必然出错

IMAP4rev1 规定邮箱名使用 modified UTF-7 编码传输。这个编码的动机很实际：早期的邮件客户端不一定能处理 8 位字节，所以协议规定把非 ASCII 部分按 UTF-16BE 编码、再 Base64、再做两处字符替换，最后用&和-包起来。具体的变形规则是：

1. 把非 ASCII 字符序列按 UTF-16BE 编码成字节；
2. 对这段字节做标准 Base64；
3. 把 Base64 里的/全部替换成,（因为/会被当成分隔符）；
4. 去掉末尾的=填充符；
5. 在前后分别加上&和-；
6. 文本里原本出现的&字符，编码成&-。

所以你在协议层看到的名字，和它在界面上的样子完全不是一回事。库一般会提供一个编解码工具函数，用它转换一次再存库：

// 编码：业务名 -> 协议名，用于 Create / Select / Status encoded := encoder.Encode("已归档").String() // 解码：协议名 -> 业务名，用于展示与入库 readable, err := decoder.Decode(encoded)

实际经验是：数据库里存编码前的可读名，发命令前再编码。反过来存编码后的名字看着省一次转换，但当服务端更换实现、编码细节出现细微差异时，你的历史数据就全部对不上了。另外，某些服务端对特定字符（比如&、%、*）的处理很随意，创建文件夹时如果名字里带这些字符，最好先做一次往返验证：创建后立刻列出名字，比对是否与预期一致，不一致就报警，别等几天后才发现数据落在了一个奇怪的名字下面。

3.3 创建目录要做成幂等操作

CREATE一个已经存在的邮箱，服务端会返回NO。在同步任务里这是常态而不是异常——任务重试、多实例并发、上次执行到一半被杀掉，都可能让你重复创建。我现在的写法是：先List一次把已有目录放进 map，需要时查 map，没有再创建；即使这样，创建失败时也要再List一次确认是否已被别的实例创建，确认存在就当作成功处理。

func ensureMailbox(c *client.Client, name string) error { boxes := make(chan *imap.MailboxInfo, 64) done := make(chan error, 1) go func() { done <- c.List("", "*", boxes) }() exist := false for m := range boxes { if decodeName(m.Name) == name { exist = true } } if err := <-done; err != nil { return err } if exist { return nil } if err := c.Create(encodeName(name)); err != nil { // 可能是并发创建，再确认一次 return nil } return nil }

这段代码有个取舍：为了幂等，每次都要全量列一遍目录。目录数量少的时候无所谓，几千个目录时这一趟会明显拖慢启动。折中办法是启动时全量列一次缓存在内存里，之后每次创建成功后手动往缓存里补一条，同时给缓存加一个较长的过期时间，定期刷新。

4. 序列号与 UID 的区别，是整个 IMAP 开发里最容易翻车的地方

如果只能给一条建议，我会说：永远用 UID，永远不要用序列号定位邮件。这不是洁癖，是我被坑过之后形成的肌肉记忆。序列号是“当前邮箱里第几封”，会随着任何一封邮件的删除而整体前移；UID 是服务端分配的一个单调递增的标识，在同一个UIDVALIDITY周期内不会变，也不会被复用。

4.1 两者的失效时机完全不同

序列号的失效时机是“任何影响邮箱内邮件数量的操作”：删除、移动、EXPUNGE。你在时刻 T 拿到第 10 封是 A 邮件，删掉第 3 封，第 10 封就变成了 B 邮件。如果你的程序是“先搜索拿到一批序列号，再逐条去取正文”，中间只要有一次删除（哪怕是你自己的另一条命令触发的），后面的数据就全错位了。这类 bug 特别难查，因为它不报错，只是数据张冠李戴。

UID 的失效时机只有一个：UIDVALIDITY变化。这个值在SELECT的OK响应里能拿到，它是一个邮箱的“代际编号”。服务端重建邮箱、迁移存储、做了一次大批量整理时，都可能换一个新的UIDVALIDITY，此时旧 UID 全部作废。所以完整的定位是“UIDVALIDITY+UID”这个二元组，只存 UID 是不严谨的。

status, err := c.Select("INBOX", false) if err != nil { return err } log.Printf("selected inbox: uidvalidity=%d uidnext=%d", status.UidValidity, status.UidNext)

4.2 UIDVALIDITY 变了怎么办，得有个明确的兜底

我的处理策略分两档，取决于业务对“漏邮件”的容忍度。

第一档是“不能漏”：UIDVALIDITY一旦变化，直接清空本地这个邮箱的同步游标，从头做一次全量对齐。代价是可能要拉几千封邮件的元数据，但能保证不漏。做法是记录一个sync_state表，字段是mailbox、uidvalidity、last_uid，每次同步前先比对。

第二档是“可以容忍少量漏”：变化时按Date头做一次粗范围回溯，比如只回溯最近 7 天，其余历史的以SEARCH结果为准做差集补齐。这种做法适合日志类、通知类邮箱，不适合工单类、归档类。

无论哪种，都必须在变化发生时打一条明确的告警日志。我见过有系统悄悄把UIDVALIDITY变化当成“正常情况”处理，结果某天服务端换了存储，游标没重置，导致连续两周的新邮件全部漏收，而监控上一切正常——因为同步任务每天都“成功”跑完了，只是拉回来 0 封。

4.3 SeqSet 的构造与两个常见越界错误

库里用SeqSet表示“一批 UID 或序列号”，可以AddNum单个、AddRange范围。这里有两个错误写法值得单独拎出来说。

第一个是把AddRange(1, 0)当成“从 1 到 0”。在这个库的约定里，0是“最后一个”的通配，AddRange(1, 0)表示“1 到末尾”，AddRange(100, 0)表示“从第 100 到末尾”。这个约定来自协议里的*。我一开始没留意，写了AddRange(last, maxUint32)，编译能过，运行时报BAD，因为maxUint32不是一个合法序号。

第二个是超范围。用序列号取第 50 封，但邮箱里只有 30 封，服务端会返回BAD甚至直接破坏响应配对。UID 场景相对安全，超出范围的 UID 会被忽略；序列号场景则会硬报错。这也是“用 UID 更安全”的一个佐证。

set := new(imap.SeqSet) set.AddRange(lastUID+1, 0) // 从上次游标的下一个，直到末尾 if set.Empty() { // 没有新邮件，直接返回，别发空命令 return nil }

set.Empty()这个判断很有必要。空集合发出去的命令在部分服务端上会返回BAD，而在另一些上返回OK加零结果，行为不一致。加上判断之后，行为就由你控制了。

5. FETCH 要按需取，别上来就拉整封邮件

FETCH 的性能瓶颈几乎全部来自“一次要了太多东西”。我见过最夸张的一版代码，同步任务对每一封新邮件都FETCH BODY[]（整封原始邮件），一个 2000 封的邮箱首次同步跑了二十多分钟，中间还因为单条响应过大超时了两次。实际上大部分场景根本不需要整封正文。

5.1 FETCH 项要跟业务需求对齐

我把常见的 FETCH 项和它们的用途整理一下，方便按需勾选：

一个要点是关于PEEK：直接取BODY[]在很多服务端上会隐式把邮件标记为已读。这个副作用在做“后台同步”时几乎是灾难——用户打开客户端发现所有邮件都变已读了。库里的BODY.PEEK[]就是用来规避这个问题的，等价于“取内容但不改标记”。我在代码评审里会把不带PEEK的取正文直接打回。

set := new(imap.SeqSet) set.AddNum(uid) // 列表页只需要这些 items := []imap.FetchItem{ imap.FetchUid, imap.FetchFlags, imap.FetchEnvelope, imap.FetchRFC822Size, } msgs := make(chan *imap.Message, 8) done := make(chan error, 1) go func() { done <- c.UidFetch(set, items, msgs) }() for m := range msgs { env := m.Envelope log.Printf("uid=%d subject=%q from=%v size=%d", m.Uid, env.Subject, env.From, m.Size) } if err := <-done; err != nil { return err }

5.2 ENVELOPE 的字段比想象的更“原始”

ENVELOPE返回的是协议层的原始结构，跟界面上看到的字符串有差距，有三点必须处理。

第一，主题使用 RFC 2047 编码。中文主题在协议里长这样：=?UTF-8?B?5rWL6K+V6YKu5Lu2?=。库一般提供解码函数，但要注意：解码可能失败（服务端编码不规范、多段编码拼接错误），失败时不要丢掉整封邮件，降级成原始字符串更稳妥。

第二，地址列表里的Personal名字同样可能是编码的，而且Host和Mailbox是分开的两个字段，拼邮箱地址时要自己加@。发件人为空（退信、系统通知）时要能兜住，不能直接 panic。

第三，Envelope.Date是服务端按它自己的时区理解给出的时间，跟邮件头里的Date字段不一定完全一致。如果业务对时间敏感（比如按天归档），建议以原始头里的Date为准，用BODY.PEEK[HEADER.FIELDS (DATE)]单独取一次，成本很低。

5.3 BODYSTRUCTURE 用来判断附件，比解析整封邮件便宜得多

判断“这封邮件有没有附件”最省钱的办法是取BODYSTRUCTURE，它返回一棵 MIME 结构树，每个节点带类型、子类型、参数、大小。遍历这棵树，找到Content-Disposition: attachment或者文件名参数非空的节点，就知道有附件。相比拉整封邮件再解析，网络传输量能差一到两个数量级。

section := &imap.BodySectionName{Peek: true} items := []imap.FetchItem{imap.FetchUid, section.FetchItem()} msgs := make(chan *imap.Message, 4) go func() { done <- c.UidFetch(set, items, msgs) }() for m := range msgs { for _, literal := range m.Body { // literal 是 io.Literal / io.Reader，内容是整封原始邮件 // 交给 net/mail + mime/multipart 解析即可 _ = literal } }

解析原始邮件时，用标准库net/mail读头，用mime/multipart按boundary切分正文和附件，这个组合够用且没有额外依赖。需要注意的是嵌套的multipart/mixed里可能再嵌multipart/alternative（纯文本 + HTML 两版），递归时要设一个深度上限，否则遇到畸形邮件会栈溢出。

5.4 增量同步的游标设计

全量扫描的代价随时间线性增长，所以一定要做增量。我的做法是维护last_uid游标，每次只取UID > last_uid的邮件：

criteria := imap.NewSearchCriteria() criteria.Uid = new(imap.SeqSet) criteria.Uid.AddRange(lastUID+1, 0) uids, err := c.UidSearch(criteria) if err != nil { return err }

这里有个细节容易忽略：UidSearch返回的 UID 列表不保证有序（虽然实践中多数服务端是升序的），所以拿到之后要自己排一次序，再按批 FETCH。如果直接按返回顺序更新游标，万一中间有一个小的 UID 排在后面，游标会来回跳，导致重复拉取。

另一个细节是批量大小。UID 列表可能有上千个，一次 FETCH 全拉会让单条响应变得巨大，容易触发读超时。我会按 50 到 200 分片，具体值看单封邮件的元数据大小，分片之间可以做一点节流，避免被服务端判定为高频访问。这个阈值不是拍脑袋定的，我是按“单条响应控制在 1MB 以内、单批耗时控制在 5 秒以内”倒推出来的，实测下来 100 这个数在不同服务端上都比较稳。

6. 搜索、打标、移动：三个动作的实际边界

6.1 SEARCH 的中文关键词基本不可靠，要有备选方案

SEARCH是服务端执行的，这既是优点（不用把邮件全拉到本地）也是缺点（受服务端实现限制）。中文关键词搜索的坑在于字符集：协议原本要求非 ASCII 搜索必须声明CHARSET，但支持哪些字符集完全由服务端决定，有的只支持US-ASCII，有的支持UTF-8，有的声明支持但实际匹配不到。

我的实测结论是：中文关键词的服务端搜索只能当优化项，不能当功能依赖。可行的架构是：

1. 先用服务端能可靠执行的条件下推，比如时间范围、发件人地址、是否有附件、已读状态；
2. 把候选集的ENVELOPE与正文摘要拉到本地；
3. 在本地做中文分词与匹配。

这样既利用了服务端的能力，又保证结果正确。纯英文关键词的场景可以直接用服务端搜索，配合HEADER条件匹配主题或发件人，效率很高：

criteria := imap.NewSearchCriteria() criteria.Since = time.Now().AddDate(0, 0, -7) criteria.WithoutFlags = []string{imap.SeenFlag} criteria.Header = textproto.MIMEHeader{} criteria.Header.Set("Subject", "invoice") uids, err := c.UidSearch(criteria)

还有一个高频误用：把criteria.Header里的键名写成小写。协议里头字段名不区分大小写，但某些服务端实现（尤其是老版本）是大小写敏感的，写subject可能匹配不到。统一用规范写法（首字母大写）更保险。

6.2 批量打标要注意原子性与并发安全

标记已读、加星标这类操作走STORE。写法上要注意两点。一是FormatFlagsOp的第二个参数决定是“静默”还是“返回新标记”，批量操作时选静默（true）能显著减少响应体大小。二是STORE本身没有事务语义，一批 200 个 UID 里如果中间某个失败了，前面的已经生效。所以分片不要太大，失败时能明确知道是哪一批出了问题，重试时整批重做（AddFlags是幂等的，重复加同一个标记不会有副作用）。

set := new(imap.SeqSet) set.AddNum(uid) // 静默模式，不返回新标记 op := imap.FormatFlagsOp(imap.AddFlags, true) if err := c.UidStore(set, op, []interface{}{imap.SeenFlag}, nil); err != nil { return err }

并发安全这块有个必须强调的点：一个连接同一时刻只能执行一条命令。库内部一般用锁或串行化保证这一点，但这意味着你在多个 goroutine 里并发调用同一个 client 的方法，实际是排队执行的，不会更快。想要真并发就得多开连接，一人一个，别在一个连接上堆 goroutine。

6.3 MOVE 与 COPY+STORE+EXPUNGE 的效果差异

有MOVE扩展时，一次调用就能把邮件移动到目标目录，服务端保证原子性，返回的新 UID 也能拿到（如果同时支持UIDPLUS）。没有MOVE时的经典三步是：COPY到目标目录、STORE +Deleted打删除标记、EXPUNGE提交删除。

三步法有两个风险。第一，COPY成功但STORE失败会留下副本，产生重复邮件；第二，EXPUNGE会清掉当前邮箱里所有带删除标记的邮件，包括别的程序标记的、以及用户手动标记但还没提交的。第二个风险特别隐蔽，我在一个多系统共用一个邮箱的场景里遇到过：我们的归档任务执行EXPUNGE，把另一个系统标记待删除的邮件一并清掉了，对方以为是自己的 bug。

规避办法有两个：一是用UID EXPUNGE（需要UIDPLUS），只提交指定 UID 的删除；二是干脆不用EXPUNGE，只打Deleted标记，把真正的清理由用户或者运维侧决定。归档类业务我一般选第二种，宁可留着标记，也不冒险批量清空。

// 优先走 MOVE if hasCap(caps, "MOVE") { return c.UidMove(set, destMailbox) } // 降级：拷贝后打标，不做 EXPUNGE if err := c.UidCopy(set, destMailbox); err != nil { return err } op := imap.FormatFlagsOp(imap.AddFlags, true) return c.UidStore(set, op, []interface{}{imap.DeletedFlag}, nil)

7. IDLE 长连接：好用，但必须有兜底

轮询的问题不用多说，间隔长了延迟高，间隔短了浪费请求，而且很多服务端对短时间内的高频SELECT/NOOP有隐性限流。IDLE扩展就是为了解决这个：客户端告诉服务端“我在这儿等着，有变化叫我”，服务端在收到新邮件、标记变化时主动推送一个* n EXISTS或* n FETCH。

7.1 IDLE 是阻塞的，必须单独占一个连接

IDLE一旦进入，连接就进入“只能收不能发（除了 DONE）”的状态，其他命令都发不出去。所以架构上必须把它隔离：专门开一个连接做监听，收到变化通知后，通过内部 channel 通知工作协程去拉数据，工作协程用另外的连接执行实际命令。

idleConn, err := client.DialWithDialerTLS(dialer, addr, tlsCfg) if err != nil { return err } if err := idleConn.Login(user, pass); err != nil { return err } if _, err := idleConn.Select("INBOX", true); err != nil { // 只读，避免副作用 return err } for { idle, err := idleConn.Idle() if err != nil { // 连接不可用，走重连 break } if err := idle.Wait(); err != nil { // 等待期间出错，或服务端超时结束 IDLE idle.Close() break } // 收到变化通知：先退出 IDLE，把命令通道让出来 if err := idle.Close(); err != nil { break } // 通知工作协程去拉增量 select { case notifyCh <- struct{}{}: default: // 已有待处理通知，合并 } }

这里的关键是idle.Close()的时机。完整的处理顺序是：Wait返回 →Close退出 IDLE 状态 → 用同一个连接发UID SEARCH或FETCH拿具体变化 → 处理完再进下一次Idle。如果在 IDLE 状态下直接发别的命令，服务端会返回BAD。

7.2 心跳与重连退避

服务端对 IDLE 有超时限制，RFC 建议不少于 30 分钟，实际各家用得不一样，常见的会在 29 分钟左右主动结束 IDLE 并返回一个OK。如果客户端不重新进入 IDLE，连接就变成“半死”状态——TCP 还连着，但收不到任何推送，肉眼看不出来。

处理办法是给每次 IDLE 设一个自己的定时器，比如 24 分钟，到点就主动Close再重新进入。这样既不会撞上服务端超时，也能顺带验证连接可用性。同时，TCP 层的保活也要开，net.Dialer的KeepAlive设成 30 秒，能更快发现链路断掉。

重连要退避，不要死循环狂连。我的参数是：初始 1 秒，每次翻倍，上限 60 秒，加 ±20% 的随机抖动。加抖动是为了避免多实例同时重连把服务端打出一个瞬时峰值。连续失败超过一定次数（比如 20 次）就上报告警，让人介入，别让程序在后台无声地转圈。

7.3 多账号连接池的规模怎么估

一个账号需要几条连接？我的经验是：1 条 IDLE 监听 + 1 条同步任务用 + 1 条用户交互用。同步任务那条如果能保证串行，就不需要更多。真正的限制来自服务端，多数服务商对单账号的并发连接数有上限（10 到 15 条不等），超过会直接拒绝。

所以连接池不是越大越好，反而要做上限保护。实现上我会给每个账号维护一个信号量，取连接前先Acquire，用完Release，池里没有空闲连接就排队等待，等待超时（比如 30 秒）就返回错误让上游重试。这样即使上游代码写得再野，也不会把账号连接数打爆。

注意：连接是稀缺资源，不是无状态 HTTP 客户端。任何“用完即弃”的写法都会让握手和鉴权的开销变成主要成本。

8. 自己实现服务端：Backend 接口的几个关键点

服务端这块的入口是创建一个server，把自定义的Backend传进去。Backend是顶层接口，负责“根据用户名找到用户”；User接口负责“列出邮箱、创建邮箱、获取邮箱”；Mailbox接口负责“列消息、取消息、改标记、提交删除”。三个接口层层嵌套，实现顺序也建议按这个顺序来。

8.1 先用内存后端把链路跑通

不要一上来就接数据库。先看仓库里的内存后端示例，把它跑起来，用真实客户端连一遍，确认LOGIN、LIST、SELECT、FETCH都能通，再开始替换存储层。这一步能帮你排除掉大量“实现错误”和“协议问题”混杂的情况。

import ( "github.com/mxk/go-imap/backend/memory" "github.com/mxk/go-imap/server" ) be := memory.New() s := server.New(be) s.Addr = "127.0.0.1:1143" s.AllowInsecureAuth = true // 仅本地调试 log.Println("imap server listening on", s.Addr) if err := s.ListenAndServe(); err != nil { log.Fatal(err) }

内存后端跑通之后，你会对“客户端在什么时机调用哪个接口”有直观认识。比如客户端SELECT一个邮箱时，服务端会调用User.GetMailbox，然后调用Mailbox.ListMessages拿消息列表，还会取Mailbox.Info拿UIDVALIDITY、UIDNEXT这些状态。这些调用顺序在文档里不容易看明白，跑一遍日志就清楚了。

8.2 实现 Backend 时最容易错的三个地方

第一是UIDVALIDITY的稳定性。这个值必须在邮箱生命周期内保持不变，除非你确实重建了整个邮箱。实现时不能每次调用都返回当前时间戳——那样客户端每次连上来都会认为邮箱换代了，触发全量重同步。正确做法是把它存在邮箱的元数据里，创建时生成一次，之后一直读这个值。

第二是序列号的生成规则。序列号必须是 1 到 N 的连续整数，反映当前邮箱内的物理顺序，且在EXPUNGE之后要重新编号。这一点在实现自定义存储时特别容易搞错，因为你的存储可能是按 UID 排序的，但对外必须能按插入顺序给出 1..N。我的做法是在内存里维护一份“当前可见消息的有序 UID 列表”，序列号就是这个列表的下标加一，任何增删都重建这份列表。

第三是标记的语义。\Seen、\Flagged、\Deleted、\Answered、\Draft这五个是系统标记，客户端会依赖它们的行为。比如\Deleted只表示“待删除”，真正的删除发生在EXPUNGE。如果你的实现里STORE +Deleted直接就把消息删了，很多客户端会表现出“删了还能看到但点不开”的怪状态。

8.3 会话层的扩展点

server包允许你自定义Session，用来在连接建立、认证成功、命令执行前后插入钩子。实用的用法有三个：一是审计日志，记录谁在什么时候访问了哪个邮箱；二是限流，按连接或按用户统计命令数，超阈值就断开；三是后端选择，根据用户名路由到不同的存储实现（比如 VIP 用户走 SSD，普通用户走冷存储）。

限流这块要提醒一句：IMAP 客户端的行为差异很大，有的客户端连上来会立刻发十几条命令探测能力，阈值设太紧会把正常客户端误杀。我一般把阈值设在“每秒 20 条命令、每分钟 300 条”，先观察一段时间再收紧。

9. 联调排错：几个看起来笨但省时间的办法

9.1 把原始协议日志打出来

库一般提供SetDebug(w io.Writer)之类的开关，打开之后所有收发的原始行都会打出来（密码类字段可能被打码，因版本而异）。这个日志比任何猜测都有效。我遇到过的几个典型问题，全靠它定位：

• 客户端和服务端对同一条命令一个用UID FETCH、一个回FETCH响应，导致解析错位；
• 服务端返回的* OK里夹了非 ASCII 内容，没有做编码处理，把后续解析带偏；
• 某条命令返回NO [TRYCREATE]，实际意思是“目标邮箱不存在，先建一个”，而不是“权限不足”。

打开调试时注意两点：一是日志里可能包含邮件正文片段，生产环境要脱敏，别把用户邮件内容落到公共日志系统；二是调试输出会显著拖慢速度，只在排查期开，别一直开着。

9.2 用一个假服务端复现问题

排查客户端 bug 时，最痛苦的是“真实服务端行为不稳定、不可控”。这时候用库自带的服务端起一个内存实例，就能构造各种边界情况：只有一封邮件、有一万封邮件、邮箱里有畸形头、UIDVALIDITY中途变化。我在一个“拉取偶发超时”的问题上就是这么定位的——用假服务端把邮件数调到 5000，本地稳定复现，最后发现是分片太大导致单条响应超过了客户端的读缓冲。

同样的思路也能用来做回归测试。把“给定一段操作序列，客户端应该发出哪些命令”写成表驱动测试，跑在假服务端上，速度快、无外部依赖，CI 里跑得很舒服。

9.3 我实测下来觉得最值的几条经验

第一条，所有网络调用都要有超时。库的默认行为在某些版本里是无限等待的，一旦服务端不回，整个 goroutine 就挂在那儿。兜底做法是把每个连接包一层带SetDeadline的包装，或者在更高层用context加 goroutine 加select做超时控制。后者虽然丑，但通用。

第二条，不要在一个连接上做“先查后改”的复合逻辑。因为中间可能有变化，查到的结果在改的时候已经失效了。正确的做法是用 UID 定位，一次命令完成一个语义动作。

第三条，日志里一定要有 UID 和邮箱名。排查问题时，只看到“fetch failed”是没用的，得看到“fetch failed: mailbox=Archive/2024, uid=18342, uidvalidity=1700000000”，才能复现。

第四条，先跑通再优化，但别把错误处理留到最后补。库的错误返回值信息很丰富，很多响应里带[ALERT]、[TRYCREATE]、[AUTHENTICATIONFAILED]这类带括号的代码，能直接告诉你怎么修。一开始就把这些代码提取出来做分支处理，后期能省掉大量猜测。

第五条，中文相关的处理统一收口到一个包。文件夹名编码、主题解码、地址名解码、搜索字符集，这几件事散落在各个业务文件里，早晚会出现“这里解码了那里没解码”的不一致。我现在的做法是建一个mailtext小包，所有进出协议层的字符串都必须过它一遍，规则只有一处，改起来也方便。

第六条，定期做一次“冷启动演练”。把本地数据库清空、游标归零，让同步任务从头跑一遍，看看耗时、内存、失败率。这个演练能暴露很多“带状态才不出问题”的隐性 bug，比如依赖某个缓存目录、依赖上次留的临时文件。跑一次演练，比加十个监控项都管用。