使用Firebase Sendgrid扩展的Flutter邮件图片附件显示异常

问题场景 #

使用Firestore搭配Trigger Email Sendgrid扩展发送带内嵌QR码的邮件，通过cid引用附件图片，但在Gmail、Mailinator中收到的图片均显示破损。已尝试移除Base64的data:image/jpeg;base64,前缀，且使用Flutter Screenshot包捕获QrImage生成纯Base64编码，问题仍未解决。

排查与解决方案 #

1. 验证Base64编码有效性 #

将生成的email.image字符串复制到Base64转图片工具中，确认图片能正常显示。如果工具无法解析，说明Screenshot捕获或编码过程存在问题：

• 检查_screenshotController.capture()返回的image是否为有效字节流，可通过image.length判断是否为空或异常。

2. 修正附件参数的格式匹配 #

QrImage默认生成的是PNG格式图片，但代码中附件type设置为image/jpeg，格式不匹配会导致邮件客户端无法解析：

'attachments': [
  {
    'filename': "qr.png", // 改为PNG文件名
    'content': email.image,
    'content_id': "qr",
    "type": "image/png", // 匹配实际图片格式
    "disposition": "inline",
  }
]

3. 检查Firestore文档写入完整性 #

确认mail集合中的文档字段无截断：

• 查看attachments[0].content字段是否完整保留了Base64字符串，Firestore单文档最大1MB，QR码的Base64远小于该限制，若出现截断需检查Flutter写入逻辑是否有字符串处理错误。

4. 调试邮件原始内容 #

在Gmail中打开邮件，点击「更多」→「显示原始内容」，搜索Content-ID: <qr>：

• 确认Content-Type与设置的type一致，Base64内容无乱码或截断。若内容不匹配，说明扩展在处理时出现异常，需检查扩展配置的Sendgrid API权限。

5. 备选方案：直接嵌入Base64到HTML #

若cid方式仍有问题，可跳过附件，直接将Base64嵌入HTML的img标签：

'message': {
  'subject': email.subject,
  'html': '<img alt="QR code" src="data:image/png;base64,${email.image}"/>',
}

此方式无需配置attachments字段，适合体积较小的QR码图片。

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