企业官网建设流程全解析

• 图像处理

PyMuPDF 是一套高性能的 Python 库，专注于 PDF（及其他格式）文档的数据提取、分析、转换与操作，底层基于 Artifex 的 MuPDF 引擎。本文以仓库中的权威变更记录 changes.txt（被文档页 docs/changes.rst 通过.. include:: ../changes.txt直接引用）为主线，系统梳理从 2016 年的 1.9.1 到当前 1.28.2 的完整演进脉络，重点解读每个版本的核心新增功能、破坏性变更与关键修复，帮助你理解「哪个功能在哪个版本引入」「升级到新版本前需要注意什么」，并为版本选型与代码迁移提供可验证的依据。

说明：本文所述版本号、功能引入时间与修复内容均以 changes.txt 原文为准；当前仓库的构建版本定义可参见 setup.py（version_p = '1.28.2'、version_mupdf = '1.28.2'），两者一致。

一、如何阅读这份变更日志：结构与格式约定

docs/changes.rst本体只有 5 行，是一个典型的 Sphinx 组装骨架：

.. include:: header.rst .. include:: ../changes.txt .. include:: footer.rst

真正的内容全部位于仓库根目录的 changes.txt（约 3000 行）。变更日志采用如下统一格式：

• 每个版本以**Changes in version X.Y.Z** (日期)开头；
• 随后列出本版本对应的MuPDF 基础版本（例如 1.28.2 使用 MuPDF-1.28.2）；
• Fixed issues:小节列出修复的 GitHub issue 编号（如#5112）；
• Other:小节列出新增 API、行为变化、构建与分发调整；
• 文档内通过.. codespell:ignore-begin/.. codespell:ignore-end包裹历史遗留的旧式命名记录，以便拼写检查工具跳过。

阅读建议：若你关心「某 API 何时出现」，直接在 changes.txt 中搜索该 API 名称；若关心「某 issue 何时修复」，搜索其编号即可。变更日志中大量使用**Fixed** <编号>形式，编号同时附带原始 GitHub issue 链接（本文按仓库规范不输出外部链接，仅保留编号便于对照）。

二、近一年核心版本：1.26.0 → 1.28.2 的功能主线

最近几个版本是 PyMuPDF 现代化重构的集中体现，也是升级用户最需要关注的区间。

2.1 1.28.2（2026-08-06）：表单层级、确定性与安全加固

• 表单（Form）能力大幅增强：新增对表单字段层级（form field hierarchies）、单选按钮组（radio button groups）与字段别名（widget aliases）的支持；
• 确定性输出：Document.save()新增reproducible/deterministic输出选项（issue #5056），可省略 MuPDF 版本横幅与 Producer 信息，便于生成可复现文件；
• Page.find_tables()参数扩展：新增use_layout: bool = True、union: bool = False、refine: bool = False三个参数，并显著提升速度；
• fitz兼容层弃用警告：导入旧名fitz模块时改为通过warnings.warn()发出FutureWarning（替代此前直接向控制台打印的做法）；
• 分发扩展：新增 windows-arm64 wheel；支持PYMUPDF_SETUP_MUPDF_VS_UPGRADE构建选项；
• 重要修复：修复clean_contents(sanitize=True)丢失字形定位的回归（#5054）、Page.remove_rotation()在 90°/270° 旋转页上导致注释消失或位移（#5059）、get_texttrace()在长运行进程中的None引用泄漏（#5042）、字体子集化段错误（#5049）等。

2.2 1.28.0（2026-06-29）：Archive 参数、CSS 应用与跨格式保存

• pymupdf.Document.__init__()新增archive参数：支持直接以压缩包形式打开文档；
• Document.convert_to_pdf()现在同时生成链接；
• Document.save()支持将非 PDF 文档直接保存为 PDF 格式；
• 新增Document.apply_css()方法；
• Pyodide wheel 正式发布到 PyPI；
• 修复了表单公式渲染为黑块（#5001）、矢量图形（线条画）不完全涂黑（#4936）、write_images()配合garbage>1保存破坏字体 xref（#4896）等问题。

2.3 1.27.x（2026-02 ~ 2026-04）：OCR 全面化与文本裁剪常量

1.27.2 起对get_textpage_ocr()做了重要改进：部分 OCR 现在覆盖页面全部非可读文本区域（包括矢量图形与含不可识别字符的文本），而不再局限于图片内部（#3842）。

