Freemarker生成的Base64图片在邮件中不显示（Java）

Hey，我太懂你踩的这个坑了！网页里用data: URI的Base64图片显示得好好的，一放进邮件就罢工，核心原因是邮件客户端和浏览器对图片内嵌的支持逻辑完全不一样。

为什么会出现这个问题？ #

大多数现代浏览器都完美支持data:image/png;base64,...这种内嵌方式，但主流邮件客户端（比如Outlook、Gmail桌面端、部分企业邮箱）并不支持data: URI scheme——它们会直接忽略这种格式的图片引用，自然就显示不出来了。另外，就算有些客户端支持，如果你用的Base64字符串带换行（比如Java的MIME风格Base64编码器），也会导致解析失败。

最可靠的解决方案：用CID引用MIME附件 #

这是邮件内嵌图片的标准做法，兼容性拉满，几乎所有邮件客户端都支持。步骤如下：

1. 修改Java代码，添加图片为MIME附件并生成CID #

假设你用JavaMail API发送邮件，调整代码如下：

import javax.mail.*;
import javax.mail.internet.*;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Properties;

// 初始化邮件相关配置（根据你的实际情况调整）
Properties props = new Properties();
// ... 配置SMTP服务器、端口等信息

Session session = Session.getInstance(props, new Authenticator() {
    protected PasswordAuthentication getPasswordAuthentication() {
        return new PasswordAuthentication("your-email@domain.com", "your-password");
    }
});

try {
    MimeMessage message = new MimeMessage(session);
    message.setFrom(new InternetAddress("your-email@domain.com"));
    message.setRecipients(Message.RecipientType.TO, InternetAddress.parse("recipient@domain.com"));
    message.setSubject("Test Email with Inline Image");

    // 读取图片文件
    String filePath = System.getProperty("catalina.base") + "/conf/app-core/logo.png";
    byte[] imageData = Files.readAllBytes(Paths.get(filePath));

    // 创建图片附件，设置为INLINE并指定CID
    MimeBodyPart imagePart = new MimeBodyPart();
    imagePart.setContent(imageData, "image/png");
    imagePart.setFileName("logo.png");
    // 生成唯一的CID（格式必须是<xxx@domain>）
    String imageCid = "logo@yourdomain.com";
    imagePart.setHeader("Content-ID", "<" + imageCid + ">");
    imagePart.setDisposition(MimeBodyPart.INLINE);

    // 生成HTML正文（从Freemarker模板渲染）
    MimeBodyPart textPart = new MimeBodyPart();
    // 把CID传入Freemarker模板的map中
    map.put("logoCid", imageCid);
    // 假设你已经有Freemarker的模板处理逻辑
    String htmlContent = freemarkerTemplate.process(map, new StringWriter());
    textPart.setContent(htmlContent, "text/html; charset=utf-8");

    // 组装Multipart内容
    Multipart multipart = new MimeMultipart();
    multipart.addBodyPart(textPart);
    multipart.addBodyPart(imagePart);

    message.setContent(multipart);
    Transport.send(message);

} catch (Exception e) {
    e.printStackTrace();
}

2. 修改Freemarker模板，用CID引用图片 #

把原来的Base64引用替换成CID：

<img src="cid:${logoCid}" alt="Company Logo" />

如果你坚持要用Base64（不推荐） #

如果因为某些原因必须用data: URI，要注意两个关键点：

1. 确保Base64字符串没有换行：Java的java.util.Base64.getEncoder()默认生成的是无换行的Base64，这个没问题；但如果你之前用的是getMimeEncoder()，一定要换成getEncoder()。
2. 仅在兼容性要求低的场景使用：只有少数客户端（比如Apple Mail、Thunderbird）支持这种方式，正式邮件不建议用。

修改后的Java代码（保持Base64方式）：

String filePath = System.getProperty("catalina.base") + "/conf/app-core/logo.png";
Path path = Paths.get(filePath);
byte[] data = Files.readAllBytes(path);
// 使用无换行的Base64编码器
byte[] encoded = java.util.Base64.getEncoder().encode(data);
String imgDataAsBase64 = new String(encoded);
String imgAsBase64 = "data:image/png;base64," + imgDataAsBase64;
map.put("logo", imgAsBase64);

模板还是原来的写法：

<img src="${logo}" alt="Company Logo" />

总结 #

优先选择CID引用MIME附件的方式，这是邮件内嵌图片的行业标准，能解决99%的兼容性问题。Base64的data: URI只适合网页场景，邮件里尽量别用。

内容的提问来源于stack exchange，提问作者Daryn