本文聚焦 Java 邮件发送配置与代码教程，覆盖从 SMTP 设置 到 示例代码 的完整实战要点。通过本指南，你可以在 Java 应用中实现可靠的邮件推送、支持 TLS/SSL 加密，并兼容 javax.mail 与 Jakarta Mail 的版本变迁。
一、SMTP 设置基础要点
1.1 SMTP 的工作原理与认证流程
在 Java 应用中发送邮件需要通过远端的 SMTP 服务器，其核心参数包括 主机地址、端口、用户名和密码，以及是否开启 身份认证 与 加密传输。理解这些参数有助于避免连接失败、邮件被拒收或被标记为垃圾邮件。
认证流程通常涉及用户名和密码的校验，以及在连接建立阶段的 TLS/SSL 握手，以确保传输链路的机密性和完整性。不同邮件服务提供商可能还支持 OAuth2 或应用专用密码的认证方式，需要在配置中正确开启对应选项。
1.2 常见配置项与注意事项
在 Java 应用中，最常见的 SMTP 配置项包括 mail.smtp.host、mail.smtp.port、mail.smtp.auth、以及 mail.smtp.starttls.enable。对于某些服务，还可能需要设置 mail.smtp.ssl.trust 或 mail.smtp.ssl.enable 等项以实现安全加密。正确设置这些参数是确保邮件发送成功的前提。
另外一个重要的点是 端口选择，587 常用于 STARTTLS，465 常用于 SSL 直接连接。不同提供商对端口的要求可能不同，应结合实际邮箱服务商的官方文档进行配置。
// 伪代码示例：基础 SMTP 配置属性
Properties props = new Properties();
props.put("mail.smtp.auth", "true");
props.put("mail.smtp.starttls.enable", "true"); // 启用 STARTTLS
props.put("mail.smtp.host", "smtp.example.com");
props.put("mail.smtp.port", "587"); // 常用端口，具体以服务商为准
在本小节中我们明确了 SMTP 设置的要点，这些要点在后续的代码实现中将直接映射为 Properties 对象的配置字段。
二、Java 邮件发送的核心技术与依赖
2.1 JavaMail 与 Jakarta Mail 的基础概览
Java 生态在从 javax.mail 迁移到 jakarta.mail 时，会有命名空间与依赖版本的变化。为了实现长期维护，建议在新项目中采用 Jakarta Mail，并选择 jakarta.mail 的最新版本，同时注意导入包名的变更，例如 jakarta.mail.Session、jakarta.mail.Transport、jakarta.mail.internet.MimeMessage 等。
对于旧有系统，仍然可以使用 javax.mail，但需要注意依赖版本与 Java 版本的兼容性。无论选择哪个命名空间，核心概念保持一致：会话对象、认证对象、邮件消息与发送。
2.2 依赖与版本迁移的实务要点
在 Maven/Gradle 项目中，选择合适的依赖坐标是确保编译通过的关键。Jakarta Mail 的常见坐标通常为 jakarta.mail:jakarta.mail-api 与实际实现包，例如 com.sun.mail:javax.mail（仅在老版本中使用），或者直接使用 org.eclipse.angus:jakarta.mail 的实现。务必在 pom.xml 或 build.gradle 中锁定版本以避免未来不兼容。
此外，若你的项目需要对邮件内容进行更复杂的处理（如 HTML 的发送、附件、嵌入图片），需要引入 jakarta.mail 的 MimeMessage、MimeBodyPart、Multipart 等类，并合理组织邮件结构。
// 使用 Jakarta Mail 的构造示例（核心导入示例）
import jakarta.mail.Session;
import jakarta.mail.PasswordAuthentication;
import jakarta.mail.Transport;
import jakarta.mail.Message;
import jakarta.mail.internet.InternetAddress;
import jakarta.mail.internet.MimeMessage;
三、从配置到发送的实战示例
3.1 完整示例代码（JavaMail/Jakarta Mail 双版本对照）
以下示例展示了一个从配置到发送的简洁流程。第一段示例基于 Jakarta Mail，第二段为传统的 javax.mail 风格，便于对比与迁移参考。核心要点在于：正确的 会话创建、正确设置 发件人、收件人、主题与正文，以及使用 Transport.send 完成发送。
// Jakarta Mail（推荐新项目使用）示例
import jakarta.mail.Session;
import jakarta.mail.PasswordAuthentication;
import jakarta.mail.Transport;
import jakarta.mail.Message;
import jakarta.mail.internet.InternetAddress;
import jakarta.mail.internet.MimeMessage;
import java.util.Properties;public class EmailDemoJakarta {public static void main(String[] args) throws Exception {String username = "your_email@example.com";String password = "your_password";Properties props = new Properties();props.put("mail.smtp.auth", "true");props.put("mail.smtp.starttls.enable", "true");props.put("mail.smtp.host", "smtp.example.com");props.put("mail.smtp.port", "587");Session session = Session.getInstance(props, new PasswordAuthentication(username, password) {@Overrideprotected PasswordAuthentication getPasswordAuthentication() {return new PasswordAuthentication(username, password);}});Message message = new MimeMessage(session);message.setFrom(new InternetAddress(username));message.setRecipients(javax.mail.Message.RecipientType.TO, InternetAddress.parse("recipient@example.com"));message.setSubject("测试主题");message.setText("这是通过 Jakarta Mail 发送的测试邮件。");Transport.send(message);}
}
// javax.mail（传统风格）示例，适合兼容旧项目
import javax.mail.Session;
import javax.mail.PasswordAuthentication;
import javax.mail.Transport;
import javax.mail.Message;
import javax.mail.internet.InternetAddress;
import javax.mail.internet.MimeMessage;
import java.util.Properties;public class EmailDemoJavax {public static void main(String[] args) throws Exception {final String username = "your_email@example.com";final String password = "your_password";Properties props = new Properties();props.put("mail.smtp.auth", "true");props.put("mail.smtp.starttls.enable", "true");props.put("mail.smtp.host", "smtp.example.com");props.put("mail.smtp.port", "587");Session session = Session.getInstance(props, new javax.mail.Authenticator() {protected PasswordAuthentication getPasswordAuthentication() {return new PasswordAuthentication(username, password);}});Message message = new MimeMessage(session);message.setFrom(new InternetAddress(username));message.setRecipients(Message.RecipientType.TO, InternetAddress.parse("recipient@example.com"));message.setSubject("Test Subject");message.setText("This is a test email sent via javax.mail.");Transport.send(message);}
}
上述代码清晰展示了从 SMTP 设置到邮件发送 的完整流程。需要注意的是，当你迁移到 Jakarta Mail 时，导入的包名将从 javax 切换为 jakarta，其余逻辑基本保持不变。
3.2 结合附件和 HTML 邮件的实战要点
在实际应用中，常会遇到需要发送带 HTML 正文、附件 或 多部分邮件 的场景。此时要使用 MimeMultipart 构建邮件体，合理分段并确保文本与 HTML 的兼容性，避免被接收端误判为垃圾邮件。在属性配置方面，建议保持 mail.smtp.auth、mail.smtp.starttls.enable 等字段健壮，以保障传输安全。
下面是一个简化的带有 HTML 正文的示例要点：将 MimeBodyPart 与 Multipart 组合，将文本/HTML 分别作为不同的子部分传递给邮件对象。
// HTML 内容的邮件发送示例片段（Jakarta Mail 要点）
import jakarta.mail.internet.MimeBodyPart;
import jakarta.mail.internet.MimeMultipart;
...
MimeMessage message = new MimeMessage(session);
message.setFrom(new InternetAddress(username));
message.setRecipients(Message.RecipientType.TO, InternetAddress.parse("recipient@example.com"));
message.setSubject("HTML 邮件示例");MimeBodyPart textPart = new MimeBodyPart();
textPart.setContent("欢迎
这是一封 HTML 邮件。
", "text/html; charset=utf-8");MimeMultipart multipart = new MimeMultipart("alternative");
multipart.addBodyPart(textPart);
message.setContent(multipart);Transport.send(message);
通过以上要点，你可以在 Java 应用中实现更丰富的邮件内容与更可靠的投递行为。关键在于正确处理 邮件体结构、确保 编码匹配，以及对 邮件服务器的防垃圾策略有所了解。
3.3 常见问题与排错要点
在实际运行中，常见的问题包括 认证失败、端口被阻塞、TLS 握手失败，以及 邮件被标记为垃圾邮件。排错时要关注 日志级别、是否开启了 调试模式、以及邮件服务器返回的错误代码。开启 mail.debug 可以帮助你获取更详细的调试信息，并据此调整参数与网络设置。
另外，请确保 凭据安全性，避免在源码中直接硬编码密码，建议使用安全的凭据管理方案，或读取环境变量/配置中心中的凭据，以提升应用的安全性。
本指南覆盖了从 SMTP 设置、到 JavaMail/Jakarta Mail 的依赖与迁移、再到 完整实战示例代码的全过程。通过遵循这些要点，你可以在 Java 应用中实现可靠的邮件发送能力，满足从开发到运维的多场景需求。上述代码片段与配置要点均围绕“Java 邮件发送配置与代码教程：从 SMTP 设置到示例代码的完整实战指南”的核心主题展开，帮助你快速落地实现。
