在邮件自动化处理场景中，Ruby标准库自带的Net::IMAP一直是轻量级方案的首选。它能直接连接IMAP服务器，完成登录、选择文件夹、搜索邮件、读取内容、移动或删除等一整套操作。其中uid_search方法是搜索环节的核心，它支持将多个搜索关键字组合起来，构建出相当复杂的查询逻辑。本文围绕uid_search的用法展开，从基本概念讲到组合条件，再给出完整的实战代码。
uid_search与search的区别：为什么优先用UID
Net::IMAP提供了两个搜索方法：search和uid_search。两者接收的参数完全一致，区别在于返回的结果。search返回的是邮件序列号（sequence number），而uid_search返回的是UID（Unique Identifier）。序列号是邮件在当前邮箱中的临时编号，一旦有邮件被删除或新邮件到达，编号就会重新排列；UID则是服务器为每封邮件分配的相对稳定的标识，在同一文件夹内不会轻易变化。
举个实际的例子：你在处理一批邮件时，中途执行了删除操作，如果用的是序列号，后续再按旧编号取邮件就很可能取错，甚至越界报错。而UID在整个处理过程中保持不变，可以安全地在多个请求之间传递。因此凡是涉及分批处理、断点续传、多步骤操作的脚本，都应当使用UID。
与UID配套的还有uid_fetch、uid_copy、uid_move、uid_store等方法，它们共同构成一套以UID为准的操作体系，建议在项目中统一使用，避免混用导致编号错位。
常用搜索关键字详解
uid_search的第一个参数通常是字符集（如"UTF-8"），其后跟一个或多个搜索关键字。单个关键字可以直接传符号，多个关键字则放到数组中，表示“与”的关系。下面先看最常用的几类。
第一类是状态类：ALL匹配所有邮件，UNSEEN匹配未读邮件，SEEN匹配已读邮件，ANSWERED匹配已回复的邮件，DELETED匹配打了删除标记的邮件。这类条件通常用作基础过滤器，比如只处理未读邮件时用UNSEEN就能过滤掉历史邮件。
第二类是头部字段类：FROM、TO、SUBJECT、CC等，需要跟一个字符串参数。服务器会对这些字段做子串匹配，例如["SUBJECT", "账单"]会匹配主题中包含“账单”二字的所有邮件。注意匹配通常不区分大小写，但具体行为取决于服务器实现，跨服务器部署的脚本最好自己再做一次二次过滤。
第三类是时间类：SINCE、BEFORE、ON接收Date对象，分别表示某日期之后、之前、当天（这里比较的是邮件的内部日期，即到达服务器的时间，而非邮件头里的Date字段）。还有SENTSINCE、SENTBEFORE，比较的才是邮件头部的发送时间。这两组很容易混淆，做定时增量拉取时如果发现结果对不上，多半是搞混了这两类日期。
第四类是大小类：LARGER匹配体积大于指定字节数的邮件，SMALLER相反，常用于过滤掉超大附件邮件或纯文本小邮件。
基本用法示例如下：
require 'net/imap'
imap = Net::IMAP.new('imap.ippipp.com', ssl: true)
imap.login('user@ipipp.com', 'password')
imap.select('INBOX')
# 查找所有未读邮件
uids = imap.uid_search(['UNSEEN'])
puts uids.inspect
# 查找某发件人近一周的邮件
uids = imap.uid_search(['FROM', 'boss@ipipp.com', 'SINCE', Date.today - 7])
puts uids.inspect
# 查找主题包含"发票"且大于10KB的邮件
uids = imap.search(['SUBJECT', '发票', 'LARGER', 10240])
puts uids.inspect
imap.logout
imap.disconnect
组合条件与NOT排除：构建复杂查询
当多个关键字放在同一个数组中时，它们是“与”的关系，即邮件必须同时满足所有条件才会被返回。如果需要“或”的关系，就要用到OR关键字。OR接收两个子条件，例如要查找来自A或来自B的邮件，写法是['OR', ['FROM', 'a@ipipp.com'], ['FROM', 'b@ipipp.com']]。OR还可以嵌套，实现三个及以上条件的“或”逻辑：先OR前两个，再把结果与第三个条件OR。
排除某些邮件则用NOT，它修饰紧跟其后的一个条件。比如查找所有未读、但主题不含“广告”的邮件：
# 未读 且 主题不含"广告"
uids = imap.uid_search(['UNSEEN', 'NOT', ['SUBJECT', '广告']])
# 来自 a 或 来自 b，且是今天的邮件
uids = imap.uid_search([
['OR', ['FROM', 'a@ipipp.com'], ['FROM', 'b@ipipp.com']],
'SINCE', Date.today
])
# 嵌套OR：来自 a、b、c 任意一方的未读邮件
uids = imap.uid_search([
'UNSEEN',
['OR', ['FROM', 'a@ipipp.com'],
['OR', ['FROM', 'b@ipipp.com'], ['FROM', 'c@ipipp.com']]]
])
需要注意，条件嵌套过深时，不同服务器的解析能力参差不齐。Gmail、腾讯企业邮等服务对复杂嵌套支持较好，而一些老旧的邮局软件可能会直接返回错误或空结果。稳妥的做法是把复杂条件拆成多次简单查询，在Ruby侧用集合运算（数组的&和|）合并结果，兼容性会好得多。
搜索结果处理：结合uid_fetch批量拉取邮件
拿到UID列表后，下一步通常是拉取邮件内容。直接对每个UID调用uid_fetch效率很低，正确做法是把UID数组一次性传给uid_fetch，并只请求需要的字段。用逗号拼接UID可以减少请求次数，用ENVELOPE可以先拿摘要再按需取正文。
uids = imap.uid_search(['UNSEEN', 'SINCE', Date.today - 3])
unless uids.empty?
# 一次性取回所有邮件的信封信息（发件人、主题、日期）
imap.uid_fetch(uids, ['ENVELOPE']).each do |data|
env = data.attr['ENVELOPE']
from = env.from.first
puts "#{from.mailbox}@#{from.host} -> #{env.subject}"
end
# 逐封拉取正文（需要时可再请求RFC822或BODY[TEXT]）
uids.each_slice(50) do |slice|
imap.uid_fetch(slice.join(','), 'RFC822').each do |data|
mail = Mail.read_from_string(data.attr['RFC822'])
puts mail.subject
end
end
end
上面的代码用到了mailgem来解析原始邮件，它对中文编码、附件提取的处理比手工解析MIME省心得多。另外记得用each_slice分批请求，一次拉取几千封邮件的完整内容容易触发服务器限流甚至断开连接。
最后还有一个容易踩的坑：如果搜索条件中包含非ASCII字符（比如中文主题），第一个字符集参数一定要传"UTF-8"，即写成uid_search('UTF-8', ['SUBJECT', '账单'])。不传字符集时部分服务器会按US-ASCII处理，直接返回错误或搜不出结果。此外，中文搜索的匹配效果依赖服务器对字符集的支持程度，Gmail支持得较好，一些自建邮局可能只匹配英文，遇到这种情况可以先按发件人或日期粗筛，拉回本地后再用Ruby对主题做精确匹配，两步走往往是最可靠的方案。
RubyNet::IMAPuid_search修改时间：2026-09-12 15:16:43