Django中使用Gmail API发送PDF附件邮件异常：附件未显示

问题描述 #

在Django后端使用Gmail API发送包含PDF附件的邮件时，收件方仅能看到邮件正文，附件无法显示。日志明确记录PDF已生成并完成添加：

[DEBUG] Generated PDF size: 16988 bytes[DEBUG] Attaching PDF: invoice_EJ70FEX.pdf (size: 16988 bytes) [INFO] Email sent successfully. Message ID: 19561950e1b649a0

但实际收到的邮件中无可见附件。

所用代码 #

import logging
from django.core.mail import EmailMultiAlternatives
from django.template.loader import render_to_string
from django.utils.html import strip_tags
from django.conf import settings
from email.utils import formataddr
import base64

logger = logging.getLogger(__name__)

def send_damage_invoice(driver_data, pdf_content):
    """发送带PDF附件的损坏账单邮件"""
    try:
        logger.debug("正在为%s (%s) 准备损坏账单邮件", 
                    driver_data['name'], driver_data['vrm'])

        subject = f'Damage Charges Invoice - {driver_data["vrm"]}'
        from_email = formataddr(('H&S Autocare', settings.DEFAULT_FROM_EMAIL))
        to_email = driver_data['email']

        # 构建邮件模板上下文
        context = {
            'driver_name': driver_data['name'],
            'vrm': driver_data['vrm']
        }

        # 渲染邮件内容
        html_content = render_to_string('emails/damage_invoice.html', context)
        text_content = strip_tags(html_content)

        # 创建邮件消息
        email = EmailMultiAlternatives(
            subject=subject,
            body=text_content,
            from_email=from_email,
            to=[to_email]
        )
        email.attach_alternative(html_content, "text/html")

        # 添加PDF附件
        filename = f'invoice_{driver_data["vrm"]}.pdf'
        logger.debug("添加PDF附件: %s (大小: %d 字节)", filename, len(pdf_content))
        email.attach(filename, pdf_content, 'application/pdf')

        email.send(fail_silently=False)
        logger.info("邮件已成功发送至%s", to_email)

        return True

    except Exception as e:
        logger.error("发送损坏账单邮件失败: %s", str(e))
        raise

排查方向建议 #

• PDF内容编码检查：确认pdf_content是原始二进制数据，而非base64编码后的字符串。如果是base64编码内容，需先解码为二进制再添加附件。
• MIME格式兼容性：部分邮件客户端对MIME边界处理敏感，可尝试直接构造MIME消息替代EmailMultiAlternatives，或检查Django邮件后端配置是否适配Gmail API。
• 邮件客户端过滤：部分客户端会自动隐藏附件或标记邮件为垃圾，建议检查收件箱垃圾文件夹，或更换不同客户端测试。
• 文件名合法性：确认文件名invoice_{driver_data["vrm"]}.pdf无特殊字符，避免客户端解析失败。

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