Python EmailMessage 怎样按内容类型读取附件载荷

用 Python 处理一封 MIME 邮件时，附件载荷并不总是“拿出来就是一段 bytes”。邮件可能同时包含纯文本正文、HTML 正文、图片附件、压缩包，甚至另一封 message/rfc822 邮件。更稳妥的做法是先遍历部件，再看 Content-Type，最后让 EmailMessage.get_content() 按内容类型返回合适的 Python 对象。

官方文档：https://docs.python.org/3/library/email.message.html

记住一条主线：multipart/* 是容器，要继续遍历；文本部件通常读成 str；普通二进制附件读成 bytes；message/rfc822 读成嵌套的 EmailMessage。

先看清邮件的 MIME 部件树

EmailMessage 的 payload 可能是字符串、字节，也可能是子消息列表。只看最外层的 get_content_type()，很容易只看到 multipart/mixed，却漏掉里面真正的附件。

因此读取流程可以拆成三个动作：识别容器、选择遍历范围、在叶子部件上读取载荷。is_multipart() 判断的是 payload 是否包含子部件；它比单纯比较主 MIME 类型更适合处理嵌套消息。

用 walk 或 iter_attachments 选择遍历范围

需要检查整棵邮件树时使用 walk()。它按深度优先顺序返回当前对象及其所有子部件，适合处理嵌套的 message/rfc822。

from email import policy
from email.parser import BytesParser

# 显式使用 default policy，让 EmailMessage 的 content_manager 可用。
with open("message.eml", "rb") as source:
    message = BytesParser(policy=policy.default).parse(source)

# walk 会进入 multipart 和嵌套 message/rfc822 的子部件。
for part in message.walk():
    print(part.get_content_type(), part.get_content_disposition())

如果只关心当前消息的直接附件，iter_attachments() 更合适。它会跳过常见的第一份正文候选；被明确标为 attachment 的正文类型仍会被保留。它不会替你递归进入更深层的嵌套邮件，所以复杂邮件通常需要与 walk() 配合。

按内容类型读取载荷

拿到叶子部件后，不要先假设返回值类型。先读取完整类型和处置方式，再调用 get_content()。标准 raw data content manager 对文本、原始字节和消息对象分别提供不同结果。

提取文件名并保存附件

下面的函数只保存带附件处置标记的非 multipart 部件。文件名可能来自 Content-Disposition 的 filename，也可能来自 Content-Type 的 name 参数；没有文件名时给一个稳定的序号名。

from pathlib import Path
import re

def safe_name(name: str | None, index: int, content_type: str) -> str:
    # 去掉路径分隔符，避免邮件文件名把输出目录带到未知位置。
    cleaned = re.sub(r"[^A-Za-z0-9._-]+", "_", name or "")
    if cleaned in {"", ".", ".."}:
        # 没有可用文件名时，用 MIME 子类型生成可读的兜底名。
        subtype = content_type.split("/", 1)[-1].replace("/", "_")
        cleaned = f"attachment-{index}.{subtype or 'bin'}"
    return cleaned

def save_attachments(message, output_dir: str = "attachments") -> list[Path]:
    destination = Path(output_dir)
    destination.mkdir(parents=True, exist_ok=True)
    saved: list[Path] = []

    # walk 能覆盖嵌套邮件；multipart 本身没有可直接保存的载荷。
    for index, part in enumerate(message.walk(), start=1):
        if part.is_multipart() or not part.is_attachment():
            continue

        content_type = part.get_content_type()
        payload = part.get_content()
        filename = safe_name(part.get_filename(), index, content_type)
        target = destination / filename

        # message/rfc822 返回 EmailMessage，先序列化；其他附件通常是 bytes。
        if hasattr(payload, "as_bytes"):
            target.write_bytes(payload.as_bytes())
        elif isinstance(payload, bytes):
            target.write_bytes(payload)
        else:
            target.write_text(payload, encoding="utf-8")
        saved.append(target)
    return saved

这里的关键不是把所有部件都保存，而是先排除容器和未标记为附件的正文。若业务需要把 inline 图片也保存，应明确把筛选条件扩展到 get_content_disposition() == "inline"，并结合 Content-ID 判断它是否被 HTML 正文引用。

处理编码、嵌套邮件和缺少文件名

文本部件的 get_content() 会依照邮件声明的字符集进行解码，默认错误策略是 replace。需要严格发现坏编码时可以传入 errors="strict"，但应把异常记录到业务日志，而不是把整封邮件静默丢弃。

def read_text_part(part) -> str:
    # 只对 text/* 使用文本读取；二进制部件不应强行解码。
    if part.get_content_maintype() != "text":
        raise TypeError("当前部件不是文本类型")
    return part.get_content(errors="strict")

还要注意两个边界：

• get_content() 直接作用于 multipart/* 时，标准内容管理器会拒绝它；先遍历子部件。
• 解析器最好显式传入 policy=policy.default。EmailMessage 的内容管理方法依赖带有 content_manager 的 policy，旧的 compat32 不适合这组方法。
• 附件文件名来自外部邮件，保存前要清理路径分隔符，并根据业务需要限制长度和扩展名。

一段速查：该选哪个方法

如果只记一个实现顺序，可以写成：walk/iter_attachments → is_multipart → get_content_type → is_attachment → get_content → 按返回类型保存。这样既不会把 multipart 容器当成附件，也不会把 PDF 或图片错误地当成文本。

常见问题

iter_attachments() 为什么返回空列表？

直接对非 multipart 或 multipart/alternative 调用时，它本来就可能返回空迭代器；另外，正文候选会被跳过。需要完整检查时改用 walk()。

为什么读取 PDF 后不是字符串？

这是预期行为。非文本的普通 MIME 部件会以 bytes 返回，直接写入二进制文件即可。

嵌套邮件要不要递归保存？

取决于业务目标。若要提取嵌套邮件内的附件，就把返回的 EmailMessage 交给同一套遍历函数；若只需保留原始邮件，则直接用 as_bytes() 序列化。