简介：这份PDF面向软件工程、计算机相关专业学生及Java邮件开发初学者，围绕基于JavaMail的电子邮件系统课程设计展开，帮助读者理解邮件客户端与服务器端的整体设计思路。内容系统梳理了SMTP、POP3、IMAP三大邮件通信协议的工作机制，并讲解MIME标准对附件与多内容类型的支持，同时深入剖析JavaMail API中Session、Store、Folder、Message、Transport等核心类的职责与调用关系，覆盖客户端登录、邮件发送、接收下载、邮件夹管理等典型功能的实现要点。资源包为单一PDF文档，大小约1.97MB，内含完整课程设计报告与配套源文件说明，结构清晰，便于对照学习。目前已有415人学习下载，适合需要完成邮件系统课设、理解协议原理与API用法的读者参考，也可作为邮件过滤、搜索、通知及安全传输等扩展功能的设计思路来源。

1. 从一份 JavaMail 邮件系统设计文档说起：它到底能跑出什么

很多人第一次看到「基于 JavaMail 电子邮件系统的设计（含源文件）」这类标题，第一反应是——这不就是大学课设吗？发个邮件而已，Transport.send()一行代码的事。但真正把一套邮件系统从零搭起来，你会发现它远不止「发信」这么简单：SMTP 认证怎么配、附件怎么带、HTML 正文里嵌图片怎么处理、收信端用 POP3 还是 IMAP、中文乱码怎么根治、群发时怎么避免被对方服务器当成垃圾邮件拒收——每一个点都能让你卡上半天。这份设计文档加源文件的价值，恰恰在于它把「发信 + 收信 + 附件 + 会话管理」这条完整链路串了起来，而不是只给你一个孤零零的发送示例。

这篇文章面向的是手里已经拿到或准备复现这套 JavaMail 邮件系统的人：你可能是在做课程设计的学生，也可能是需要给内部系统加一个邮件通知模块的后端开发。我会按「环境怎么搭 → 核心类怎么用 → 收发信怎么落地 → 踩过哪些坑 → 怎么验证和进阶」的顺序，把 JavaMail 这套东西讲透。读完你应该能独立跑通一个支持发送纯文本、HTML、带附件邮件，并且能用 IMAP 收信解析的最小系统。下面先从依赖和会话配置开始。

2. JavaMail 环境搭建与 Session 会话配置：从 jar 包到可复用连接

2.1 依赖引入：javax.mail 与 jakarta.mail 的选择

JavaMail 的坐标在 Java EE 时代是javax.mail:javax.mail-api加具体实现com.sun.mail:javax.mail。从 Jakarta EE 9 开始，包名整体迁移到jakarta.mail，坐标变成com.sun.mail:jakarta.mail。如果你用的是 Spring Boot 2.x 且 JDK 8，直接上javax.mail最省事；如果是 Spring Boot 3.x 或 JDK 17+，必须用jakarta.mail，否则运行时会抛ClassNotFoundException。这是第一个容易翻车的地方——很多人复制了老教程的依赖，编译能过，一运行就炸。

Maven 里最简依赖如下，jakarta.mail这个 artifact 已经包含了 API 和 Sun 的实现，不需要再单独引 API 包：

<dependency> <groupId>com.sun.mail</groupId> <artifactId>jakarta.mail</artifactId> <version>2.0.1</version> </dependency>

如果你不用构建工具，直接下 jar 包放进WEB-INF/lib或 classpath 也行，但要确保jakarta.activation一起带上，否则处理附件时会报DataType相关的错。参数上，version选 2.0.x 系列即可，1.6.x 是javax时代的最后稳定版，两者不要混用。

2.2 Session 会话：认证、超时与调试开关

Session是 JavaMail 的核心入口，它保存了邮件服务器地址、端口、认证信息等全局配置。很多人图省事在每个发送方法里Session.getInstance()一次，结果连接池无法复用，高并发下性能很差。正确做法是把Session做成单例，或者交给 Spring 容器管理。

Properties props = new Properties(); // SMTP 服务器地址与端口，465 为 SSL，587 为 STARTTLS props.put("mail.smtp.host", "smtp.example.com"); props.put("mail.smtp.port", "465"); props.put("mail.smtp.auth", "true"); // 开启 SSL 加密 props.put("mail.smtp.ssl.enable", "true"); // 连接超时与读写超时，单位毫秒，避免网络抖动时线程卡死 props.put("mail.smtp.connectiontimeout", "5000"); props.put("mail.smtp.timeout", "5000"); props.put("mail.smtp.writetimeout", "5000"); // 调试开关，生产环境务必关掉，否则控制台会打印协议交互细节 props.put("mail.debug", "false"); Session session = Session.getInstance(props, new Authenticator() { @Override protected PasswordAuthentication getPasswordAuthentication() { return new PasswordAuthentication("user@example.com", "授权码"); } });

