简介：面向Java开发者与企业级应用场景，这份资源提供了一套通过JavaMail发送文本内容并携带附件的完整程序示例，可帮助解决SMTP配置、身份认证及附件封装等常见问题，适合集成邮件通知、报表推送等功能时参考。rar压缩包共含41个文件，大小约1.33MB，覆盖java源码、class编译文件、jar依赖库、xml配置以及日志等类型，目录包含Eclipse工程配置与WebContent页面，整体为一套可直接导入运行的项目。已有816人浏览学习。除核心发送逻辑外，源代码中体现了Session初始化、Message构建、Multipart附件组装、Transport发送以及调试模式的完整写法，并附带项目配置文件与运行日志，便于对照排查认证失败、网络异常等实际问题，可显著节省二次开发时间。
1. Java 发送邮件这件事：从一套 API 到能跑的源码包
很多开发者第一次接触“Java发送邮件”是在做用户注册通知、报表推送、订单回执这类功能时，发现自己对着教程写了两小时，邮件不是进垃圾箱，就是认证失败，甚至中文附件名直接变乱码。Java 发送邮件说白了就是靠 JavaMail API 把文本、HTML、图片和附件拼成一个 MimeMessage，再通过 SMTP 协议交给邮箱服务器。这份资源解决的不只是“能发出去”，而是把纯文本、富文本、附件三大场景全部封装成可直接复用的工具类，参数和踩坑点都在代码里标清楚了。适合刚接手企业后台开发、需要临时维护邮件模块的从业者，也适合需要给课程设计快速加一个邮件通知功能的学生。
2. JavaMail API 工作原理：会话、消息与传输协议选型
2.1 核心对象关系：Session、Message、Transport 各管什么
JavaMail 看起来复杂，实际只有三个核心对象需要真正理解。Session 是邮件的运行环境，它持有 SMTP 服务器地址、端口、认证方式等配置；Message 描述邮件本身，包括发件人、收件人、主题、正文和附件；Transport 负责把 Message 送到服务器。三者之间的关系是：Session 创建 Transport，Transport 利用 Session 里配置的认证信息建立连接，再调用 send 方法把 Message 发出去。
// 创建 Session 的常见方式 Properties props = new Properties(); props.put("mail.smtp.host", "smtp.example.com"); props.put("mail.smtp.port", "587"); props.put("mail.smtp.auth", "true"); props.put("mail.smtp.starttls.enable", "true"); Session session = Session.getInstance(props, new Authenticator() { @Override protected PasswordAuthentication getPasswordAuthentication() { return new PasswordAuthentication("user@example.com", "password"); } });这一段配置里，mail.smtp.host 是发送服务器地址，端口 587 配合 starttls.enable 是当前最通用的加密方式。mail.smtp.auth 必须开启，否则会被服务器拒绝。Session.getInstance 的第二个参数是 Authenticator，用来在需要认证时回调返回账号密码。有人会把账号密码写在 props 里用 props.put("mail.smtp.user", ...)，这种做法不是标准 API，部分服务商不读取，建议统一用 Authenticator。
2.2 SMTP 协议与 SSL/TLS 端口怎么选：465 还是 587
很多新手在这件事上翻车。465 端口是 SSL 加密的 SMTP，通常用于老式客户端；587 端口是 STARTTLS 加密，连接时先走明文，再升级为加密通道。现代邮箱服务商普遍推荐 587 + STARTTLS，但部分服务商的默认端口是 465。选错端口的表现是连不上、超时，或者偶尔能连上但邮件被拒。
// 465 端口需要单独开启 SSL 套接字 props.put("mail.smtp.ssl.enable", "true"); props.put("mail.smtp.socketFactory.class", "javax.net.ssl.SSLSocketFactory"); props.put("mail.smtp.ssl.trust", "smtp.example.com");使用 465 时，socketFactory.port 要和 mail.smtp.port 一致，否则还会报端口不匹配。mail.smtp.ssl.trust 用来绕过证书校验，只在调试时用，生产环境不建议设置这个属性，否则有中间人攻击风险。我的习惯是优先用 587 + STARTTLS，因为兼容性最好，而且大多数服务商的文档都基于这个组合写。
2.3 用 JavaMail 还是 Spring 封装：边界在哪里
如果你的项目没有用 Spring，直接引入 javax.mail 是最轻量的方案。如果项目本身是 Spring Boot，用 Spring 自带的 JavaMailSender 会更顺手。但 Spring 封装也基于 JavaMail，只是把 Session 和 Transport 的连接管理、异常转换都处理好了。我一般会看发送需求复杂度：只发纯文本、偶尔发附件，直接用 JavaMail 写个小工具类；如果涉及 HTML 模板、批量发送、异步任务，引入 Spring 封装能少写很多样板代码。注意，Spring 的 JavaMailSenderImpl 里设置 username/password 时，如果邮件服务商开了双重认证，需要使用授权码而不是登录密码，这点很多人第一次会踩坑。
3. 完整实现：从纯文本到带附件邮件的可运行代码
3.1 环境准备：依赖引入与本地调试环境
这份资源里已经包含完整的依赖说明和可直接编译的源码。如果是 Maven 工程，只需要加一个坐标；如果是非 Maven，需要把 javax.mail.jar 放进 classpath。JavaMail 从 1.6 版本开始坐标变成了 jakarta.mail，如果你的项目还在用 javax.mail 的旧包，要注意版本冲突。
<!-- Maven 依赖：JavaMail 1.6.2 --> <dependency> <groupId>com.sun.mail</groupId> <artifactId>javax.mail</artifactId> <version>1.6.2</version> </dependency>本地调试时最容易忽略的是网络环境：公司内网可能限制 25 端口，必须改用 587 或 465。我一般会在测试类里先把收件人填成自己的备用邮箱，发送成功后检查原始邮件 headers，确认走了哪条链路。另外，本地没有 DNS 解析问题，但如果你改了 hosts 文件，可能会影响 SMTP 服务器的 TLS 证书校验结果。
3.2 基础实现：发送纯文本邮件
先写一个最简版本，确认环境通顺。这一步不涉及附件，只做三件事：创建 Session、构造 Message、调用 Transport.send。
// 纯文本邮件发送 public void sendPlainText(String to, String subject, String body) { Properties props = new Properties(); props.put("mail.smtp.host", "smtp.example.com"); props.put("mail.smtp.port", "587"); props.put("mail.smtp.auth", "true"); props.put("mail.smtp.starttls.enable", "true"); Session session = Session.getInstance(props, new Authenticator() { @Override protected PasswordAuthentication getPasswordAuthentication() { return new PasswordAuthentication("user@example.com", "authCode"); } }); try { MimeMessage message = new MimeMessage(session); message.setFrom(new InternetAddress("user@example.com")); message.setRecipient(Message.RecipientType.TO, new InternetAddress(to)); message.setSubject(subject, "UTF-8"); message.setText(body, "UTF-8"); Transport.send(message); } catch (MessagingException e) { e.printStackTrace(); } }这段代码里有两个细节：setSubject 和 setText 都显式传了 UTF-8，解决中文乱码；Transport.send(message) 内部会自动调用 Message 里保存的 Session 配置，无需手动 connect。如果不想要异常堆栈，可以包装成自定义异常，但要注意 MessagingException 属于受检异常，需要在上层处理。
3.3 进阶实现：MimeMultipart 组装带附件邮件
纯文本能发出去后，带附件就是加一个 MimeBodyPart 的问题。邮件正文和附件都放在一个 MimeMultipart 里，正文放在第一个 bodyPart，附件放在后续的 bodyPart。
// 带附件邮件发送 public void sendWithAttachment(String to, String subject, String body, File attachment) { Properties props = new Properties(); props.put("mail.smtp.host", "smtp.example.com"); props.put("mail.smtp.port", "587"); props.put("mail.smtp.auth", "true"); props.put("mail.smtp.starttls.enable", "true"); Session session = Session.getInstance(props, new Authenticator() { @Override protected PasswordAuthentication getPasswordAuthentication() { return new PasswordAuthentication("user@example.com", "authCode"); } }); try { MimeMessage message = new MimeMessage(session); message.setFrom(new InternetAddress("user@example.com")); message.setRecipient(Message.RecipientType.TO, new InternetAddress(to)); message.setSubject(subject, "UTF-8"); MimeBodyPart textPart = new MimeBodyPart(); textPart.setContent(body, "text/plain; charset=UTF-8"); MimeBodyPart attachmentPart = new MimeBodyPart(); attachmentPart.attachFile(attachment); attachmentPart.setFileName(MimeUtility.encodeText(attachment.getName(), "UTF-8", null)); MimeMultipart multipart = new MimeMultipart(); multipart.addBodyPart(textPart); multipart.addBodyPart(attachmentPart); message.setContent(multipart); Transport.send(message); } catch (MessagingException | IOException e) { e.printStackTrace(); } }这里的关键是 attachmentPart.setFileName 用 MimeUtility.encodeText 处理了文件名编码。如果不做这一步，文件名里包含中文时，常见表现是邮件客户端收到的附件名变成一串下划线乱码。attachFile 会自动根据文件扩展名设置 Content-Type，如果是 PDF 会设为 application/pdf，如果是压缩包会是 application/zip。你也可以手动通过 setHeader("Content-Type", "application/octet-stream") 强制所有附件按二进制流处理。
3.4 参数调优：超时、连接池与线程安全
把功能跑通后，要处理生产环境的健壮性。JavaMail 默认的 Socket 连接超时时间是 45 秒，在弱网环境下会拖累业务线程。建议显式设置连接、读写超时。
// 超时配置 props.put("mail.smtp.connectiontimeout", "10000"); props.put("mail.smtp.timeout", "10000"); props.put("mail.smtp.writetimeout", "10000");connectiontimeout 是建立 TCP 连接的超时，timeout 是发送命令后读取响应的超时，writetimeout 是写数据时的超时。全部设为 10 秒比较合适，超过就快速失败。关于线程安全，Session 和 Message 都不是线程安全的，我自己会在代码里每次发送时创建新的 Session，或者用 ThreadLocal 持有。消息对象不能跨线程复用，否则会出现邮件主题和收件人串掉的问题。批量发送时不要用同一个 Message 循环发给不同收件人，正确做法是每个收件人 new 一个 Message。
4. 避坑指南：身份认证、中文乱码与附件文件名的 5 个踩坑记录
4.1 现象：发送时提示 AuthenticationFailedException
原因之一是账号密码错误，但更常见的是使用了登录密码而不是授权码。主流邮箱服务商为了安全，默认关闭了 SMTP 的明文密码认证，必须在邮箱设置里打开 SMTP 服务并生成授权码。另一个原因是服务商要求必须先用网页登录一次才能激活 SMTP 通道。
解决：先到邮箱设置里确认 SMTP 服务已开启；如果开启后仍然报错，把密码换成授权码；再不行，检查代码里的 Authenticator 是否真正被调用，有的 Session 配置会被之前的 RemoteServer 缓存干扰。我一般会在代码里加一个调试输出，判断是否进入了 getPasswordAuthentication 方法。
4.2 现象：邮件正文中文显示“????”或者全是乱码
原因是 setText 和 setContent 时没有指定 charset，或者指定了 ISO-8859-1。JavaMail 默认采用平台的字符编码，在 Linux 服务器上通常是 UTF-8，但如果服务器 locale 是英文，就会用 ASCII 编码，中文全部变成问号。
解决：setText(body, "UTF-8") 和 setContent(body, "text/plain; charset=UTF-8") 两头都指定，注意 setContent 里只要写 contentType 字符串，不要再用 setText 覆盖。另外，MimeMultipart 里的文本部分也要单独指定编码，如果正文包含 HTML，建议用 “text/html; charset=UTF-8” 而不是纯文本，避免特殊字符被转义。
4.3 现象：附件文件名为中文时，收到邮件变成一堆下划线
原因：附件文件名在 MIME 编码里没有正确进行 Base64 编码。JavaMail 的 attachFile 方法会尝试从文件路径提取文件名，但如果文件名包含非 ASCII 字符，必须手动编码。
解决：使用 MimeUtility.encodeText(attachment.getName(), "UTF-8", "B")，这里的 B 代表 Base64 编码。上面代码中我写的是 setFileName(MimeUtility.encodeText(...))，这是标准做法。注意不要再用 setFileName 传普通字符串，否则某些邮件客户端会直接丢弃文件名。如果文件名里有空格，还需要手工替换成下划线，或者在编码前做 URLEncode 不锈钢处理。
4.4 现象：邮件能发出去，但收件人看不到附件，或者附件大小被限制
原因：邮件服务商对附件总大小有限制。免费邮箱一般是 20MB 到 50MB，如果发送超过限制，服务器会返回 552 或者类似错误。JavaMail 本身不会检查附件大小，它只是在传输中把字节流推送出去。
解决：发送前先检查 attachment.length()，超过阈值就要拆分或者压缩。同时注意 MimeMultipart 默认使用同一种编码，对所有附件统一 base64，这也可能导致体积膨胀 33%。如果附件本身是压缩包，又要转 base64，体积会更大。我一般在工具类里加一个 size 判断，超过 10MB 就提示改用分片发送或上传网盘再发链接。
4.5 现象：调试时看不到详细报错，或邮件在服务商的垃圾箱里
原因：JavaMail 默认没有完整的协议日志，报错只显示一个英文短句，不足以判断问题。另外内容被判定为垃圾邮件，大多因为纯文本里包含营销词汇、链接或者图片。
解决：调高日志级别，让 JavaMail 打印 RAW 协议。代码里加 session.setDebug(true)，或者在写代码时故意将收件人设为不同域名的测试邮箱。对于垃圾箱问题，建议先发给自己的同一个服务商邮箱，查看信头里是否有 SPF、DKIM 标记。如果你的发件域名没有 DNS 记录，几乎必进垃圾箱。这个问题不是代码能解决的，需要在域名管理后台添加 SPF 和 DKIM 记录。
5. 收尾：用封装工具类与异步发送提升可用性
功能跑通后，要把发送逻辑封装成一个独立工具类，避免业务代码里到处 new Session。我自己会做成静态方法，输入收件人、主题、正文、附件列表，统一处理超时和异常。
public class MailSenderUtil { public static void send(String to, String subject, String body, List<File> attachments) { // 内部统一构建 Session，基于上述配置 // 附件为空时走纯文本逻辑，非空时走 Multipart 逻辑 } }封装时还要考虑异步。邮件发送涉及网络 IO，如果在用户请求里直接调用，响应时间可能超过 2 秒。常见做法是丢进线程池，或者使用 Spring 的 @Async。我习惯用一个单线程的 ExecutorService 去消费队列里的邮件任务，因为邮件服务商对并发连接数有限制，并发太高容易触发限流。
另一种提升可用性的做法是增加重试机制。SMTP 返回 4xx 状态码时通常是临时性失败，比如邮箱满、服务器过载，可以等几秒重试；5xx 是永久失败，重试没有意义。注意 JavaMail 的 Transport.send 只在代码层面抛异常，不会自动区分 4xx 和 5xx，所以需要在 catch 里解析 MessagingException 的嵌套异常。我一般会写一个简单的重试封装，最多重试 3 次，间隔按 1 秒、5 秒、30 秒递增。
还有一个容易被忽略的点：本地测试和线上配置分离。测试时连接本地调试邮箱，线上才连接真实 SMTP 服务。配置文件里不要把密码写死在代码中，至少用环境变量或配置中心。以前我把授权码写在 properties 文件里，不小心提交到库，第二天就收到异地登录警告。从那以后，我每次发完邮件都会强制走一遍流程：确认认证方式是授权码，检查端口是 587 还是 465，附件文件名编码是否正常，发送后立刻去收件箱查看原始 header。这套流程看起来笨，但能挡掉九成以上的“明明代码没问题但就是发不出去”的玄学问题。希望帮到你。
本文还有配套的精品资源，点击获取
