根本原因是MimeMessageHelper未正确设置附件MIME类型和文件名编码，或输入流被提前关闭；需显式指定类型、UTF-8编码文件名、使用ByteArrayResource避免流关闭。
JavaMailSender 发送带附件的邮件时，为什么附件总是空或乱码？
根本原因通常是 MimeMessageHelper 没正确设置附件的 MIME 类型和文件名编码，或者输入流被提前关闭。Spring 的 MimeMessageHelper 默认对附件名做 RFC 2047 编码，但若原始文件名含中文且未显式指定字符集，部分邮箱客户端（如 Outlook）会解码失败，显示为乱码或丢失。
实操建议：
立即学习“Java免费学习笔记（深入）”；
- 始终用
helper.addAttachment("简历.pdf", new ByteArrayResource(bytes), "application/pdf")显式传入 MIME 类型，别依赖自动探测 - 附件名含中文时，用
MimeUtility.encodeText("张三_简历.pdf", "UTF-8", "B")预处理，再传给addAttachment - 避免用
new FileInputStream(file)直接传入 —— 流在发送过程中可能被关闭；改用new ByteArrayResource(Files.readAllBytes(file.toPath())) - 如果附件来自 HTTP 下载，确保响应体已完整读取并转成字节数组，而不是直接传
InputStreamResource（它不支持多次读取）
SMTP 配置里 mail.smtp.auth 和 mail.smtp.starttls.enable 到底要不要开？
绝大多数现代邮件服务商（Gmail、QQ 邮箱、163、企业 SMTP）都强制要求身份认证 + 加密传输，关掉其中任一选项，AuthenticationFailedException 或连接超时几乎是必然结果。
实操建议：
立即学习“Java免费学习笔记（深入）”；
-
mail.smtp.auth必须设为true，否则JavaMailSender根本不会尝试发用户名密码 -
mail.smtp.starttls.enable对 587 端口是必须的；若用 465 端口，则应设mail.smtp.ssl.enable=true，且starttls.enable要关掉（否则可能握手失败） - QQ 邮箱要求开启“POP3/SMTP 服务”并在账户设置里生成专用密码，不能用登录密码；Gmail 同理，需开启两步验证后生成 App Password
- 测试时加一行
props.put("mail.debug", "true")，看日志里是否出现AUTH LOGIN和STARTTLS success
怎么让 JavaMailSender 支持动态附件路径和多个附件？
硬编码路径或只支持单个附件的写法，在真实业务中很快就会卡住 —— 比如导出报表后自动发邮件，附件名和数量每次都不一样。
java-api-doc-generator
下载
分析 Java Spring Boot 后端 Controller 代码，自动生成 Markdown 格式的接口文档。当用户说“生成 Java 接口文档”、“生成 API 文档”、“从 Spring 代码生成文档”时触发。
实操建议：
立即学习“Java免费学习笔记（深入）”；
- 把附件抽象成一个简单 POJO：
class Attachment { String filename; byte[] content; String contentType; }，避免直接操作FileSystemResource - 遍历附件列表时，统一用
helper.addAttachment(encodedName, new ByteArrayResource(a.content), a.contentType)，不依赖文件系统路径 - 如果附件来自数据库 BLOB，直接用
rs.getBytes("file_data")获取字节数组，别写临时文件 —— 减少 IO 和清理负担 - 注意总附件大小：单封邮件超过 25MB（Gmail 限制）会被静默截断，建议在发送前校验
attachments.stream().mapToLong(a -> a.content.length).sum()
Spring Boot 项目里，JavaMailSender 配置写在哪最容易出错？
常见陷阱不是配错参数，而是配置没生效 —— 比如把 spring.mail.* 写在 application-test.yml 里却跑了 dev profile，或者自定义了 @Bean JavaMailSender 却没禁用自动配置。
实操建议：
立即学习“Java免费学习笔记（深入）”；
- 优先用
application.yml声明标准配置项：spring.mail.host、spring.mail.port、spring.mail.username、spring.mail.password、spring.mail.properties.mail.smtp.auth等 - 如果需要额外属性（如
mail.smtp.connectiontimeout），必须加spring.mail.properties.前缀，否则被忽略 - 自定义
JavaMailSenderBean 时，加上@Primary并确认没有其他同类型 Bean；更稳妥的做法是只重写JavaMailSenderImpl的setJavaMailProperties，不覆盖整个 Bean - 启动后检查日志是否有
Using JavaMailSender implementation: org.springframework.mail.javamail.JavaMailSenderImpl，确认生效的是你配的那个实例
附件名编码、SMTP 加密开关、配置加载时机——这三个点，漏掉任何一个，邮件就可能发出去但收件人打不开、连不上、或根本没发成功。实际跑通一次比看十篇指南都管用。
