附件发送失败主因是路径错误、MIME类型不当、上下文不一致及SMTP配置不足；需用绝对路径校验存在性、正确设置二进制文件MIME子类型、共用token变量、压缩大附件并调高超时阈值。
附件路径错误导致邮件发送失败
Flask-Mail 本身不校验附件文件是否存在，send() 调用成功但收件人收不到附件，大概率是路径写错了。常见坑是：用相对路径（比如 "./files/verify.pdf"）在生产环境（如 Gunicorn 启动）下找不到文件——工作目录不是你开发时的项目根目录。
- 始终用
os.path.join(app.root_path, "static", "attachments", "verify.pdf")构造绝对路径，app.root_path稳定指向 Flask 应用实例所在目录 - 发信前加一行检查：
if not os.path.exists(attachment_path): raise ValueError(f"Attachment missing: {attachment_path}") - 别把敏感文件（如数据库备份）放附件目录，Flask 静态路由可能意外暴露它们
构造带附件的 Message 实例要注意 MIME 类型
Message 对象对附件没封装高级接口，必须手动添加 MIMEApplication 或 MIMEBase，否则附件会变成乱码或被拒收。尤其注意二进制文件（PDF、PNG）不能用 attach(filename, content, 'text/plain') 硬塞。
- 文本类附件（如 .txt、.csv）可用
msg.attach("info.txt", "text/plain", content.encode("utf-8")) - 二进制文件必须读取为 bytes 并指定 subtype：
with open(path, "rb") as f: msg.attach("verify.pdf", "application/pdf", f.read()) - 避免用
charset="utf-8"去 attach 二进制内容——这会导致 PDF 头部被篡改，打开报错
验证邮件正文和附件需共用同一上下文变量
用户点击邮件里的验证链接时，链接参数（如 token）要和附件里嵌入的凭证一致，否则验证逻辑断裂。附件内容（如 PDF 里的 token）不能靠模板渲染生成，得和邮件正文用同一个 generate_token(user.id) 结果。
- 生成 token 后立刻存入变量：
token = generate_token(user.id)，再同时用于url_for("auth.verify", token=token, _external=True)和附件内容填充 - 如果附件是动态生成的 PDF，用
io.BytesIO写入内存而非落地文件，避免并发时文件覆盖或权限问题 - 测试时用真实邮箱（别只测 Gmail，Outlook 对附件大小限制更严，超过 10MB 直接退信）
SMTP 配置不当引发附件被拦截或超时
带附件的邮件比纯文本大得多，容易触发 SMTP 服务器的大小限制或 TLS 协商失败。Gmail 默认限制 25MB，但很多企业邮箱（如腾讯企业邮）实际阈值是 10MB，且对 application/octet-stream 类型附件更敏感。
立即学习“Python免费学习笔记（深入）”；
- 在
app.config中显式设置：MAIL_MAX_EMAILS = 1（防并发冲撞），MAIL_TIMEOUT = 30（默认 10 秒不够传附件） - 附件总大小超过 5MB 时，优先压缩（如用
PIL.Image缩小 PNG）或改用网盘链接+正文说明，别硬传 - 本地开发用
python -m smtpd -c DebuggingServer -n localhost:1025拦截邮件看原始 MIME 结构，确认Content-Disposition: attachment字段存在且 filename 未被 URL 编码污染
attach() 就完事——路径、MIME、上下文、SMTP 四处任一环节松动，用户就收不到可验证的完整邮件。 
