IMAP 诊断工具（imapdiag）

排查「账号添加成功但收不到邮件」「IDLE 反复报错」「某个邮箱死活同步不了」这类问题时，第一步应该是用数据说话，而不是猜。

imapdiag 是一个独立的命令行工具，它绕过应用层直接连上 IMAP 服务器，把协议交互和关键计数打出来。一次运行就能区分：是服务器真的没邮件、是协议兼容问题、还是应用层过滤导致的。

它不会被打进发布产物

scripts/build.sh 用的是 go build -o <输出> .，只构建根包，server/cmd/ 下的工具不参与打包，可以长期留在仓库里。

快速开始

在 server 目录下执行（不需要先构建，不需要装包）：

go run ./cmd/imapdiag -host imap.189.cn -user you@189.cn -pass '你的密码或授权码'

密码含 $ ) * 等特殊字符时，务必用单引号包裹。

参数

参数	默认值	说明
-host	imap.189.cn	IMAP 服务器主机名
-port	993	IMAP 端口（SSL 通常 993）
-user	必填	登录用户名，通常为完整邮箱地址
-pass	必填	登录密码或授权码
-mailbox	INBOX	要诊断的目录名，LIST 出来名字不对时可换
-all	false	扫描 LIST 出的所有目录并逐个统计邮件数
-no-id	false	跳过 IMAP ID 命令，用于对比 ID 是否影响 SELECT 结果
-raw	true	打印原始 IMAP 协议交互（登录行自动脱敏）

输出较长时建议先关掉 -raw：

go run ./cmd/imapdiag -host imap.189.cn -user you@189.cn -pass 'xxx' -raw=false

输出解读

工具按 8 步输出，每一步都在回答一个具体问题：

步骤	命令	回答的问题
1	TCP + TLS	网络与 TLS 是否通、服务器声明了哪些能力
2	ID (RFC 2971)	服务器自述身份（可识别 Coremail 等具体实现）
3	LOGIN	凭据是否正确、是否支持 IDLE
4	LIST "" *	有哪些目录、邮件是否落在别的文件夹
4b	STATUS（-all）	每个目录各有多少封
5	STATUS	不进入已选状态的独立计数
6	SELECT	EXISTS、UIDNEXT、Flags
7	UID SEARCH ALL	第三条独立计数路径
8	FETCH	前 3 封信封（验证真的能读到内容）

最后输出三条计数的对比结论。

三个典型场景

场景一：收件箱为空

关键看三条独立路径是否一致：STATUS 计数、SELECT 的 EXISTS、UID SEARCH ALL。

• 三条都是 0，且 -all 扫描所有目录也都是 0 → 服务器侧确实没有邮件，应用层没问题。 注意看 UIDNEXT：若各目录都是 1，说明从未有邮件投递进来过。
• 三条都是 0，但 -all 发现别的目录有邮件 → 邮件不在你假设的目录里，用 -mailbox 指定正确的目录名。
• STATUS/SEARCH 有数，但 SELECT 读到 0 → 协议解析或 SELECT 兼容性问题，需针对性适配。

小心服务商的历史邮件限制

部分运营商邮箱（如天翼 189.cn）只向 IMAP/POP3 投递「开通服务之后」新到达的邮件，历史邮件仅在网页端可见。

判据：发一封测试邮件后立刻复查，若新邮件能读到、且其 UID 远大于 1（说明服务器上存在过更早的 UID 却不暴露），即可确认是这种限制。客户端在协议层无解，参见已知问题。

场景二：IDLE 反复报错

第 3 步会直接给出答案：

IDLE 能力: ❌ 未声明（应用应直接走轮询）

应用侧就是靠认证后的 CAPABILITY 探测来判定的（RFC 2177 要求支持 IDLE 的服务器必须声明）。服务器没声明就不该尝试 IDLE，参见已知问题中的 IDLE 条目。

场景三：邮件落在别的目录

加 -all，输出会给有邮件的目录打上 ⭐ 标记，并给出所有目录的合计：

⭐ "INBOX"     MESSAGES=12   UNSEEN=3    UIDNEXT=116   UIDVALIDITY=1
   "我的账单"   MESSAGES=0    UNSEEN=0    UIDNEXT=1     UIDVALIDITY=102
   ---- 所有目录合计: 12 封 ----

注意事项

• 凭据安全：-raw 会把登录行脱敏后再打印，但密码仍会出现在 shell 历史里，用完建议轮换。
• 网络要求：工具从你当前的机器直连 IMAP 服务器，若服务器需要代理才能访问，请在网络可达的环境运行。
• 只读操作：工具只执行 LIST / STATUS / SELECT / SEARCH / FETCH，不会修改、删除邮件或改变已读状态。
• 不会污染应用数据：它独立连接服务器，不读写应用的数据库。

相关文档

• 已知问题
• 特殊邮箱
• 添加 IMAP 功能