这里几个参数值得展开说。mail.smtp.ssl.enable和mail.smtp.starttls.enable是两回事：前者是全程 SSL（通常 465 端口），后者是先明文连接再升级为 TLS（通常 587 端口）。选错了会直接连接超时或握手失败。connectiontimeout、timeout、writetimeout这三个超时参数是血泪经验——不设的话，对方服务器不响应时你的线程会一直挂着，在 Web 应用里很快就把线程池耗光。认证密码那一栏，现在主流邮箱服务商都要求用「授权码」而不是登录密码，这个授权码在邮箱后台单独生成，和登录密码不是一回事，填错了会报AuthenticationFailedException。

提示：mail.debug设为 true 时能看到完整的 SMTP 对话，排查认证失败、被拒收时非常有用，但排查完记得关掉，它会打印 Base64 编码后的认证信息。

3. 邮件发送核心：MimeMessage 构造与三种正文形态

3.1 纯文本与 HTML 正文的构造差异

发送邮件的核心类是MimeMessage，它继承自Message。最简单的纯文本邮件只需要设置发件人、收件人、主题和内容四要素：

MimeMessage message = new MimeMessage(session); // 发件人，第二个参数是显示名称 message.setFrom(new InternetAddress("user@example.com", "系统通知")); // 收件人，TO 是直接收件人，CC 抄送，BCC 密送 message.setRecipient(Message.RecipientType.TO, new InternetAddress("target@example.com")); message.setSubject("账户激活通知", "UTF-8"); // 第二个参数指定 MIME 类型和字符集 message.setContent("<h3>您好</h3><p>请点击链接激活账户</p>", "text/html;charset=UTF-8"); Transport.send(message);

注意setSubject和setContent里的字符集参数。中文乱码问题十有八九出在这里：setSubject不传"UTF-8"时，默认用平台编码，在 Windows 上就是 GBK，收件人用 UTF-8 解码就成乱码。setContent的第二个参数必须写成"text/html;charset=UTF-8"这种完整形式，只写"text/html"同样会乱码。纯文本邮件把text/html换成text/plain即可。

3.2 带附件的复合邮件：MimeMultipart 的嵌套结构

带附件的邮件本质是一个MimeMultipart容器，里面装若干BodyPart：正文一个 part，每个附件一个 part。这里有个容易搞混的点——如果正文里还要嵌图片（比如邮件签名里的 logo），需要再套一层multipart/related。先看最常用的「正文 + 附件」结构：

// 创建混合容器，对应 multipart/mixed MimeMultipart multipart = new MimeMultipart("mixed"); // 正文部分 MimeBodyPart textPart = new MimeBodyPart(); textPart.setContent("请查收本月账单", "text/plain;charset=UTF-8"); multipart.addBodyPart(textPart); // 附件部分 MimeBodyPart attachPart = new MimeBodyPart(); FileDataSource source = new FileDataSource(new File("/data/bill.pdf")); attachPart.setDataHandler(new DataHandler(source)); // 用 MimeUtility.encodeText 处理中文文件名 attachPart.setFileName(MimeUtility.encodeText("月度账单.pdf", "UTF-8", null)); multipart.addBodyPart(attachPart); message.setContent(multipart); Transport.send(message);

MimeMultipart的构造参数决定了邮件的整体结构："mixed"用于正文加附件，"related"用于 HTML 正文内嵌资源，"alternative"用于纯文本和 HTML 双版本共存。附件文件名一定要用MimeUtility.encodeText编码，否则中文文件名在 Outlook 里会显示成一串=?UTF-8?B?...?=的乱码。FileDataSource直接读文件，大附件场景要注意内存占用，超过 10MB 的附件建议改用流式处理或直接走网盘链接。

3.3 收件人类型与批量发送的正确姿势

Message.RecipientType有三个值：TO、CC、BCC。群发时如果直接把几十个地址塞进TO，收件人能看到彼此的邮箱，既不礼貌也可能泄露隐私。正确做法是把真实收件人放BCC，TO填自己的地址或一个占位地址。另外，setRecipients方法接受数组，比循环调用setRecipient效率高：

InternetAddress[] toList = InternetAddress.parse("a@x.com,b@x.com"); message.setRecipients(Message.RecipientType.BCC, toList);

