Spring JavaMail内嵌图片在Web客户端显示为附件问题求助

我来帮你揪出这个内嵌图片变附件的问题！之前做邮件发送时踩过一模一样的坑，主要是这几个细节没处理对：

1. 模板里的图片引用必须用cid:前缀 #

Velocity模板中引用内嵌图片时，必须通过cid:XXX的格式关联代码中添加的内嵌资源，不能用相对路径或直接写本地地址。比如：

<!-- 正确写法 -->
<img src="cid:company-logo.png" alt="公司logo">

<!-- 错误写法（会被识别为附件或无法显示） -->
<img src="/images/logo.png" alt="公司logo">

这里的company-logo.png要和代码中设置的contentId完全一致，包括文件名大小写（部分邮件客户端对大小写敏感）。

2. 代码中用addInline正确添加内嵌资源 #

使用MimeMessageHelper的addInline方法添加图片时，要指定正确的contentId、资源路径和MIME类型，Spring会自动将资源标记为inline而非attachment。示例代码：

// 假设图片放在resources/static/images目录下
Resource logoResource = new ClassPathResource("static/images/company-logo.png");
// 第一个参数是contentId，要和模板里的cid完全匹配
helper.addInline("company-logo.png", logoResource, "image/png");

⚠️ 注意：不要同时用addAttachment和addInline处理同一个资源，否则会被当成附件发送。

3. 确保发送的是HTML邮件 #

helper.setText方法的第二个参数必须设为true，明确告知这是HTML格式的邮件——内嵌图片只在HTML邮件中生效，纯文本邮件会直接将图片转为附件或链接。你的代码里helper.setText(body, is...这里的isHtml参数一定要设为true。

4. 检查邮件原始源码（终极排查手段） #

如果以上步骤都做了还是有问题，在邮件客户端中打开“查看原始邮件”，检查图片对应的MIME部分：

• 确认Content-Disposition是inline，不是attachment
• 确认Content-ID的值和模板里的cid:后缀完全一致（部分客户端要求Content-ID带尖括号，比如<company-logo.png>，用Spring的addInline会自动处理，但手动构建时要注意）

Velocity模板（email-template.vm） #

<!DOCTYPE html>
<html>
<head>
    <style>
        .logo { width: 120px; border-radius: 8px; }
    </style>
</head>
<body>
    <h2>您好，欢迎加入我们！</h2>
    <img src="cid:company-logo.png" class="logo" alt="官方logo">
    <p>这是您的注册确认邮件，请点击下方按钮完成验证...</p>
</body>
</html>

Java发送代码 #

final MimeMessage message = mailSender.createMimeMessage();
final MimeMessageHelper helper = new MimeMessageHelper(message, true, "UTF-8");
try {
    helper.setFrom(getSystemAddress());
    if (replyTo != null) {
        helper.setReplyTo(replyTo);
    }
    helper.setTo(to);
    helper.setSubject("注册确认邮件");

    // 渲染Velocity模板
    VelocityEngine velocityEngine = new VelocityEngine();
    Properties props = new Properties();
    props.setProperty("resource.loader", "class");
    props.setProperty("class.resource.loader.class", "org.apache.velocity.runtime.resource.loader.ClasspathResourceLoader");
    velocityEngine.init(props);
    
    VelocityContext context = new VelocityContext();
    context.put("username", "张三"); // 模板变量
    String htmlBody = VelocityEngineUtils.mergeTemplateIntoString(velocityEngine, "email-template.vm", "UTF-8", context);

    // 设置HTML内容
    helper.setText(htmlBody, true);

    // 添加内嵌图片
    Resource logoResource = new ClassPathResource("static/images/company-logo.png");
    helper.addInline("company-logo.png", logoResource, "image/png");

    mailSender.send(message);
} catch (Exception e) {
    e.printStackTrace();
}

额外注意事项 #

• 部分邮件客户端（如Outlook）会将超过1MB的内嵌图片自动转为附件，这种情况建议压缩图片或改用外部CDN链接（但外部链接可能被邮件服务商拦截）。
• 确保Velocity模板没有被转义，比如cid:前缀被转成了cid%3A，导致无法识别。

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