Python 3.14 compression.zstd 怎样读写 Zstandard

Python 3.14 把 Zstandard 放进了标准库，入口是 compression.zstd。需要处理一个小的 bytes 对象时用 compress() 和 decompress()；需要读写 .zst 文件时用 zstd.open()；日志、备份或网络流较大时，改用 ZstdCompressor 和 ZstdDecompressor 做增量处理。这样既不用先引入第三方绑定，也不会把整份大文件一次性读进内存。

官方文档：https://docs.python.org/3.14/library/compression.zstd.html

先按数据形态选择 compression.zstd 接口

选择接口的关键不是“哪个函数更快”，而是数据是否已经在内存中。compress(data) 返回完整的压缩字节，适合配置片段、消息体和小型缓存；zstd.open() 把压缩层接到文件对象上，适合备份文件；增量类把输入拆成多块，适合不能一次装入内存的内容。

用 zstd.open 读写 .zst 文件

文件读写最容易落地。写入时使用 "wb"，读取时使用 "rb"；若内容本来就是文本，也可以用 "wt" 和 "rt" 并显式指定编码。读取阶段不要传 level，压缩等级只对写入有意义。

from compression import zstd

payload = "订单号,状态\nA-1001,已完成\n".encode("utf-8")

# 写入新的 Zstandard 文件；wb 表示写入二进制压缩流。
with zstd.open("orders.csv.zst", "wb", level=3) as compressed:
    compressed.write(payload)

# 读取时只提供读取模式；损坏的帧会抛出 zstd.ZstdError。
try:
    with zstd.open("orders.csv.zst", "rb") as compressed:
        restored = compressed.read()
except zstd.ZstdError as exc:
    raise RuntimeError("Zstandard 文件无法读取") from exc

assert restored == payload

这里的 level=3 只是写入示例，不代表所有数据都应固定用这个值。生产环境应在代表性样本上比较压缩时间、输出大小和解压耗时，并把文件扩展名和格式约定写进接口文档。

小对象一次处理，大对象改用增量压缩

内存接口很直观：zstd.compress(data) 返回压缩后的 bytes，zstd.decompress(data) 可以还原。对象可能达到几十 MB 或更大时，不要为了调用方便先执行 read()；可以让压缩器逐块接收输入，并把最后的收尾帧追加到结果中。

from compression import zstd

def compress_chunks(chunks: list[bytes]) -> bytes:
    compressor = zstd.ZstdCompressor()
    output = []
    for chunk in chunks:
        # 每块只产生部分输出，不能把它当成完整的独立文件。
        output.append(compressor.compress(chunk))
    # flush 负责结束当前 Zstandard 帧，不能省略。
    output.append(compressor.flush())
    return b"".join(output)

encoded = compress_chunks([b"header\n", b"records\n"])
decoded = zstd.decompress(encoded)
assert decoded == b"header\nrecords\n"

参数和归档兼容性要先写清楚

简单调参时可以传 level；需要窗口大小、校验和或多线程等高级设置时，使用 options 字典。两者不能同时传入，参数上下界可通过 CompressionParameter 的 bounds() 查询。解压使用训练字典时，必须提供压缩端使用的同一份 ZstdDict，不能把字典当作普通密码。

Python 3.14 的 zipfile.ZIP_ZSTANDARD 和 tarfile 的 r:zst/w:zst 也依赖 compression.zstd。ZIP 写入使用方法 ID 93，读取兼容 20 和 93；旧工具可能完全不认识 Zstandard，因此交付归档前要确认接收方版本。若导入失败，先判断是缺少可选模块、归档方法不支持，还是压缩帧本身损坏，不要只盲目降低压缩等级。

常见问题

Python 3.13 能直接 import compression.zstd 吗？

不能把它当作 Python 3.14 之前的内置接口。需要兼容旧解释器时，应明确使用第三方绑定或继续采用 gzip、bz2、lzma 等已有模块，并把依赖写入部署说明。

为什么 zstd.open 读文件时传 level 会报错？

level 是压缩参数，读取阶段没有压缩动作。把读取调用改为 zstd.open(path, "rb")，需要高级解压设置时再传 options。

compress() 和 ZstdCompressor 有什么区别？

前者面向已经在内存中的完整 bytes，后者允许分块输入。只要数据来源是文件、网络或生成器，就优先考虑增量接口，并确保结束时调用 flush()。