PHPMailer调用AddEmbeddedImage嵌入内联图片时收到空白邮件

问题修复方案 #

出现启用内联图片后Outlook、Gmail显示空白邮件、但方法返回true的情况，核心诱因都是MIME结构生成异常，按以下优先级排查即可：

• addEmbeddedImage返回true仅代表目标图片文件存在、可读、参数格式符合基础校验规则，不会校验后续MIME结构合法性，也不会检查正文CID引用是否正确，不能用返回值判断嵌入逻辑有效。
• 第一优先级检查正文CID引用格式：必须严格写为<img src="cid:你传入的$ImageCID值">，不能漏写cid:前缀、不能加多余空格、不能用本地路径/网络URL替代CID值。CID引用不匹配时PHPMailer不会抛出错误，但会直接导致MIME边界断裂，客户端无法解析正文结构，最终显示空白邮件。
• 第二优先级检查参数传值：$ImageCID必须是纯ASCII字符，不能包含中文、全角符号、特殊空格，建议直接用uniqid() . '@phpmailer'这类规则生成唯一标识；$ImageType参数不要手动传值，留空让PHPMailer自动检测图片MIME类型即可，手动传错类型（比如实际是PNG传了image/jpeg）是非常高发的异常原因。
• 最简验证方式：先去掉所有自定义传参，用最简调用测试：$mail->addEmbeddedImage($ImagePath, 'test-cid-001');，正文写最小测试内容<p>测试正文</p><img src="cid:test-cid-001">，确认该状态下邮件正常显示后，再逐个追加自定义参数定位具体传参错误。

AddEmbeddedImage方法参数说明 #

该方法完整签名为addEmbeddedImage($path, $cid, $name = '', $encoding = PHPMailer::ENCODING_BASE64, $type = '', $disposition = 'inline')，各参数的作用和推荐取值如下：

• 第三个参数$name（文件名参数）：作用是用户右键保存内联图片时，弹窗默认填充的文件名，不需要强制自定义；留空时PHPMailer会自动取图片路径的原文件名，如果需要自定义，必须传入带正确后缀的合法文件名，不要传无后缀、含特殊转义字符的名称。
• 第四个参数$encoding（编码参数）：固定推荐传入类常量PHPMailer::ENCODING_BASE64，不要直接传字符串'base64'，不同PHPMailer版本对字符串传参的兼容逻辑不一致，直接传常量是最稳妥的方式，不要留空，留空触发的默认编码 fallback 逻辑在部分旧版本中会导致MIME头异常。
• 第六个参数$disposition（配置参数）：标准MIME协议下仅支持两个合法取值：
  • inline：默认值，图片作为内联资源嵌入正文，不会在邮件附件栏单独显示
  • attachment：图片作为独立附件存在，即使正文用CID引用，客户端也会在附件栏展示该文件
    不要传入其他自定义值，非标准disposition值会直接导致客户端MIME解析失败。

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