本文详解如何在 Micronaut 应用中正确发送含内联图片的 HTML 邮件，重点解决 cid: 引用失效、图片显示为附件而非嵌入内容等常见问题，提供可直接落地的代码方案与关键配置说明。
本文详解如何在 micronaut 应用中正确发送含内联图片的 html 邮件，重点解决 `cid:` 引用失效、图片显示为附件而非嵌入内容等常见问题，提供可直接落地的代码方案与关键配置说明。
在使用 Micronaut 构建邮件服务时，若需在 HTML 邮件正文中内联显示图片（如 Logo、品牌图标），仅将图片作为普通附件添加是无效的——这会导致 Outlook、Apple Mail 等主流客户端仅显示 alt 文本或小红叉。根本原因在于：内联图片必须满足 MIME 结构规范：邮件整体需为 multipart/related 类型，图片附件需声明 Content-Disposition: inline 并绑定唯一 Content-ID，HTML 中则通过 <img src="cid:xxx" alt="Micronaut 中实现 HTML 邮件内联图片（CID 嵌入）的完整指南" > 精确引用。
Micronaut 的 io.micronaut.email 模块（如 micronaut-email-javamail）原生支持该机制，但需严格遵循以下三要素，缺一不可：
✅ 1. 正确构造内联附件（关键！）
Attachment.builder() 必须同时设置：
-
.id("logo.png")—— ID 值必须与 HTML 中cid:后的字符串完全一致（推荐直接用文件名，避免特殊字符）； -
.disposition("inline")—— 显式声明为内联（非attachment），这是区分“附件”与“内联资源”的核心标识； -
.filename("logo.png")—— 文件名建议与 ID 一致，提升兼容性； -
.contentType(MediaType.IMAGE_PNG)—— 使用标准 MIME 类型（image/png,image/jpeg）； -
.content(byte[])—— 图片二进制数据（确保非 null）。
byte[] logoBytes = IOUtils.resourceToByteArray("static/logo.png", getClass().getClassLoader());
Attachment inlineLogo = Attachment.builder()
.id("logo.png") // ← 必须与 <img src="cid:logo.png" alt="Micronaut 中实现 HTML 邮件内联图片（CID 嵌入）的完整指南" > 完全匹配
.filename("logo.png")
.contentType(MediaType.IMAGE_PNG)
.content(logoBytes)
.disposition("inline") // ← 最关键！不可省略
.build();✅ 2. 构建 multipart/related 邮件结构
Micronaut 默认使用 multipart/alternative（纯文本 + HTML），但内联图片必须升级为 multipart/related。需确保：
立即学习“前端免费学习笔记（深入）”；
- 邮件主体（HTML）与内联附件处于同一
multipart/related容器下； -
Email.builder()中同时传入 HTML body 和 inline attachment（无需额外设置）； - 使用
TemplateBody时，模板渲染后的 HTML 字符串会自动参与 MIME 组装。
Map<String, Object> model = Map.of("xyz", "aaaaaaa");
TemplateBody<Map<String, Object>> body =
new TemplateBody<>("mail/mail-body.vm", model);
Email email = Email.builder()
.to("recipient@example.com")
.from("sender@example.com")
.subject("带Logo的邮件")
.body(body)
.attachment(inlineLogo) // ← 此处添加即触发 multipart/related 自动构建
.build();
emailSender.send(email);✅ 3. Velocity 模板中正确引用 CID
HTML 中 <img alt="Micronaut 中实现 HTML 邮件内联图片（CID 嵌入）的完整指南" > 标签的 src 属性必须严格匹配附件 .id() 值，且不带路径、不带扩展名以外的特殊符号：
<!-- mail-body.vm --> <div> <p>欢迎使用我们的服务！</p> <img src="cid:logo.png" alt="公司Logo" style="max-width:90%" style="max-width:90%"/> </div>
⚠️ 注意事项：
- 不要使用 Base64：多数企业邮箱（Outlook、Gmail Web）默认拦截或截断超长 Base64 字符串，导致图片丢失；
- 禁止使用相对路径或本地 URL：邮件客户端无法访问发件人本地文件系统；
- ID 命名规范：避免空格、中文、下划线开头；推荐
logo.png、banner-jpg等简洁格式；- 验证原始邮件头：用邮件客户端“查看原始信息”或抓包工具确认最终 MIME 结构是否为：
Content-Type: multipart/related; boundary="..."` --boundary Content-Type: text/html; charset=UTF-8 --boundary Content-Type: image/png Content-ID: <logo.png> ← 注意尖括号！Micronaut 会自动添加 Content-Disposition: inline
✅ 补充：多图场景处理
若需嵌入多个图片，只需为每张图创建独立 Attachment，并确保 .id() 唯一且与 HTML 中 cid: 一一对应：
Attachment banner = Attachment.builder()
.id("banner.jpg").filename("banner.jpg")
.contentType(MediaType.IMAGE_JPEG)
.content(bannerBytes).disposition("inline").build();
Attachment icon = Attachment.builder()
.id("icon.svg").filename("icon.svg")
.contentType(MediaType.IMAGE_SVG_XML)
.content(iconBytes).disposition("inline").build();
Email.builder()
.body(body)
.attachment(banner)
.attachment(icon) // 支持链式添加多个 inline 附件
.build();通过以上配置，Micronaut 将自动生成符合 RFC 2387 标准的 multipart/related 邮件，确保图片在 Outlook Desktop、Outlook on Web、Apple Mail、Thunderbird 等主流客户端中稳定内联显示——告别小红叉，交付专业级邮件体验。
