上一次在做一个JavaWeb练习项目时需要在用户注册后给邮箱发一封激活邮件。原以为很麻烦其实只要把流程拆开用原生ServletJSP配合JavaMail API完全能自己实现一套轻量邮件发送模块。整个过程不依赖Spring、不依赖框架每个步骤都看得见摸得着。这篇就把我的完整实现过程写出来从环境准备、核心代码、页面对接到部署运行时遇到的坑全盘记录包你照着能做出来。1. 整体思路与准备工作1.1 邮件发送的基本流程邮件发送本质上是客户端和邮件服务器之间的一段“对话”。你的JavaWeb程序扮演邮件客户端的角色通过SMTP协议连接邮件服务商提供的SMTP服务器然后发送身份认证信息认证通过后把邮件内容交给服务器由服务器负责投递到收件人的邮箱。所以最关键的两点一是要能连接上SMTP服务器二是要能通过认证。很多人第一次做邮件功能时卡住的地方就在认证上——你以为填的是邮箱登录密码但实际邮件服务商为了安全要求你用“授权码”代替登录密码而且这个授权码要你在邮箱设置里手动开启SMTP服务后才会生成。这一点务必摸索清楚否则后面代码写得再好也发不出去。1.2 技术选型为什么选择原生Servlet JavaMail现在网上搜“JavaWeb发送邮件”很多教程直接给你一套Spring Boot MailSender的代码确实简单但把JavaMail底层细节全封装掉了。对于刚学完Servlet和JSP的同学或者做课程设计、毕业设计的人来说用原生方式实现一遍能真正理解SMTP协议的交互过程JavaMail的API怎么用Session、MimeMessage、Transport这些对象分别负责什么日后转任何框架都会很轻松。另外原生方式的项目结构简单不用引入全家桶依赖。只需要准备一个Servlet容器我用的是Tomcat再加一个JavaMail的jar包总共两个关键组件就能跑起来。如果你要做的是一个由基础Servlet构建的项目切过去毫无压力。1.3 环境依赖与邮箱授权码准备我用的是Java 8 Tomcat 9 JavaMail 1.6.2。JavaMail从1.6开始已经自带jar包但注意还要配套一个javax.activation依赖否则运行时可能报ClassNotFoundException。如果你用Maven构建可以直接在pom.xml里搜索JavaMail相关依赖版本选1.6.2即可如果手写war包就把下载好的mail.jar和activation.jar丢到WEB-INF/lib目录下。接着进入邮箱设置开启SMTP服务。这一步不同邮箱位置不同但入口基本在“设置 - 账号”或者“安全中心”里找到“SMTP/IMAP”服务开启后会提示生成授权码。授权码通常是一串16位左右的字符串把它复制保存好后面写代码时当作SMTP登录密码使用。绝对不要直接在代码里硬编码邮箱的真实登录密码一是不安全二是服务商通常直接拒绝。2. 核心工具类与发送逻辑2.1 发送前的参数封装写代码之前先想清楚邮件发送需要哪些参数SMTP服务器地址、SMTP端口、发件人邮箱、授权码、收件人邮箱、主题、正文内容、是否HTML格式以及可选的附件和图片。这些参数如果散落在业务代码里后期维护会很混乱。我建议把它们统一放到一个配置类或者通过读取properties配置文件加载方便你换邮箱时只改一处。下面是我项目里用的配置类比较简单package com.example.webdemo.config; public class MailConfig { // SMTP服务器地址换成你的邮箱服务商实际地址即可 public static final String SMTP_HOST smtp.example.com; // 发件人邮箱地址 public static final String MAIL_FROM your-accountexample.com; // SMTP服务器端口SSL常用465STARTTLS常用587 public static final String SMTP_PORT 465; // 授权码不是登录密码 public static final String AUTH_CODE your-auth-code; }如果你有多套环境本地测试、生产环境更推荐用properties文件配合定时读取或启动时加载避免改一行代码就重新编译部署。我这个项目规模小直接写在类里也能接受但心里要清楚这不是值得推广的好习惯。2.2 纯文本邮件发送核心代码接下来是重量级工具类。我封装了一个MailUtils里面提供静态方法传入必要的参数即可完成发送。重点看里面的Session创建和MimeMessage组装这段是JavaMail的精华。package com.example.webdemo.util; import com.example.webdemo.config.MailConfig; import javax.mail.*; import javax.mail.internet.InternetAddress; import javax.mail.internet.MimeMessage; import java.util.Properties; public class MailUtils { public static void sendTextMail(String toEmail, String subject, String content) throws MessagingException { Properties props new Properties(); props.put(mail.smtp.host, MailConfig.SMTP_HOST); props.put(mail.smtp.port, MailConfig.SMTP_PORT); props.put(mail.smtp.auth, true); // SSL方式连接 props.put(mail.smtp.ssl.enable, true); props.put(mail.smtp.connectiontimeout, 10000); props.put(mail.smtp.timeout, 10000); Session session Session.getInstance(props, new Authenticator() { Override protected PasswordAuthentication getPasswordAuthentication() { return new PasswordAuthentication(MailConfig.MAIL_FROM, MailConfig.AUTH_CODE); } }); // 打开调试日志测试阶段可以清楚看到和SMTP服务器的交互 session.setDebug(true); MimeMessage message new MimeMessage(session); // 发件人 message.setFrom(new InternetAddress(MailConfig.MAIL_FROM)); // 收件人可以传多个地址逗号分隔 message.setRecipients(Message.RecipientType.TO, InternetAddress.parse(toEmail)); // 主题使用UTF-8编码 message.setSubject(subject, UTF-8); // 文本内容 message.setText(content, UTF-8); Transport.send(message); } }使用这个工具类时一行代码就搞定MailUtils.sendTextMail(receiverexample.com, 测试邮件, Hello这是一封来自JavaWeb的邮件);上面代码里session.setDebug(true)在开发阶段很有用控制台会打印出类似220 SMTP server ready、334 UGFzc3dvcmQ6这样的协议交互记录。第一次跑通后建议关掉否则日志会非常刷屏。这里的核心“为什么”我多说两句。Session是JavaMail里的会话对象它保存了所有SMTP相关配置和认证信息。MimeMessage代表一封符合MIME规范的电子邮件它依赖Session实例创建。Transport.send()是一个静态方法底层会帮我们建立连接、完成认证、发送邮件再断开连接所以日常开发中你不用手动去调transport.connect()和transport.close()。但如果你要在一个连接里发送多封邮件手动复用Transport会更合适。2.3 带HTML内容和内嵌图片的邮件很多时候你想发一封带样式、带图片的邮件比如激活链接、营销海报。JavaMail处理这种场景的核心是message.setContent(content, text/html;charsetUTF-8)但要注意如果你要内嵌图片而非外链图片就不能简单地把HTML当作字符串塞进去需要用MimeMultipart组装。public static void sendHtmlMail(String toEmail, String subject, String htmlContent, String imageCid, String imagePath) throws Exception { Properties props buildProps(); Session session buildSession(props); MimeMessage message new MimeMessage(session); message.setFrom(new InternetAddress(MailConfig.MAIL_FROM)); message.setRecipients(Message.RecipientType.TO, InternetAddress.parse(toEmail)); message.setSubject(subject, UTF-8); // 创建HTML正文部分 MimeBodyPart htmlPart new MimeBodyPart(); htmlPart.setContent(htmlContent, text/html;charsetUTF-8); // 创建图片部分 MimeBodyPart imagePart new MimeBodyPart(); imagePart.attachFile(imagePath); // 设置Content-IDHTML正文中用cid:imageId引用 imagePart.setHeader(Content-ID, imageCid ); imagePart.setDisposition(MimeBodyPart.INLINE); MimeMultipart multipart new MimeMultipart(); multipart.addBodyPart(htmlPart); multipart.addBodyPart(imagePart); // 如果只是普通HTML不内嵌图片用“related”即可 multipart.setSubType(related); message.setContent(multipart); Transport.send(message); }调用时HTML内容里写img srccid:logo其中logo就是传入的imageCid。这种方式发送的图片作为邮件正文的一部分存在不会因为外链失效而显示为红叉。可能遇到的问题有些邮箱对附件大小有限制内嵌图片一并计入整个邮件体积控制在2MB以内比较稳妥。用户收件时企业邮箱通常会自动屏蔽外部图片而cid方式内嵌的图片则不受影响这也是做邮件营销时优先选择内嵌图片的原因。2.4 带附件的邮件发送附件的逻辑和上面类似把附件作为单独的MimeBodyPart添加到MimeMultipart中并设置Disposition为ATTACHMENT。难点不在JavaMail而在文件路径获取和中文文件名编码。如果文件名里包含中文直接setFileName(资料.pdf)可能在部分邮箱里乱码需要用MimeUtility.encodeText()处理。public static void sendAttachmentMail(String toEmail, String subject, String contentText, File attachmentFile) throws Exception { Properties props buildProps(); Session session buildSession(props); MimeMessage message new MimeMessage(session); message.setFrom(new InternetAddress(MailConfig.MAIL_FROM)); message.setRecipients(Message.RecipientType.TO, InternetAddress.parse(toEmail)); message.setSubject(subject, UTF-8); MimeBodyPart textPart new MimeBodyPart(); textPart.setText(contentText, UTF-8); MimeBodyPart attachmentPart new MimeBodyPart(); attachmentPart.attachFile(attachmentFile); // 解决中文文件名乱码 String encodedFileName MimeUtility.encodeText(attachmentFile.getName(), UTF-8, B); attachmentPart.setFileName(encodedFileName); attachmentPart.setDisposition(MimeBodyPart.ATTACHMENT); MimeMultipart multipart new MimeMultipart(); multipart.addBodyPart(textPart); multipart.addBodyPart(attachmentPart); message.setContent(multipart); Transport.send(message); }附件路径有三种常见来源一是上传文件后存到服务器某个目录发送时传入File对象二是数据库存了BASE64字符串发送前先解码成临时文件再发三是从网络下载到本地临时目录。无论哪一种发送完成后都要考虑是否删除临时文件避免磁盘被占满。3. Servlet与前端页面对接3.1 表单页面与参数约束有了工具类接下来就是通过浏览器触发发送流程。我建了一个JSP页面作为邮件发送的测试入口。整个页面结构不复杂就是一个表单加上中间的结果提示区。页面完成后的效果大概是这样的这里用文字还原界面------------------------------------------ | JavaWeb 邮件发送测试工具 | | | | 收件人: [ ] | | | | 主题: [ ] | | | | 内容: [ ] | | [ 发 送 ] | ------------------------------------------前端页面里没有引入jQuery直接用原生的fetch提交表单数据这样更贴合“原生JavaWeb”的调性。注意Content-Type要用application/x-www-form-urlencoded否则Servlet里getParameter拿不到数据。% page contentTypetext/html;charsetUTF-8 languagejava % !DOCTYPE html html head meta charsetUTF-8 title邮件发送测试/title /head body h2JavaWeb 邮件发送测试工具/h2 form idmailForm 收件人input typetext nameto size40 placeholderreceiverexample.com/ br/br/ 主题input typetext namesubject size40/ br/br/ 内容textarea namecontent rows10 cols50/textarea br/br/ button typebutton onclicksendMail()发送/button /form div idresult stylemargin-top:20px;color:#333;/div script function sendMail() { var form document.getElementById(mailForm); var formData new URLSearchParams(new FormData(form)); fetch(sendMail, { method: POST, headers: {Content-Type: application/x-www-form-urlencoded}, body: formData.toString() }) .then(function (response) { return response.json(); }) .then(function (data) { document.getElementById(result).innerHTML data.msg; }) .catch(function (err) { document.getElementById(result).innerHTML 请求异常 err; }); } /script /body /html页面很简单但我故意没有写前端校验。实际项目里一定要在JS端先做一次空值判断和邮箱格式正则比如/^[a-zA-Z0-9_.-][a-zA-Z0-9-]\.[a-zA-Z0-9-.]$/这能省掉很多无效请求到达后端也减少被频繁调用的风险。3.2 Servlet端参数校验与调用Servlet负责接收请求、获取参数、调用MailUtils发送邮件、然后把发送结果以JSON格式返回给前端。如果你用的是Servlet 3.0以上版本可以直接用WebServlet(/sendMail)注解不用再在web.xml里手写servlet-mapping。package com.example.webdemo.servlet; import com.example.webdemo.util.MailUtils; import javax.servlet.ServletException; import javax.servlet.annotation.WebServlet; import javax.servlet.http.HttpServlet; import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse; import java.io.IOException; import java.io.PrintWriter; WebServlet(/sendMail) public class SendMailServlet extends HttpServlet { Override protected void doPost(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException { req.setCharacterEncoding(UTF-8); resp.setContentType(application/json;charsetUTF-8); String to req.getParameter(to); String subject req.getParameter(subject); String content req.getParameter(content); if (!isEmail(to) || subject null || subject.trim().isEmpty() || content null || content.trim().isEmpty()) { writeJson(resp, 500, 参数不完整或邮箱格式有误); return; } try { MailUtils.sendTextMail(to.trim(), subject.trim(), content.trim()); writeJson(resp, 200, 邮件发送成功); } catch (Exception e) { e.printStackTrace(); writeJson(resp, 500, 发送失败 e.getMessage()); } } private boolean isEmail(String email) { if (email null) { return false; } return email.matches(^[a-zA-Z0-9_.-][a-zA-Z0-9-]\\.[a-zA-Z0-9-.]$); } private void writeJson(HttpServletResponse resp, String code, String msg) throws IOException { PrintWriter out resp.getWriter(); out.print({\code\:\ code \,\msg\:\ msg \}); } }这里有两个容易忽略的细节需要说明。第一req.setCharacterEncoding(UTF-8)必须在req.getParameter()之前调用否则中文参数会在请求体解码时丢失最终出现乱码。第二返回JSON时msg里可能包含冒号、引号等特殊字符比如异常堆栈中的内容简单拼接会导致前端解析错误。严谨做法是用JSON库把字符串转义后再输出。由于这个项目坚持原生我手动把消息里的引号替换掉或者让前端做JSON.parse时做好容错。其实更推荐引入一个轻量JSON库能避免很多边界问题。3.3 发送状态回显与异步优化上面前端用的是fetch异步请求好处很明显点击发送后页面不刷新用户可以继续操作也不影响其他任务。如果做的是同步表单提交邮件发送慢的话用户会一直卡在页面上体验很差。异步请求返回后在result区域展示发送结果错误信息也能第一时间看到方便调试。关于异步还有一个进阶做法把邮件发送逻辑和请求线程解耦。比如收到请求后先把邮件信息存进数据库或者内存队列再从线程池里取一个线程去真正执行SMTP发送请求立刻返回“已加入发送队列”。这个方案适合注册邮件、通知邮件等量大、不要求即时的场景。如果每封邮件都同步发送遇到SMTP服务器响应慢用户请求线程就会被阻塞严重时Tomcat线程池被耗尽其他接口全部卡死。我后来在自己的项目里加了一个最简单的线程池优化核心代码大致是ExecutorService pool Executors.newFixedThreadPool(5); pool.submit(() - { try { MailUtils.sendTextMail(to, subject, content); } catch (Exception e) { e.printStackTrace(); } });这样做要注意如果服务器进程重启或崩溃队列中未发送的邮件可能会丢失。要可靠还是得落库并加上状态字段待发送/成功/失败配合定时任务重试失败项。这个扩展在测试阶段不必做但了解方案后后续上线心里有底。4. 部署运行与避坑指南4.1 Tomcat部署与目录结构我用的是传统war包方式。项目结构大致如下pom.xml 或者直接是手工构建 |-- src/main/java | |-- com.example.webdemo.config.MailConfig.java | |-- com.example.webdemo.util.MailUtils.java | |-- com.example.webdemo.servlet.SendMailServlet.java |-- src/main/webapp | |-- index.jsp | |-- WEB-INF | |-- lib | |-- mail.jar | |-- activation.jar启动Tomcat把打好的war包丢到webapps目录或者用IDEA里的Tomcat插件直接部署。访问http://localhost:8080/项目名/index.jsp填好收件人、主题、内容点击发送。如果控制台没有异常且看到Transport.send()执行完毕收件人的邮箱里就会收到邮件。一个非常容易踩的坑Tomcat版本和Servlet包名不匹配。Tomcat 9及以下版本对应javax.servletTomcat 10及以上版本已经换成jakarta.servlet。如果你拿Tomcat 10跑我代码里javax.servlet开头的Servlet类启动时会直接报NoClassDefFoundError。要么改用Tomcat 9要么把所有javax.servlet替换成jakarta.servlet。JavaMail的javax.mail包在Tomcat 10下不受影响所以问题主要集中在Servlet部分。4.2 常见异常及排查流程我在调试过程中遇到的典型问题整理成了一张速查表遇到问题可以对照排查。异常现象原因方向解决思路AuthenticationFailedException认证失败检查SMTP服务是否开启、授权码是否填对、发件人地址是否匹配Could not connect to SMTP host网络不通或端口错误用Telnet测试服务器的465/587端口是否可达确认端口对应SSL还是STARTTLSConnection refusedSMTP地址或防火墙问题确认地址是邮件服务商官方地址检查服务器安全组和本地防火墙中文主题乱码编码没有指定setSubject(subject, UTF-8)中文内容乱码编码没有指定setText(content, UTF-8)或者setContent(content, text/html;charsetUTF-8)附件的中文文件名乱码头部编码问题MimeUtility.encodeText(name, UTF-8, B)发送超时SMTP服务器响应慢调大mail.smtp.connectiontimeout和mail.smtp.timeout单位毫秒355/530错误码协议状态不对关闭session.setDebug后查看详细的SMTP交互往往能定位到具体原因调试时我强烈建议保留Telnet测试这步。在命令行输入telnet smtp.example.com 465如果显示连接被拒说明网络层就堵住了代码没有排查意义。如果连得上可以尝试手动敲SMTP命令但比较繁琐所以让session.setDebug(true)打印交互信息是最高效的方式。4.3 线上环境的安全建议邮件发送功能如果上线要注意的事情比本地跑通多很多。首先最重要的一条不要把你的邮箱授权码写在代码和配置文件里并提交到仓库。建议通过系统环境变量或者Tomcat的JNDI配置来注入比如在启动脚本里设置MAIL_AUTH_CODExxxx代码里通过System.getenv(MAIL_AUTH_CODE)读取密钥泄露后也能快速轮换。第二限制发送频率。如果你的邮件模块可以被用户随意调用又没有做频率控制分分钟被人利用刷爆邮箱甚至让你的服务器变成垃圾邮件发送器。简单做法是用Servlet过滤器拦截同一个IP或者同一个收件人的请求比如每分钟最多发送3封。更严格的方案是引入验证码、限制登录后才能使用。第三注意发送内容的合规性。模板里的邮件标题和正文不要带引导性、夸大性词汇不要做垃圾邮件群发否则邮箱服务商很快会把你的账号封禁而且域名或IP的邮件信誉一旦受损后续正常邮件也会被拒收。第四生产环境建议使用专业邮件发送服务或者自建邮件中继因为普通个人邮箱的SMTP发送数量和服务稳定性有限不适合作为业务系统的唯一发送通道。当然对于中小项目和练习场景个人邮箱的SMTP足够用了。最后再说一个我在实际使用中的体会原生JavaWeb发送邮件看起来代码量不大但真正难的是对邮件协议、编码、服务器限制的理解。一开始我也觉得设置一堆mail.smtp.*属性很玄学后来把这些属性当成“给Session准备的配置参数”把MimeMessage当成“信纸”思路立刻清晰了。跟着这篇文章把这个功能做完一遍再去接触邮件发送的框架封装你会觉得那些框架API简直就是在帮你偷懒而且你还能看懂它们底层到底做了什么。如果大家在实现时碰到别的问题建议先开session.setDebug(true)看协议日志再对照上面的排查表处理基本能解决90%的问题。