根本原因是未正确构建multipart/mixed与multipart/alternative嵌套结构：外层mixed容纳html正文和附件，内层alternative提供html与纯文本fallback；直接赋值msg.html后加附件会导致附件丢失或渲染异常。
Flask-Mail 发送带附件的 HTML 邮件为什么总失败？
根本原因通常是 Message 对象构建时没正确设置 multipart/alternative 和 multipart/mixed 的嵌套结构。Flask-Mail 默认用 Message 构造纯文本或 HTML 邮件，但一旦加附件，必须手动构造多部分 MIME 树：外层是 multipart/mixed（容纳 HTML 正文 + 附件），内层 HTML 部分得是 multipart/alternative（兼容纯文本 fallback）。直接在 msg.html 赋值后加附件，附件会丢失或正文渲染异常。
实操建议：
- 不要依赖
msg.html = "..."单独赋值，改用msg.attach()显式添加 HTML 部分和附件 - HTML 内容需封装为
MIMEText(..., 'html', 'utf-8')，并设Content-Disposition: inline - 附件要用
MIMEApplication或MIMEBase，设Content-Disposition: attachment - 务必调用
msg.attach()按顺序添加：先 HTML 部分（inline），再附件（attachment）
如何用 Flask-Mail 实现真正的异步发送？
Flask-Mail 本身**不提供异步能力**，mail.send() 是同步阻塞调用。所谓“异步”必须靠外部机制实现，常见错误是误以为设置 MAIL_SUPPRESS_SEND=True 或用线程池包装就安全了。
实操建议：
- 用
threading.Thread最轻量，适合低频邮件（如注册确认），注意避免主线程退出导致子线程被杀 - 生产环境优先选
celery，把mail.send()封装成 task，配置 broker（如 Redis）和 worker - 若用线程，必须在新线程中重新创建
app.app_context()，否则current_app报错RuntimeError: Working outside of application context - 别在 Flask 请求上下文中直接
time.sleep()或长耗时操作——这会卡住整个 werkzeug worker
附件路径、中文名、大文件怎么处理？
附件读取失败、乱码、超时，90% 出在路径和编码上。Flask-Mail 不处理文件流生命周期，全靠你传入已打开的二进制内容。
实操建议：
- 路径用
os.path.join(app.root_path, 'static', 'files', filename)，避免相对路径歧义 - 中文文件名必须用
Header编码：header = Header(filename, 'utf-8').encode()，再设part.add_header('Content-Disposition', 'attachment', filename=header) - 大文件（>5MB）别一次性读入内存，改用
with open(path, 'rb') as f: part.set_payload(f.read())—— 这仍会加载全部内容；更稳妥是用生成器分块读，但 Flask-Mail 不支持流式 attach，所以实际应提前压缩/切片或走云存储链接 - 发送前校验文件是否存在、可读：
os.path.isfile(path) and os.access(path, os.R_OK)
HTML 中的本地图片、CSS 样式为何不显示？
HTML 邮件客户端（Outlook、Apple Mail 等）几乎不执行 CSS 外链或 JS，且拒绝加载本地 file:// 图片。把 <img src="static/logo.png"> 直接塞进 HTML，收件方看到的是红叉。
实操建议：
- 所有图片必须转为内联 base64：
with open(img_path, 'rb') as f: b64 = base64.b64encode(f.read()).decode()，然后<img src="data:image/png;base64,%7Bb64%7D"> - CSS 必须写成
<style>...</style>内联样式，且只用最简属性（float、display: table在 Outlook 中表现极差） - 绝对不要用
@import或<link rel="stylesheet"> - 字体用系统通用栈：
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif
附件和 HTML 渲染的细节堆叠起来，很容易漏掉一环就发不出或显示异常。最常被忽略的是 MIME 部分的 Content-ID 关联（用于 HTML 中引用内联图片）和线程中应用上下文的显式激活——这两处出问题，日志里往往没有直接报错，只能收不到邮件或内容错乱。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