需要提醒的是，即便用了BCC，短时间内向同一服务器投递大量邮件仍可能触发限流。生产环境做批量通知时，常见做法是接入专业的邮件推送服务，或者自己控制发送速率、加队列削峰。JavaMail 本身不提供队列能力，这部分要自己在业务层实现。

4. 收信与解析：用 IMAP 拉取邮件并提取正文附件

4.1 POP3 与 IMAP 的选型对比

收信协议主要有两个：POP3 和 IMAP。POP3 把邮件下载到本地后通常从服务器删除，适合单设备、只读一次的场景；IMAP 在服务器上保留邮件并支持文件夹、已读状态同步，适合多设备。做邮件系统设计时，如果只是「拉取验证码」这类一次性需求，POP3 足够；如果要做一个完整的邮件客户端或需要同步已读状态，必须用 IMAP。下面这张表是选型时的关键差异：

4.2 用 IMAP 拉取并解析邮件内容

收信的核心类是Store和Folder。连接、打开收件箱、遍历Message，再根据内容类型递归解析。下面这段代码演示了拉取最新一封邮件并提取纯文本正文：

Properties props = new Properties(); props.put("mail.store.protocol", "imap"); props.put("mail.imap.ssl.enable", "true"); props.put("mail.imap.host", "imap.example.com"); props.put("mail.imap.port", "993"); Session session = Session.getInstance(props); try (Store store = session.getStore("imap")) { store.connect("user@example.com", "授权码"); // 只读方式打开收件箱，避免误改已读状态 try (Folder folder = store.getFolder("INBOX")) { folder.open(Folder.READ_ONLY); Message[] messages = folder.getMessages(); if (messages.length == 0) return; // 取最新一封 Message latest = messages[messages.length - 1]; System.out.println("主题：" + latest.getSubject()); // 递归解析内容 Object content = latest.getContent(); if (content instanceof String) { System.out.println("正文：" + content); } else if (content instanceof Multipart) { Multipart mp = (Multipart) content; for (int i = 0; i < mp.getCount(); i++) { BodyPart part = mp.getBodyPart(i); if (part.isMimeType("text/plain")) { System.out.println("正文：" + part.getContent()); } else if (Part.ATTACHMENT.equalsIgnoreCase(part.getDisposition())) { // 附件保存到本地 try (InputStream is = part.getInputStream()) { Files.copy(is, Paths.get("/data/recv/" + MimeUtility.decodeText(part.getFileName()))); } } } } } }

这段代码有几个关键点。folder.open(Folder.READ_ONLY)用只读模式打开，避免拉取时把未读邮件标记成已读，这在做监控或归档时很重要。getContent()返回的类型是不确定的：纯文本邮件返回String，复合邮件返回Multipart，所以必须做类型判断再递归。附件判断用Part.ATTACHMENT.equalsIgnoreCase(part.getDisposition())，注意getDisposition()可能返回 null，直接调equals会空指针，所以要把常量放前面。附件文件名同样要MimeUtility.decodeText解码，否则中文名是乱码。

4.3 大附件与部分下载优化

IMAP 协议支持FetchProfile，可以只拉取邮件头而不下载整个正文和附件，这在邮件量大时能显著提速：

FetchProfile profile = new FetchProfile(); profile.add(FetchProfile.Item.ENVELOPE); profile.add(FetchProfile.Item.FLAGS); folder.fetch(messages, profile);

先 fetch 信封信息（发件人、主题、日期），用户点开某封时再按需拉取正文。如果只想要正文不想要附件，可以在解析时跳过Part.ATTACHMENT类型，或者用part.getInputStream()时限制读取字节数。这些优化在邮件系统设计里属于进阶内容，但一旦邮件量上来，不做的话内存和带宽都会吃不消。

5. 避坑与排查：JavaMail 落地时最容易翻车的五个点

5.1 认证失败：AuthenticationFailedException

现象：连接能建立，但一认证就抛AuthenticationFailedException: 535 Error: authentication failed。原因通常有三个：一是用了登录密码而不是授权码，现在主流邮箱服务商都要求授权码；二是账号没开启 SMTP/IMAP 服务，需要在邮箱设置里手动打开；三是mail.smtp.auth没设为 true，或者Authenticator返回的密码为空。解决顺序是：先确认服务已开启，再用授权码替换密码，最后检查props里auth参数。如果还不行，把mail.debug打开看服务器返回的具体错误码，535 是认证失败，550 是发件人被拒。

5.2 中文乱码：主题、正文、附件名三处都要管

现象：收件人看到的主题是乱码，或者正文正常但附件名是=?UTF-8?B?...?=。原因是编码设置不完整。主题要用setSubject(subject, "UTF-8")，正文的 content type 要写全"text/html;charset=UTF-8"，附件名要MimeUtility.encodeText(name, "UTF-8", null)。三处缺一处都会乱码。另外，读取邮件时也要对应解码，MimeUtility.decodeText用于文件名，正文的getContent()一般会自动按声明的字符集解码，但如果发件方声明有误，可能需要手动用new String(content.getBytes("ISO-8859-1"), "UTF-8")转一次，这是老邮件系统常见的兼容处理。

5.3 连接超时：线程卡死与超时参数缺失

现象：程序运行一段时间后线程池耗尽，日志里大量线程停在SocketInputStream.read。原因是没设connectiontimeout、timeout、writetimeout，对方服务器不响应时连接一直挂着。解决是在Properties里把这三个超时都设上，建议 5000 到 10000 毫秒。另外，Transport.send()内部会自己建立和关闭连接，如果频繁发送，建议改用Transport对象复用连接，或者用连接池。注意Transport不是线程安全的，多线程共享时要加锁或每个线程独立创建。

5.4 被判定为垃圾邮件：内容与频率双重因素

现象：邮件发出去了，但对方收件箱里找不到，垃圾箱里也没有，或者直接进垃圾箱。原因分两类：内容层面，主题含敏感词、正文全是图片、HTML 里带大量外链，都会提高垃圾评分；频率层面，短时间大量发送、收件人频繁退信，会导致发件 IP 或域名被拉黑。解决上，内容尽量保持文本和 HTML 双版本、控制图片比例、避免夸张营销词；频率上做队列限速，监控退信率。如果自建邮件服务器，还要配 SPF、DKIM、DMARC 记录，这部分超出 JavaMail 本身，但做邮件系统绕不开。

5.5 附件过大：内存溢出与服务器拒收

现象：发送 20MB 以上附件时抛OutOfMemoryError，或者服务器返回552 Message size exceeds fixed maximum message size。原因是FileDataSource会把整个文件读进内存，且多数邮件服务器对单封邮件大小有限制（常见 25MB 或 50MB）。解决上，大文件不要走邮件附件，改成发下载链接；如果必须发，用流式BodyPart并控制并发。另外，附件经过 Base64 编码后体积会膨胀约 33%，所以 20MB 的文件实际传输量接近 27MB，算大小的时候要把这个系数考虑进去。

6. 验证与进阶：怎么确认系统真的可靠

跑通发送和接收只是第一步，要确认这套 JavaMail 邮件系统真的可靠，得有一套验证方法。我一般会分三层验证：单元层、集成层、压力层。

单元层用 GreenMail 这类嵌入式邮件服务器，它能在本地起一个 SMTP/IMAP 服务，不依赖外部邮箱，测试用例里直接断言收到的邮件内容。这样 CI 环境也能跑，不担心网络和授权码问题。集成层用真实邮箱服务商，发一封到自己的测试邮箱，人工确认主题、正文、附件、中文显示都正常。压力层则用队列灌入 1000 封邮件，观察发送耗时、失败率、内存占用，找出瓶颈。

进阶用法上，有几个方向值得投入。一是把Session和Transport做成 Spring Bean，配合@Async做异步发送，避免阻塞主业务线程。二是引入模板引擎（如 Thymeleaf、Freemarker）生成 HTML 正文，把邮件内容和代码分离，改文案不用重新编译。三是做发送日志和重试机制，记录每封邮件的状态，失败的进重试队列，这对通知类系统是刚需。四是收信端做增量拉取，用UIDFolder记录上次拉取的最大 UID，下次只拉新邮件，避免每次全量遍历。

下面是一个用UIDFolder做增量拉取的片段，思路是记录上次处理的最大 UID，下次只取比它大的：

UIDFolder uidFolder = (UIDFolder) folder; UID[] uids = uidFolder.getUIDs(messages[0], messages[messages.length - 1]); long lastUid = readLastUidFromDb(); // 从数据库或文件读取 for (int i = 0; i < uids.length; i++) { if (uids[i].uid > lastUid) { Message msg = uidFolder.getMessageByUID(uids[i].uid); // 处理新邮件 process(msg); lastUid = uids[i].uid; } } saveLastUidToDb(lastUid); // 处理完持久化

这个模式在邮件量大的场景下能把每次拉取的耗时从几十秒降到几百毫秒。我自己的习惯是，任何涉及外部服务的模块，上线前一定要把超时、重试、日志三件套配齐，JavaMail 尤其如此——它的异常信息有时候很含糊，没有足够的日志根本定位不到问题。另外，授权码这类敏感信息不要硬编码在代码里，走配置中心或环境变量，这是安全底线。

希望帮到你。

本文还有配套的精品资源，点击获取