PDF 库依赖与渲染差异

【踩坑实录】PDF 库依赖与渲染差异

▍现象
电子书管理工程的格式支持矩阵里 PDF 是硬需求（大量电子书资产是 PDF）。桌面链路的 PDF 处理（解析与渲染）依赖一组桌面组件，移植环境不可用。换库之后又冒出渲染差异：同一份 PDF 在不同渲染引擎下的呈现有细节差异（字体替换、图像色彩、注释层）。

▍定位与替换
PDF 处理的两个层面分开换：解析层（提取文本、目录、元数据）与渲染层（页面成图）。工程的选型：轻量纯引擎（pypdfium2 类）同时覆盖两层——纯运行时依赖（跟着 Python 环境走，没有原生库的交叉编译负担）、渲染走成熟内核（长期演进的渲染实现，一致性有保障）。验证方式值得借鉴：互联网真实语料几十本、跨十种格式的转换全过测试——真实世界的 PDF（损坏的、加密的、多字体的、扫描的）比标准样本残酷得多。

▍渲染差异的坑位
字体替换差异（原文档字体没嵌入时的替换策略——不同引擎的回退字体不同，观感差异由此而来）；色彩管理（图像的色彩配置处理差异）；注释与表单层（有的引擎渲染注释层有的忽略——同一份带批注的文档呈现不同）。对策：差异基线（关键样本文档在各引擎的渲染对拍——选型时就知道差异在哪）；用户预期（导出与显示的引擎一致性说明——同一引擎内自洽比跨引擎绝对一致更实际）。

▍根因抽象
格式处理类依赖的移植，选型权重要加一项：语料覆盖度（引擎对真实世界文档的鲁棒性）——功能清单都写着支持，真实语料见真章。

▍方法论沉淀
格式类替换的验收用真实语料库（几十份来源各异的真实文档），标准测试集只能证明基本盘。

纯引擎替换与真实语料验证的完整记录在电子书工程实录，apps 板块 56 篇欢迎对照。