在IMAP协议里，邮件客户端操作邮件时面临一个核心问题：服务器返回的消息序列号不是稳定标识。用户一旦删除邮件或收到新邮件，同一封邮件的序列号就可能改变。Net::IMAP为此提供了一套基于UID的方法，其中uid_store和uid_copy是处理邮件状态与迁移的关键。UID是邮箱文件夹内相对稳定的唯一标识，只要文件夹的UIDVALIDITY不变，UID就不会因为其他邮件的增删而漂移。
UID与消息序列号：为什么必须用UID操作
初次接触Net::IMAP的人常会把消息序列号和UID混为一谈。消息序列号是一个从1开始的整数，表示邮件在当前邮箱中的位置。比如收件箱里有10封邮件，第一封序号是1，最后一封是10。但删除第1封邮件后，原来第2封会变成新的1号。如果客户端正在根据序号执行标记已读操作，就可能改错对象。UID则不同，它在同一文件夹内由服务器保证唯一，并且只要文件夹的UIDVALIDITY属性没有变化，UID就不会因为其他邮件的增删而改变。
实际开发中，稳定标识对邮件同步非常重要。假设客户端本地缓存了一封邮件的UID为2048，期间收件箱又收到了三封新邮件，序列号可能已经改变，但UID仍然是2048。此时用uid_store去修改这封邮件的标志就不会出错。获取UID的方法通常是通过uid_search或uid_fetch。下面先建立一个基本连接并搜索未读邮件的UID：
require 'net/imap'
imap = Net::IMAP.new('imap.ipipp.com', 993, true)
imap.login('user@ipipp.com', 'password')
imap.select('INBOX')
uids = imap.uid_search(['UNSEEN'])
puts "未读邮件UID列表: #{uids.inspect}"
上面的代码中uid_search返回的是UID数组，而不是消息序列号。之后调用uid_store、uid_copy或uid_fetch时都应当传入这些UID。需要特别注意的是，如果文件夹被服务器重建，UIDVALIDITY会发生变化，本地缓存的UID就失效了。可以通过imap.responses['UIDVALIDITY']或选择文件夹后查看imap.responses来获取该值，并在检测到变化时重新同步UID。
Net::IMAP中除了UID方法，还有对应的非UID方法，比如store、copy、fetch和search。它们接收的是消息序列号。除非你只在一次性脚本中处理简单任务，否则应优先使用UID版本。序列号只在极短的会话内可靠，而邮件客户端往往需要跨会话维护状态，这时候UID几乎是唯一正确的选择。
uid_store方法详解：精准修改邮件标志
uid_store的作用是对一个或多个UID对应的邮件执行标志修改操作。它的方法签名可以理解为uid_store(set, attr, flags)，其中set是UID、UID数组或Range，attr是操作类型字符串，flags是标志数组。最常用的操作类型有三种：FLAGS表示用给定标志替换邮件原有的所有标志，+FLAGS表示在现有标志基础上追加，-FLAGS表示从现有标志中移除。此外还支持+FLAGS.SILENT和-FLAGS.SILENT，带SILENT后缀的操作不会返回更新后的标志列表，可以节省带宽。
邮件标志通常使用Symbol表示，比如:Seen代表已读、:Flagged代表星标、:Answered代表已回复、:Deleted代表已标记删除。如果使用字符串形式，需要写成\Seen这样的IMAP标准写法。下面演示如何把指定UID的邮件标记为已读并添加星标：
# 假设已通过uid_search拿到UID target_uids = [101, 102, 103] # 追加已读和星标标志 imap.uid_store(target_uids, '+FLAGS', [:Seen, :Flagged]) # 移除星标，保留其他标志 imap.uid_store(101, '-FLAGS', [:Flagged]) # 直接用FLAGS替换，会清掉邮件上原有的其他标志 imap.uid_store(102, 'FLAGS', [:Seen])
很多人误以为设置了:Deleted标志邮件就立刻消失了，实际上它只是给邮件打上删除标记，还需要调用expunge才能真正从文件夹中移除。如果希望撤回删除操作，可以在expunge之前使用-FLAGS移除:Deleted标志。例如：
# 先标记为删除 imap.uid_store(2048, '+FLAGS', [:Deleted]) # 如果改主意了，在expunge之前撤回 imap.uid_store(2048, '-FLAGS', [:Deleted]) # 确认删除，执行expunge imap.expunge
uid_store的返回值在非SILENT模式下是一个Net::IMAP::FetchData数组，包含邮件序号、UID以及更新后的标志。不过多数场景只需要确认操作没有抛出异常即可。对批量UID执行操作时，Net::IMAP会构造一条包含多个UID的IMAP命令，这比循环逐个调用高效得多。如果UID不存在，服务器通常会返回错误，Net::IMAP会抛出Net::IMAP::NoRespError，因此最好用begin rescue包裹关键操作。
uid_copy方法：把邮件复制到其他文件夹
uid_copy用于将指定UID的邮件复制到目标邮箱文件夹。它的参数形式为uid_copy(set, mailbox)，其中set同样可以是UID、数组或Range，mailbox是目标文件夹名字符串。复制不会影响原邮件，目标文件夹中会生成一份新的邮件副本。如果目标文件夹不存在，IMAP服务器会返回错误，因此通常需要先创建目标文件夹，可以用imap.create完成。
下面演示一个常见场景：把收件箱中所有带星标的邮件复制到Archive文件夹。代码先搜索带:Flagged标志的UID，然后一次性复制过去：
# 确保Archive文件夹存在
begin
imap.create('Archive')
rescue Net::IMAP::NoRespError
# 文件夹已存在则忽略
end
# 搜索带星标的邮件UID
flagged_uids = imap.uid_search(['FLAGGED'])
# 一次性复制到Archive
imap.uid_copy(flagged_uids, 'Archive') unless flagged_uids.empty?
复制后的邮件在目标文件夹中会获得新的UID，原文件夹中的UID保持不变。如果服务器支持UIDPLUS扩展，复制完成后可以通过响应的COPYUID信息获取新UID。在Net::IMAP中，这些扩展信息位于imap.responses里，键通常为COPYUID。解析响应可以建立原UID与新UID的映射，这对邮件同步工具很有价值。没有UIDPLUS时，需要重新在目标文件夹中搜索条件来定位新邮件。
与uid_store类似，uid_copy同样支持批量操作。需要注意，IMAP协议并不保证复制会保留原邮件所有标志。大多数服务器会保留内部日期和部分标志，但自定义关键字是否保留取决于服务器实现。如果希望目标文件夹中的副本具备特定状态，可以在复制完成后对新UID再次调用uid_store。
组合使用：实现一个自动归档脚本
实际项目中，uid_store和uid_copy经常组合在一起完成归档、同步或移动逻辑。IMAP本身没有原生的移动命令，移动通常等于先复制到目标文件夹，再给原邮件打上:Deleted标志，最后执行expunge。下面给出一个自动归档未读邮件的完整示例，它将未读邮件复制到Archive，并标记原邮件为已读和已删除：
require 'net/imap'
imap = Net::IMAP.new('imap.ipipp.com', 993, true)
imap.login('user@ipipp.com', 'password')
imap.select('INBOX')
begin
imap.create('Archive')
rescue Net::IMAP::NoRespError
# 已存在则忽略
end
unseen_uids = imap.uid_search(['UNSEEN'])
puts "发现 #{unseen_uids.size} 封未读邮件"
unless unseen_uids.empty?
# 1. 复制到Archive
imap.uid_copy(unseen_uids, 'Archive')
# 2. 原邮件标记已读并打上删除标记
imap.uid_store(unseen_uids, '+FLAGS', [:Seen, :Deleted])
# 3. 真正删除
imap.expunge
end
imap.logout
imap.disconnect
这个脚本完成了一次简单的未读邮件迁移。复制操作可以保证Archive中保留未读状态的副本，之后原邮件被清理。需要注意的是，expunge执行后，被删除邮件对应的UID将不再有效，任何后续针对这些UID的操作都会失败。因此在设计同步流程时，应把uid_copy和uid_store的顺序安排好，先获取数据并完成复制，再执行删除。
错误处理也是组合使用时不可忽视的部分。网络中断、登录凭证失效、目标文件夹权限不足等情况都可能导致异常。建议将begin rescue Net::IMAP::Error => e包住整个会话，记录错误并保证连接正常关闭。此外，如果批量UID数量非常大，单条IMAP命令可能超出服务器限制，可以按固定大小分批执行，比如每批200个UID。分批处理能提高稳定性，也方便断点重试。
UIDVALIDITY变化是另一个需要处理的边界情况。可以在选择文件夹后读取imap.responses['UIDVALIDITY']，与本地缓存比较。如果不同，说明服务器重建了文件夹，必须丢弃本地UID并重新执行完整同步。忽略这一点会导致错误的邮件被修改或复制，影响数据完整性。综合运用UID搜索、批量uid_store、uid_copy以及UIDVALIDITY校验，可以构建出可靠且高效的Ruby邮件处理逻辑。
