如何阻止Gmail将Spring发送的内嵌图片显示为附件？

嘿，这个问题我太熟了！Gmail对内嵌图片的识别规则有点“轴”，只要咱们把几个关键配置弄对，就能搞定它。

核心原因 #

Gmail会把没有明确标记为inline或者Content-ID设置错误的内嵌资源自动当成附件。所以咱们要做的就是确保Spring生成的邮件头部完全符合Gmail的要求。

具体修改步骤（结合你的代码） #

我把你的代码补全并修改，关键地方都标出来了：

public class Email {
    public static MimeMessagePreparator getContentAsInlineResourceMessagePreparator(final String to) {
        MimeMessagePreparator preparator = new MimeMessagePreparator() {
            public void prepare(MimeMessage mimeMessage) throws Exception {
                MimeMessageHelper helper = new MimeMessageHelper(mimeMessage, true, "UTF-8");
                helper.setSubject("Email with Inline Image");
                helper.setTo(to);
                helper.setFrom("your-sender-email@example.com");
                
                // 1. 必须使用HTML格式的邮件内容，并用cid引用图片
                String htmlContent = "<html><body>" +
                    "Hi there! Here's our logo:<br>" +
                    "<img src=\"cid:companyLogo\" alt=\"Our Company Logo\" width=\"200\">" +
                    "</body></html>";
                // 第二个参数设为true，告诉Spring这是HTML邮件
                helper.setText(htmlContent, true);
                
                // 2. 添加内嵌图片，关键配置在这里！
                Resource imageResource = new ClassPathResource("images/company-logo.png");
                // 第一个参数：对应HTML里的cid:companyLogo（必须完全匹配）
                // 第三个参数：明确指定图片的MIME类型，避免Gmail识别错误
                helper.addInline("companyLogo", imageResource, "image/png");
            }
        };
        return preparator;
    }
}

几个容易踩的坑 #

• 忘记开启HTML模式：如果helper.setText()的第二个参数是false（默认），邮件会被当成纯文本，内嵌图片直接变附件，这是最常见的错误！
• Content-ID不匹配：HTML里的cid:xxx必须和addInline()的第一个参数完全一致，大小写都不能错。
• 图片尺寸过大：Gmail对大图片（比如超过1MB）会强制转为附件，所以建议把图片压缩到合适大小。
• 资源路径错误：如果图片找不到，Spring会把它当成无效附件发送，所以要确保ClassPathResource的路径和实际文件位置一致。

排查技巧 #

如果还是不行，你可以在Gmail里打开邮件的“显示原始内容”，检查这两个头部：

• Content-Disposition: inline：必须是inline，不能是attachment
• Content-ID: <companyLogo>：必须和你设置的cid一致，并且带尖括号（Spring的addInline会自动加，不用手动写）

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