1.27.1 新增了pymupdf.TEXT_CLIP常量、Document.save()的raise_on_repair参数与Document.repair()方法，并移除对 MuPDF < 1.26 的支持。

2.4 1.26.x（2025-05 ~ 2025-12）：重写图像、页面裁剪与表单元数据

• Document.rewrite_images()（1.26.1 新增）：用于减小文件体积、转换图片格式或转换色彩空间；
• Page.clip_to_rect()（1.26.4 新增）：将页面裁剪到指定矩形；
• Page.get_image_info()与get_drawings()持续修复缓存与属性解析问题；
• Shape类正式公开为pymupdf.Shape（1.26.3），并移除了pymupdf.utils.Shape重复定义（1.26.5）；
• 表格模块（1.26.3）新增表格单元格 Markdown 输出支持；
• 1.26.6 起支持的 Python 版本为 3.10–3.14（1.26.5 时为 3.9–3.14）。

2.5 1.25.x（2024-12 ~ 2025-03）：注释富文本、表单字段与 span 字典增强

• FreeText 注释新增FreeTextCallout子类型与富文本（rich text）支持（1.25.3）；
• insert_text*()系列新增miter_limit参数，用于抑制长斜接产生的尖刺（spikes）；
• Document.insert_pdf()支持复制 Widget（表单字段）；
• span 字典新增bibi键，char 字典新增synthetic键；span 字典还新增char_flags成员（可检测不可见文本）；
• Pixmap.pil_image()新增（1.25.2），直接返回 Pillow Image 对象。

三、表格识别（Table Detection）功能的演进

表格识别是 PyMuPDF 近年持续投入的功能，其演进脉络贯穿 1.23.x 与 1.24.x，源码实现在仓库的 src/table.py 及 src/_table_headers.py、src/_table_refine.py、src/_table_spans.py、src/_table_union.py 等模块中（测试见 tests/test_tables.py）。

• 1.23.0：Page.find_tables()首次引入，可在任意受支持文档页上定位表格并按单元格提取内容；
• 1.23.13：修复to_pandas()的list index out of range（#2979），以及对一个文档调用find_tables()改变后续文档 bbox 的串扰问题（#3001）；
• 1.23.16：lines_strict策略排除纯填充的矢量图形；
• 1.23.19：允许在查表时加入用户自定义的"虚拟"矢量图形，并加速矩形相交判断；
• 1.23.24：修复垂直文本处理（#3148）与矢量图形簇的错误分离（#3179）；
• 1.24.0：新增将表格输出为 Markdown 字符串的方法；修复表头对象计算错误，允许None单元格值（在 pandas DataFrame 场景按需解析），并正确纳入线条起止点以计算簇包围盒；
• 1.28.2：find_tables()新增use_layout、union、refine三个参数，并修复启用 layout 时返回零单元格表格导致Table.bbox抛ValueError的问题（#5030）。

从源码结构看，表格模块被拆分为多个职责单一的文件：_table_headers（表头识别）、_table_refine（表格细化）、_table_spans（单元格跨度）、_table_union（表格合并），共同支撑Page.find_tables()的完整流程。

四、API 命名体系的重构：camelCase → snake_case 与 fitz → pymupdf

变更日志中最具影响力的演进之一是 API 命名与模块名的两次大迁移，直接影响所有存量代码。

4.1 命名风格迁移（1.18.x 起）

• 1.18.3：以Annot类为试点，启动将 camelCase/mixedCase 命名的属性和方法转换为lower_case_with_underscores风格的长期工程；旧名称继续保留以避免代码破坏，但不再出现在文档中；
• 1.18.14：snake_case 命名基本完成，文档末尾新增 Deprecated 章节，提供新旧名称映射表；
• 迁移示例：Page.getText→Page.get_text、Page.searchFor→Page.search_for、Document.save（不变）、Pixmap.getPNGdata→Pixmap.tobytes别名等。

4.2 模块名迁移：fitz → pymupdf（1.24.3）

• 1.24.3：Python 模块正式更名为pymupdf，fitz仍作为向后兼容别名保留；
• 1.28.2 起：导入旧名fitz会输出警告，且使用warnings.warn()+FutureWarning（此前 1.28.0 开始为控制台打印）；
• 对应地，1.24.2 从发行版中移除了旧的 classic 实现（fitz_old模块）。

4.3 底层实现的重写：classic → rebased（1.23.x）

• 1.23.0：引入全新的 "rebased" 实现，作为fitz_new模块提供，可import fitz_new as fitz直接替换；同时把与 Python 无关的 MuPDF 库拆分到独立的PyMuPDFbwheel；
• 1.23.9：默认切换到 rebased 实现，旧 classic 实现通过import fitz_old as fitz保留；
• rebased 实现改进了类型标注（1.26.5 起所有类方法显式定义，不再动态赋值）、去除了(*args, **kwargs)式的 API 签名（1.23.8）、并支持 MuPDF 新的 Python 异常类；
• 1.24.2 起 classic 实现从发行版移除。

五、文本提取与搜索的核心能力演进

文本提取是 PyMuPDF 最常用的能力，其 API 与内部行为在多个版本中持续增强：

• 1.16.3：get_text()的 "dict"/"rawdict" 变体移植到 C 实现，文本型文档上速度接近翻倍；
• 1.18.2：文本搜索支持任意数量的命中结果（移除hit_max参数）、新增clip参数限定搜索区域、支持跨行断词连字符检测；
• 1.19.1：get_text()支持sort参数，输出按标准阅读顺序（左上→右下）排序；
• 1.19.2：文本搜索与提取默认开启TEXT_MEDIABOX_CLIP标志，自动抑制完全位于页面 MediaBox 之外的字符，不再需要手动传clip=page.rect；
• 1.22.0：行为变化——文本提取现在包含与 clip 矩形重叠的字形，此前仅包含完全位于 clip 内的字形；
• 1.23.5：支持额外的词分隔符（extra word delimiters）；
• 1.24.14：确保get_text()返回的 words 不混入 RTL/LTR 字符；
• 1.19.0 起：新增get_texttrace()（低层字符属性，含 "sequence number" 指示页面绘制顺序）与get_bboxlog()（返回页面对象矩形列表，序列顺序可判断对象遮挡关系）。

文本提取的 flags 体系

变更日志多次提及TEXT_*系列 flags（如TEXT_MEDIABOX_CLIP、TEXT_INHIBIT_SPACES）。1.19.6 还新增了便捷常量TEXTFLAGS_WORDS（对应get_text("words")）等默认标志组合。这些常量的具体位定义可查阅 docs/textpage.rst 中的文本提取标志章节。

六、OCR（Tesseract 集成）能力演进

PyMuPDF 从 1.19.0 开始集成 Tesseract OCR（该能力源自 MuPDF 1.18.0）：

• 1.19.0：OCR 功能正式落地——Pixmap.pdfocr_save()/pdfocr_tobytes()生成带 OCR 文本层的单页 PDF；Page.get_textpage_ocr()对页面执行 OCR 并把结果与常规内容合并进TextPage；文本搜索/提取方法新增textpage参数以复用已创建的 TextPage；
• 依赖说明：OCR 需要独立安装 Tesseract，MuPDF 仅需要其tessdata文件夹路径，通过环境变量TESSDATA_PREFIX提供；
• 1.19.1：get_textpage_ocr()新增dpi参数控制 OCR 质量，并可选择整页 OCR 或仅 OCR 页面显示的图片；
• 1.22.5：新增get_tessdata()函数定位 Tesseract 语言包目录，OCR 函数支持tessdata参数；
• 1.27.2：部分 OCR 覆盖范围从"图片内"扩展到页面全部非可读文本区域（矢量图形、含不可识别字符的文本）。

仓库相关测试见 tests/test_tesseract.py，文档见 docs/recipes-ocr.rst 与 docs/ocr/tesseract-language-packs.rst。

七、内容编辑、净化与信息安全

7.1 涂黑（Redaction）

• 1.16.11：新增Page.add_redact_annot()与Page.apply_redactions()，支持涂黑删除文本；
• 1.16.12：增强——被涂黑矩形包含的图片与 XObject 会被移除，部分重叠则被背景色覆盖；可指定 overlay 文本插入矩形区域；
• 1.17.0：与涂黑重叠的图片被永久擦除重叠区域，重叠链接被移除，与 PDF 规范完全同步；
• 1.24.0：支持涂黑矢量图形；
• 1.28.0：修复矢量线条画涂黑不完整（#4936）。

7.2 净化（Scrub）与流处理

• 1.16.14：新增Document.scrub()移除 PDF 中的潜在敏感数据；1.18.10 加固了 JavaScript 对象移除；1.18.7 新增thumbnails参数以同时删除页面缩略图；1.18.2 新增redact_images选项；
• 1.27.1：Document.save()新增raise_on_repair参数、新增Document.repair()；
• 1.24.1：Document.save()/ez_save()/write()新增use_objstm、compression_effort、preserve_metadata参数；1.24.10 起对象流与线性化（linearization）不能同时使用，尝试同时启用会抛出异常（#3603），而 1.26.0 起完全移除了 PDF 线性化支持（save(linear=True)将抛异常）。

八、PDF 生成、表单字段与低层对象操作

8.1 表单字段（Widgets）

• 1.13.2：PDF 表单支持起步——Document.is_form_pdf、Annot.widget_type等属性；
• 1.13.11：可添加 Text、CheckBox、ListBox、ComboBox 四种表单字段；
• 1.13.12：Annot.update_widget()支持修改已有字段（含字段值）；ListBox/ComboBox 可选值列表统一为Widget.choice_values；
• 1.25.3：Document.insert_pdf()支持复制 Widget；1.22.x修复了单选按钮组的状态同步问题（#2333、#2391）；
• 1.28.2：支持表单字段层级、单选按钮组与字段别名；
• 变更日志特别提醒：1.16.0 起注释（annotations）与表单字段（widgets）是两条独立的对象链——Page.first_annot/Annot.next不会再遍历到 widget，必须使用Page.first_widget/Widget.next。

8.2 PDF 生成

• 1.11.0：Document.insert_page()（含文本）、Page.insert_image()、Page.insert_text()奠定 PDF 内容生成基础；
• 1.11.1：Shape类引入，统一页面绘图 API；
• 1.22.0：新增/PageMode、/PageLayout、/MarkInfo的 getter/setter、Document.version_count（增量保存次数 + 1）、is_fast_webaccess（是否线性化）等属性；
• 1.24.2：Document.bake()把注释/字段固化为永久内容；Page.cluster_drawings()按几何邻近度聚类矢量图形；apply_redactions()新增text参数。

8.3 低层 xref 操作

从 1.16.8 起提供Document.xref_object、xref_stream、xref_stream_raw、pdf_trailer、pdf_catalog、update_object、update_stream等系列方法；1.18.7 新增xref_get_keys/xref_get_key/xref_set_key（1.18.10 起支持用-1访问 trailer 字典）；1.19.5 新增Document.xref_copy。相关方法文档集中在 docs/document.rst 与 docs/lowlevel.rst。

九、打印、渲染与图片处理

• Pixmap 渲染：1.16.0 起Page.get_pixmap()/Annot.get_pixmap()支持annots参数抑制注释渲染；1.19.2 起支持dpi参数（此时matrix被忽略）；1.10.0 起 alpha 通道可选，显著减小像素图体积（CMYK -20%、RGB -25%、GRAY -50%）；
• 图片提取：extract_image()自 1.14.9 起对 JPX 图片返回原始格式（避免转 PNG 导致的体积剧增）；Page.get_image_bbox()/get_image_rects()持续改进；1.17.5 新增Page.get_svg_image()的text_as_path选项生成更小的 SVG；
• 颜色：1.14.12 起绘图与文本插入支持 GRAY/CMYK 色彩空间；1.19.1 起get_drawings()/get_cdrawings()自动将颜色转为 RGB 元组；
• 抗锯齿：1.16.14 起Tools.set_aa_level()可控制抗锯齿级别。

十、安全与稳定性：内存泄漏、崩溃与资源问题修复趋势

变更日志中占比最高的是内存泄漏、段错误（segfault）与资源管理修复，这反映 PyMuPDF 与 MuPDF 底层 C 代码交互的复杂性：

• 内存泄漏：insert_pdf()（#1417/#1418、#3201、1.18.0 修复 #669）、get_text("rawdict")（#362/#290）、extract_blocks的文本对象引用（#5067）、widgets()迭代（#4751）等均有针对性修复；
• 段错误：apply_redactions()与透明图片重叠（#1824）、get_drawings()（#1971）、subset_fonts()字体子集化（#5049）、Pillow 混用（#4762）等；
• 资源管理：1.13.19 起 Python 3 构建全程使用 Python 内存管理（替代原生malloc()）；1.24.6 修复了并发使用时的临时文件名冲突；
• 防御性增强：1.23.0 起对/Annots数组中的非法成员（null、非字典项）跳过处理；1.18.1 起检测并恢复页面资源循环依赖。

从仓库结构看，tests/目录中存在大量以 issue 编号命名的回归测试（如 tests/test_5044.py、tests/test_4942.py、tests/test_4670.py 等），与变更日志中对应编号一一呼应，可作为"该修复确有回归测试覆盖"的佐证。

十一、Python 版本支持与构建分发演进

• Python 支持范围：1.23.0 放弃 Python-3.7；1.24.12 放弃 3.8、新增 3.13（当时支持 3.9–3.13）；1.26.5 支持 3.9–3.14；1.26.6 起为 3.10–3.14；最新变更还提到适配 Python-3.15 预发布版与 free-threading（自由线程）Python；
• Wheel 策略：1.24.11 起 wheel 使用 Python Stable ABI——每个平台一个 wheel，兼容所有受支持的 Python 版本，且不再有独立的 PyMuPDFb wheel；1.28.2 新增 windows-arm64 wheel；1.24.6 起增加 musllinux x86_64 wheel；
• 构建系统：1.22.0 引入pyproject.toml；1.20.0 起从 sdist 构建时自动下载并编译所需 MuPDF 源码，无需预装 MuPDF；1.23.26 起 sdist 不再包含 MuPDF 源码（构建时自动下载）；
• 版本信息属性：1.24.6 起提供pymupdf.pymupdf_version、pymupdf.mupdf_version、pymupdf.pymupdf_date；1.23.7 起提供fitz.pymupdf_version_tuple（如(1, 23, 6)）；1.26.1 起pymupdf_date与VersionDate不再随版本填充（均为 None），且版本号不再携带发布日期。

十二、升级与迁移检查清单

综合变更日志中的破坏性变更（Breaking Changes），升级到新版前建议逐一核对：

1. 模块导入：import fitz仍可用但会告警（1.28.2 起为FutureWarning），新代码请使用import pymupdf；
2. 命名风格：camelCase 旧方法（如getText、searchFor）已不再出现在文档中，新代码应使用 snake_case 形式（get_text、search_for）；
3. 线性化：Document.save(linear=True)自 1.26.0 起直接抛异常（线性化支持已移除）；对象流 + 线性化组合自 1.24.10 起即被禁止；
4. 保存行为：Document.save()自 1.28.0 起可保存非 PDF 文档为 PDF；需要可复现输出时使用 1.28.2 的确定性保存选项；
5. 注释与表单分离：遍历注释不会经过表单字段，表单字段需走first_widget链；
6. OCR 依赖：OCR 功能需要独立安装 Tesseract 并配置TESSDATA_PREFIX；
7. Python 版本：确认你的 Python 版本在支持范围内（当前为 3.10–3.14）；
8. 剪贴行为：1.22.0 起文本提取对 clip 矩形的包含规则从"完全包含"变为"重叠即包含"，涉及精确坐标计算的场景需复核。

十三、如何验证与进一步阅读

• 对照源码：changes.txt 提到的 API 大多能在 src/pymupdf.py、src/fitz_table.py、src/fitz_utils.py 中找到实现；构建与版本定义见 setup.py；
• 对照测试：tests/目录下以 issue 编号命名的测试文件（如 tests/test_5044.py、tests/test_5044.py 等）直接对应变更日志中的修复项；
• 安装方式：pip install pymupdf即可；从源码构建时 sdist 会自动下载对应 MuPDF 版本；
• 配套文档：各功能的详细 API 说明分散于 docs/document.rst、docs/page.rst、docs/annot.rst、docs/textpage.rst、docs/pixmap.rst 等文件，变更日志可视为这些文档的"时间轴索引"。

结语

从 2016 年的 1.9.1 到 2026 年的 1.28.2，PyMuPDF 走过了从"PDF 文本提取工具"到"覆盖提取、分析、转换、生成与安全处理的完整文档处理平台"的演进之路。这份变更日志既是版本索引，也是理解库设计决策（命名迁移、实现重写、功能取舍）的第一手资料。升级时，以本文第十二节的检查清单为依据，结合 changes.txt 中对应版本段的原文，即可做出稳妥的迁移决策。

• 图像处理