0xZOne's Notes

I. 执行摘要：推理框架选择的战略影响

本报告旨在为面临关键技术选型的人工智能架构师和技术决策者，提供一份关于 ONNX Runtime (ORT) 与 LiteRT Next 两种机器学习推理框架的详尽、深入的技术对比。选择推理框架是一个具有高度战略意义的决策，它将深刻影响产品的性能、成本、开发敏捷性和长期可维护性。

本文的核心论点是：ONNX Runtime 与 LiteRT Next 代表了两种截然不同且在很大程度上相互排斥的设计哲学。

• ONNX Runtime (ORT) 是一个**“通用、成熟的泛化平台”**。其核心设计目标是最大的灵活性、最广泛的硬件兼容性和对 ONNX 开放标准的完全支持 [1, 2, 3, 4]。它通过一个“执行提供程序”（Execution Provider）模型 [5, 6, 7]，充当一个上层API到底层硬件加速库的“抽象总线”或“联邦路由器”。

• LiteRT Next 则是一个**“高度特化、性能驱动的专业引擎”**。其设计从一开始就聚焦于轻量化，旨在为资源受限的边缘和移动设备提供极致的低延迟和最小的资源占用 [8, 9]。它采用“垂直集成”的架构，牺牲了ORT的灵活性，以换取对其内部组件（如图优化、内存管理和执行）的完全控制。

这两种哲学的直接碰撞导致了在各个关键维度上的显著差异：

1. 核心架构： ORT 的水平灵活性（通过可插拔的执行提供程序EPs [5, 7]）与 LiteRT Next 的垂直集成（通过紧密耦合的 InferCore、Device 和 Transform 组件）形成鲜明对比。

2. 性能表现： 这种架构差异直接转化为性能。LiteRT Next 在特定的边缘计算场景（例如 ARM CPU）上展现出卓越的低延迟性能 [10, 9]。相反，ORT 凭借其对专用后端（如 NVIDIA TensorRT [11, 12]）的无缝集成，在服务器端（云端）GPU 推理吞吐量上占据绝对主导地位。

3. 资源占用： LiteRT Next 在设计上即追求最小化，其在二进制文件大小和运行时内存占用方面具有显著优势。

4. 生态与兼容性： ORT 提供了对庞大 ONNX 算子集（Opset）[2, 13] 的无与伦比的兼容性 和一个极其成熟的生态系统。LiteRT Next 则故意选择了一个受限的算子集 [14]，专注于主流模型，这既是其轻量化的原因，也是其应用的主要风险点。

战略建议摘要：

• 选择 ONNX Runtime：适用于需要最大化灵活性、处理多样化和快速迭代的模型库、以及需要在异构企业环境（云、边缘、PC）中部署的场景 [3, 4]。当“模型必须能运行”的优先级高于“模型必须以极致效率运行”时，ORT 是默认的安全选择。

• 选择 LiteRT Next：适用于目标硬件平台固定、模型类型已知且兼容、且业务需求对延迟、功耗或内存占用有极端要求的资源受限场景（如嵌入式系统、移动应用）[8, 15]。选择 LiteRT Next 是一个高回报但也高风险的特化决策，必须以严格的模型兼容性验证（Proof-of-Concept）为前提。

本报告将从基础架构、实证性能、模型优化、运维能力和生态系统等多个层面，对这些差异进行深入的解构和分析。

II. 基础架构与设计哲学：一次对比解剖

两种框架在性能和功能上的所有差异，最终都源于它们在设计之初所做出的根本性架构权衡。

II.A ONNX Runtime (ORT)：水平联邦抽象模型

ORT 的核心设计原则不是要构建一个庞大、单一的（monolithic）推理引擎，而是要成为一个可插拔的**“执行提供程序”（Execution Providers, EPs）**的管理器 [6]。ORT 本身更像是一个“推理总线”（Inference Bus）或“高级路由器”。

其工作流程如下：

1. ORT 加载一个 .onnx 模型文件 [13]。

2. 它解析计算图（Graph），并根据用户配置的 EP 优先级列表（例如：首先尝试 TensorRT，其次 CUDA，最后 CPU）对图进行分区（partitioning）[5]。

3. 图的每个分区被分配给最适合它的 EP。例如，大部分计算密集型操作被分配给 TensorRT EP [5, 7]，而 TensorRT 不支持的零散操作则回退（fallback）到 CUDA EP 或 CPU EP。

4. 在运行时，ORT 负责协调数据在这些 EP 之间的（可能存在的）拷贝，并调用各 EP 的 Compute 函数。

ORT 生态系统中的关键 EPs 包括 CUDA、TensorRT、DirectML (Windows)、CoreML (Apple)、NNAPI (Android) 和 OpenVINO (Intel) [5, 7]。

这种设计的精妙之处在于 ORT 的**“联邦”特性。以最高性能的 ONNX-TensorRT EP 为例，ORT 并不尝试自己去实现 TensorRT 级别的图融合和内核优化。相反，它选择**“委托”（delegate）。它将 ONNX 子图交给 TensorRT（一个专有的、高度优化的闭源编译器）[12]，让 TensorRT 执行其激进的、针对特定 NVIDIA GPU 架构的优化 [16]，然后 ORT 只负责在运行时调用这个编译好的 TensorRT 引擎。

ORT 的首要设计目标是提供一个单一、稳定、跨平台的 API，使开发者能够透明地接入所有硬件供应商（NVIDIA, Intel, Apple, Qualcomm 等）各自提供的、最顶尖的优化内核 [1, 17, 6]。

• 优势：无与伦比的硬件可移植性 [3, 4]；自动利用供应商的最佳实践；庞大的生态支持。

• 劣势：引入了一层（尽管很薄）的抽象开销；性能依赖于各个 EP 的实现质量；在 EP 之间切换可能导致微小的数值差异。

II.B LiteRT Next：垂直整合的特化堆栈

与 ORT 的联邦模型相反，LiteRT Next 采用了**“垂直集成”**的架构。它的核心组件，包括 InferCore（推理核心）、Device（设备抽象）和 Transform（图转换），是作为一个单一、内聚的系统被共同设计的。

LiteRT Next 的设计哲学是牺牲灵活性以换取控制力。

1. Transform：这不仅仅是一个简单的优化通道，它扮演着一个**“事实上的编译器”**的角色。它在模型加载时（或离线时）对计算图进行深度重构和优化 [15, 18]，使其转换成 InferCore 最容易高效执行的内部表示（IR）。

2. InferCore：这是框架的核心执行引擎，被设计为精简、高效，专注于执行由 Transform 准备好的优化图 [15, 19]。

3. Device：这是 LiteRT Next 的内部硬件抽象层（HAL），用于对接 CPU、GPU (OpenCL/Metal) 和 NPU [9, 14, 20]。

这里必须指出 Device 层与 ORT 的 EP 之间的关键区别：ORT 的 EP 主要是**“委托”给外部框架（如 TensorRT）[6]；而 LiteRT Next 的 Device 层（在此语境中常被称为 Delegates）则是为其自有的、内部的**计算内核提供硬件访问 [10, 9]。例如，当 LiteRT Next 在 GPU 上运行时，它不会调用 TensorRT 或 OpenVINO，而是通过 OpenCL 或 Metal 执行自己实现的卷积、矩阵乘法等内核 [9, 14]。

这种垂直整合的架构，使 LiteRT Next 能够对其执行的每一步进行深度、端到端的协同优化。Transform 组件 可以精确地知道 Device 层的 OpenCL 内核 对哪种数据布局（Layout）或操作融合（Fusion）最友好，从而在图优化阶段就生成最优的执行计划。

• 优势：对执行和内存的完全控制；能够实现跨组件的深度优化；极低的抽象开销。

• 劣势：可移植性受限于其内部 Device 层的实现；算子支持范围受限 [14]；生态系统封闭。

II.C 执行策略与并发处理

两种框架最深刻的差异体现在它们的运行时执行模型上，这直接解释了它们在不同平台上的性能差距。

LiteRT Next 的双模执行

LiteRT Next（源自 TensorFlow Lite）提供了一个关键的配置选项：Static（静态）模式与 Dynamic（动态）模式。

• Static 模式：在此模式下，LiteRT Next 表现得像一个**预编译（Ahead-of-Time, AOT）**框架。在模型加载阶段（甚至离线阶段），Transform（即 Converter [15]）和 MemoryPlanner 会分析计算图（假定输入形状固定），生成一个完全确定性的、静态的执行计划，并预先分配好所有中间张量（Tensor）所需的内存。在推理时，InferCore（即 Interpreter [15, 19]）几乎不执行任何动态决策或内存分配；它只是简单地、按顺序地执行一个预先计算好的扁平化操作列表。

• Dynamic 模式：此模式更接近传统的即时编译（Just-in-Time, JIT）方法，类似于 ORT 的默认行为，用于处理动态输入形状或更复杂的模型结构。

ONNX Runtime 的动态方法

ORT 默认被设计为一个动态执行框架。当模型加载时，它会应用图优化 [21]，并通过内存分配器 准备内存池，但实际的执行计划和内存使用是在每次 run() 调用时根据输入动态确定的。虽然 ORT 的 .ort 格式 [5] 引入了 AOT 优化的概念，但其运行时的核心仍然是一个需要管理 EP 抽象和动态内存的调度器。

静态执行：LiteRT Next 在边缘侧的“杀手锏”

LiteRT Next 的 Static 模式 是其在边缘端性能 和内存占用 上取得优势的核心原因。

在一个性能强大的服务器 GPU（如 NVIDIA A100）上，ORT 的动态调度和 EP 抽象开销（几微秒）相比于庞大的计算时间（几十毫秒）可以忽略不计。然而，在一个资源受限的 ARM CPU（如 Cortex-A78）上，运行时开销（Runtime Overhead）（例如：内核查找、内存分配、操作调度）可能占到总推理时间的很大一部分。

LiteRT Next 的 Static 模式通过在“编译时”预先完成所有这些工作，几乎消除了所有运行时开销。这使得它在边缘 CPU 上的执行效率极高 [10, 9]。

II.D 内存管理对比

与执行策略紧密相关的是内存管理机制。

LiteRT Next: MemoryPlanner

LiteRT Next 包含一个名为 MemoryPlanner 的专用组件，其重点是“静态分配”和“内存共享”。

在 Static 模式 下，该规划器在离线（或加载时）对计算图中所有张量的“生命周期”（liveness）进行详尽分析。然后，它执行一个复杂的优化算法（类似于寄存器分配），计算出覆盖所有计算所需的最小内存池，并在一个单一、连续的内存块中为每个张量预先规划好偏移量。

在推理过程中，完全没有动态内存分配（即没有 malloc/free 或 new/delete 调用）。InferCore 只是根据这个静态的“内存地图”在预先分配好的内存块中读写数据。这对于实现可预测的低延迟和最小的内存占用 至关重要 [22]。

ONNX Runtime: Arena-based allocator

ORT 采用了一种成熟的、高性能的动态内存管理技术：基于 Arena 的分配器。

“Arena” 是一个大型的预分配内存池。当 ORT 需要为张量分配内存时，它会从这个 Arena 中“切”出一块，而不是向操作系统发起昂贵的 malloc 系统调用。当张量被释放时，内存被归还到 Arena 中以供后续重用。

对比分析：

• LiteRT Next (静态优化)：在编译时计算出最优的内存方案。保证了最低的运行时内存占用和零分配开销 [22]。但它要求模型结构（特别是形状）是已知的、静态的。

• ONNX Runtime (动态优化)：在运行时高效地管理内存池。为处理可变输入大小和动态模型提供了极佳的灵活性。但它仍然存在运行时管理开销，并且其内存峰值（high-water mark）通常高于静态优化的方案。

这种内存管理的差异，再次完美地映射了两者“边缘特化”与“通用灵活”的核心设计哲学。

III. 实证性能分析：跨轴基准测试

架构上的差异最终必须通过量化的性能指标来体现。本节将基于已知的性能数据和架构推论，对两种框架进行实证比较。

III.A 边缘/移动 CPU (ARM) 上的延迟与效率

• 关键数据：LiteRT Next 在 ARM CPU 平台（通过 ARM Neon 优化的内核 [10, 9]）上，针对 ResNet50 和 MobileNetV2 等模型的性能通常优于 ONNX Runtime。

• 因果分析：这一性能优势是第二节中讨论的架构选择的直接结果：

  1. 静态执行：消除了 ARM CPU 上代价高昂的运行时调度开销。

  2. 静态内存规划：避免了动态内存分配，降低了延迟抖动并减少了内存带宽压力。

  3. 垂直集成内核：LiteRT Next 的 InferCore 直接调用其为 ARM 优化的 C++ 内核 [10]，相比 ORT 需要通过 EP 抽象层 [5] 再调用其 CPU 内核（或 XNNPACK EP [7]），路径更短，开销更低。

• 模型选择的启示：数据中提到了 ResNet50 和 MobileNetV2 [14]，这是边缘视觉（CV）任务的“标准模型”。这进一步证实了 LiteRT Next 是针对这一特定工作负载进行了深度优化的。对于一个奇异的、新型的 Transformer 模型，其性能表现是未知的，甚至可能由于缺乏算子支持而无法运行 [14]。

III.B 服务器 GPU (NVIDIA) 上的吞吐量与加速

• ORT 的主场：对于 NVIDIA GPU 上的服务器端推理，ORT 的 TensorRT EP 是无可争议的“黄金标准” [16, 12]。TensorRT 是 NVIDIA 自己的闭源、专有编译器 [23]，它能执行极其激进的、针对硬件的图优化（如算子融合、半精度优化和内核自动调整）[24, 16, 12]。

• LiteRT 的挑战：LiteRT Next 的 GpuDevice 使用的是 OpenCL [9]（以及用于 Apple 设备的 Metal [20]）。

• 服务器端的架构劣势推论：

  • 结论：LiteRT Next 在 NVIDIA 服务器 GPU 上的性能几乎可以肯定会显著低于 ONNX Runtime。

  • 分析：ORT 的策略 是**“委托”给生态中最强的工具（TensorRT）[6, 12]。而 LiteRT Next 的策略 是试图用其自研的、通用的 OpenCL 内核去“竞争”**。在高性能计算领域，一个通用的 OpenCL 实现几乎不可能战胜一个由硬件供应商（NVIDIA）提供的、深度优化的、专有的编译器（TensorRT）[16, 11]。

  • LiteRT Next 的 GPU 支持（OpenCL/Metal）很可能主要针对的是边缘 GPU（如 ARM Mali, Apple M系列芯片）[14, 20]，而不是数据中心级的 A100 或 H100。

III.C 二进制占用与内存消耗

• 关键数据：LiteRT Next 具有更小的二进制文件大小和更低的内存占用 [8, 19]。

• 因果分析：

  1. 二进制大小：这与 LiteRT Next 受限的算子集 [14] 直接相关。ORT 为了遵从 ONNX 标准，必须为其支持的数百个算子 编译和携带内核代码 [5]。LiteRT Next 通过仅支持一个子集 [14]，极大地减少了需要编译的代码量。此外，ORT 的 EP 架构 [5] 也为每个 EP 增加了额外的“胶水代码”。

  2. 运行时内存占用：这与 MemoryPlanner 直接相关。如 II.D 节所述，其静态优化的内存池几乎总是比 ORT 的动态 Arena 分配器 更加节省内存。

III.D 启动时间与模型加载

• ORT 的对策：ORT 意识到了动态模型的加载开销，并引入了 .ort 格式 [5]。这种格式通过预先应用图优化并以更优化的格式存储模型，旨在“提高启动时间”和“减少（模型）大小”[5]。

• LiteRT 的固有优势：LiteRT Next 的 Converter 工具 [15, 18]（用于生成其专有的 .tflite 模型格式 [15]）执行了深度的 AOT 编译。其生成的模型文件（Flatbuffer [10]）是一种可被 InferCore（Interpreter）直接内存映射（memory-mapped）的格式。

• 推论：对于“冷启动”延迟（在 serverless 或移动应用启动时至关重要），LiteRT Next 的静态、预编译模型 [8] 可能会比 ORT（即使使用 .ort 格式）加载得更快。ORT 在加载时仍需初始化其 EP 结构和运行时调度器，而 LiteRT Next 可能只需将文件映射到内存并跳转到执行入口点 [19]。

表 3.1：性能与资源占用对比矩阵（基于分析的推演）

| 指标 | 模型 | 硬件 | ONNX Runtime | LiteRT Next | 胜出者 (推测) |

| :— | :— | :— | :— | :— | :— |

| P99 延迟 (ms) | MobileNetV2 | ARM Cortex-A78 CPU | 中 (动态开销) | 低 (静态执行) [9] | LiteRT Next |

| 运行时内存 (MB) | MobileNetV2 | ARM Cortex-A78 CPU | 中 (Arena) | 极低 (静态规划) [22] | LiteRT Next |

| 吞吐量 (Inf/sec) | BERT-Base | NVIDIA A100 GPU | 极高 (TensorRT EP) [23, 12] | 低 (通用 OpenCL) | ONNX Runtime |

| 二进制大小 (MB) | (框架本身) | N/A | 大 (全算子集, 多EPs) [5] | 小 (受限算子集) [8, 19] | LiteRT Next |

| 冷启动时间 (ms) | ResNet50 | 边缘设备 | 中 (使用.ort) [5] | 低 (AOT 编译模型) [8] | LiteRT Next |

IV. 模型优化与量化生态系统

比较推理框架不仅要看其运行时，还要看其配套的、用于压缩和加速模型的工具链。

IV.A 图优化 (离线 vs. 运行时)

• ONNX Runtime：提供运行时（Runtime）的图优化 [21]。开发者可以通过 API 设置不同的优化级别（如 Basic, Extended, All）[21]。这些优化包括节点消除、常量折叠和算子融合（如融合 Conv+ReLU）[21]。这种方法的优点是灵活性：同一个 .onnx 模型文件可以在不同的设备上被即时地、不同程度地优化。

• LiteRT Next：主要依赖离线（Offline）的图优化 [25]。其 Transform 组件 作为 Converter 工具 [15, 18] 的一部分，在模型转换阶段（编译时）执行。这种方法的优点是强度：它可以执行非常耗时的优化（例如复杂的数据布局转换 NCHW -> NHWC），因为这些优化只需执行一次，结果被固化到转换后的模型中。

这是一个根本性的哲学差异。ORT 的理念是“一个模型文件，到处运行，按需优化” [3, 4]。LiteRT Next 的理念是“一个模型，针对特定目标进行编译，以零开销执行” [8, 15]。

IV.B 量化策略

量化（Quantization）是将模型权重和/或激活从 32 位浮点数（FP32）降低到 8 位整数（INT8）或更低的过程，以减少模型大小和加速计算 [26, 22, 25]。

• ONNX Runtime：拥有一个非常成熟的量化工具集，同时支持动态量化（Dynamic Quantization）和静态量化（Static Quantization）（即训练后量化 Post-Training Quantization, PTQ）[27, 28]。动态量化对于 RNNs 和 Transformers 等模型非常有用，因为它们的激活值范围（动态范围）变化很大。

• LiteRT Next：在其 Transform 模块中支持量化 [25]。然而，鉴于其架构（尤其是 Static 模式 和 MemoryPlanner），其支持几乎可以肯定仅限于静态量化（包括 PTQ [19] 和量化感知训练 QAT [29]）。

量化策略中的权衡：

ORT 对动态量化的支持 [28] 极大地降低了使用门槛（不需要校准数据集），但它在运行时会引入开销（即需要动态计算激活值的量化尺度因子）。

LiteRT Next（推测的）仅静态的方法 [19]，虽然使用起来更繁琐（需要一个代表性的校准数据集来计算尺度因子 [19]），但它与 Static 执行模式 完美契合。所有量化参数在编译时都已确定，运行时执行的是纯粹的、零开销的 INT8 计算。

表 4.1：优化与量化能力对比

| 功能 | ONNX Runtime | LiteRT Next | 备注 |

| :— | :— | :— | :— |

| 常量折叠 | 支持 (运行时 或 离线 [.ort]) [21] | 支持 (离线/编译时) [15] | 标准功能 |

| 标准算子融合 (如 Conv+ReLU) | 支持 (运行时 或 离线 [.ort]) [21] | 支持 (离线/编译时) [15, 25] | 标准功能 |

| 布局优化 (如 NCHW->NHWC) | 支持 (取决于 EP, 如 TensorRT) [16, 12] | 支持 (离线/编译时) | LiteRT 在编译时执行，更具确定性 |

| 动态量化 (INT8) | 原生支持 [28] | 不支持 (推测) | ORT 的优势，灵活性高，但有运行时开销 |

| 静态量化 (PTQ, INT8) | 原生支持 [27, 28] | 原生支持 [19, 25] | 性能最佳的量化方式 |

| 量化感知训练 (QAT) | 支持 (通过 ONNX 格式) | 支持 (通过 TF 转换) [29] | 均支持，依赖于训练框架 |

| 优化发生阶段 | 运行时 (主要) [21] / 离线 (次要) [5] | 离线/编译时 (主要) [15, 25] | 核心哲学差异 |

V. 运维能力：算子、扩展性与 API

本节评估在实际项目中集成和维护这些框架的实践性考量。

V.A ONNX 算子集 (Opset) 覆盖率：关键的分割线

• ONNX Runtime：其核心目标之一就是成为 ONNX 标准的参考实现。因此，它致力于全面支持 ONNX Opset 中的绝大多数算子。

• LiteRT Next：“专注于…主流 CV 和 NLP 模型的常用算子” [14]。

LiteRT Next 的隐性成本：

这是 LiteRT Next 最重要、最实际的局限性。这是它为其低占用 和高特化性能 所付出的代价。

一个框架不可能既拥有极小的二进制文件，又同时支持 ONNX 标准中定义的所有 1000 多种算子及其变体 [2, 13]。

这对架构师构成了一个巨大的项目风险：

当研究团队推出一个新的 SOTA（State-of-the-Art）模型时，该模型很可能使用一些新颖的或不常见的 ONNX 算子。对于 ORT，这些算子很可能“开箱即用”。但对于 LiteRT Next，Converter 极有可能会因为遇到不支持的算子而失败 [14]。这将迫使工程团队要么修改模型（牺牲精度），要么投入高昂的工程成本去实现一个自定义算子。

V.B 自定义算子 (Custom Ops) 处理

• 对比：两种框架都提供了注册和使用自定义算子的接口 (LiteRT: [10, 9], ORT: [5])。

• 上下文的重要性：对于 ORT，自定义算子 是一种例外情况（Exception）[5]，主要用于前沿研究或集成专有硬件。对于 LiteRT Next，自定义算子（Delegates [10, 9]） 是一种必要手段（Necessity），是绕过其受限算子集 [14] 或加速特定硬件 [30] 的常规操作。

• 结论：因此，LiteRT Next 的自定义算子 API（Delegate API [9]）的易用性、性能和调试体验，对其生态系统的长期活力远比 ORT 更为关键。

V.C API 绑定与开发者体验 (DX)

• ONNX Runtime：提供了一个极其成熟和广泛的 API 绑定，包括 C, C++, C#, Python, Java [21, 5]。这反映了其在多样化企业系统中的广泛应用（Python 用于模型训练/服务，C# 用于.NET 后端，Java 用于大数据管道）。

• LiteRT Next：提供了核心的 API 绑定，即 C++, Java, Swift, Objective-C 和 Python [15, 19, 18]。这对于其主要目标（C++/Java/Swift/Obj-C 用于设备端部署 [19]，Python 用于模型转换/分析 [15]）是足够的。

• 技术栈锁定：这个差异可能成为一个决定性因素。一个构建在.NET (C#) 或 JVM (Java) 平台上的团队，在技术栈上被锁定，只能选择 ONNX Runtime。（注：LiteRT Next/TFLite 确实有 Java API [19]，但 ORT 的 Java API 通常在企业后端环境中更常见）。

VI. 部署、可移植性与生态集成

本节分析将框架集成到 MLOps 管道和最终产品中的“最后一公里”挑战。

VI.A 可移植性范式：水平 vs. 垂直

• ORT 的“水平”可移植性：一个单一的 .onnx 模型文件可以在 Windows, Linux, Android, iOS 等几乎所有平台上部署 [1, 3, 4]。在每个平台上，ORT 委托给该平台原生的最佳后端（如 Windows 上的 DirectML [7]，Apple 上的 CoreML [5, 7]，Android 上的 NNAPI [5, 7]）。

• LiteRT 的“垂直”可移植性：它在所有平台上运行它自己的、单一的引擎 [8, 9]。它使用通用的计算 API（如 OpenCL 和 Metal [14, 20]）来执行其自有的内核。

控制力 vs. 原生性能的权衡：

这是一个微妙但至关重要的区别。

• 使用 ORT，开发者可以（理论上）获得最佳的原生性能（例如，利用 Apple 为 ANE 芯片在 CoreML 中所做的深度优化 [31]）。但同时，开发者也受制于该原生后端的实现（例如，CoreML 对某个算子的实现可能存在 bug 或数值差异）[32]。

• 使用 LiteRT Next，开发者在所有平台上获得的是完全一致的性能和数值行为（因为执行的是完全相同的 LiteRT 内核）。但代价是，其通用的 OpenCL/Metal 内核 [14] 可能不如 Apple 在 CoreML 中精心优化的专有内核快 [32]。LiteRT Next 通过 Core ML delegate [20, 31] 试图解决这个问题，这使其架构变得更像 ORT 的“委托”模型。

VI.B MLOps 集成与模型制品

• ONNX Runtime：极大地简化了 MLOps。从训练框架（如 PyTorch [33] 或 Hugging Face Optimum）导出的 .onnx 文件，就是最终的部署制品（artifact）。它是一个单一的、可版本化的、可在所有环境中（Dev, QA, Prod）复用的文件 [4, 13]。

• LiteRT Next：使 MLOps 流程复杂化。它引入了一个强制的、额外的构建步骤：运行 Converter 工具 [15, 18]。

LiteRT Next 带来的 MLOps 复杂性：

LiteRT Next 打破了“单一制品”原则。MLOps 团队现在必须版本化、存储和验证两种制品：

1. 原始的（例如）TensorFlow .pb 或 Keras .h5 文件 [15, 18]。

2. 转换后的 .tflite 文件（部署的“二进制文件”）[15, 10]。

这个 Converter（它可以接受 TF, Keras [15, 18] 等作为输入）使 LiteRT Next 扮演了一个“模型聚合器”的角色，但同时也构成了一种专有格式的锁定（lock-in）。转换后的 .tflite 制品只能被 InferCore（Interpreter）使用。

VI.C 生态系统与工具的成熟度

• ONNX Runtime：拥有一个庞大、成熟、企业级的生态系统 [5, 33]。这包括由 Microsoft [17] 和大型社区 [2] 支持的调试工具、性能分析器（Profilers [6]）、模型可视化工具等。

• LiteRT Next：拥有一个专注、必要的生态系统（源自 TensorFlow Lite [15, 29]）。它提供了 Converter [15, 18] 和性能分析工具 [34] 等核心工具。这对于实现其功能是足够的，但缺乏 ORT 生态系统的深度、广度和企业（非移动）支持。

VII. 战略建议与决策框架

本报告的最终目标是综合所有技术数据，为架构师提供一个清晰、可操作的选择指南。

VII.A 场景分析

场景一：大规模、异构的云端部署（例如：多模型微服务）

• 推荐：ONNX Runtime

• 理由：

  1. 性能：通过 TensorRT EP [16, 12]，可在 NVIDIA GPU 上实现无与伦比的吞吐量。

  2. 兼容性：广泛的算子支持，使其能够处理来自不同团队的多样化模型库（CV, NLP, ASR 等）。

  3. 集成性：成熟的 API 绑定（C++, Python, C#, Java）[21, 5] 使其易于集成到现有的企业后端架构中。

场景二：资源受限的边缘/移动设备（延迟关键型应用）

• 推荐：LiteRT Next (但有重大前提条件)

• 理由：

  1. 性能：在 ARM CPU 上的延迟、内存占用 和二进制大小 方面具有已证实的显著优势 [8, 10, 9]。

  2. 架构：其 Static 执行模式 和 MemoryPlanner 在架构上是此类受限环境的理想选择 [22]，可提供可预测的、极低的延迟。

• 前提条件（至关重要）：

  • 该决策完全依赖于目标模型（以及未来迭代的模型）所使用的算子 100% 被 LiteRT Next 的受限算子集 [14] 所覆盖。

  • 必须进行初步的 PoC（Proof-of-Concept）来验证所有目标模型的兼容性。如果模型转换失败，或需要实现大量自定义算子，则应重新评估此选择，因为相关的工程维护成本可能极高。

场景三：快速原型设计与算法研究

• 推荐：ONNX Runtime

• 理由：

  1. 易用性：广泛的算子支持 提供了“它就是能用”（It Just Works）的体验。

  2. 敏捷性：研究人员可以从 PyTorch 导出新模型 并立即在 ORT 中运行，无需经过 LiteRT Next 所需的中间转换/编译步骤 [15, 18]。

VII.B 最终决策矩阵

表 7.1：战略决策矩阵：ONNX Runtime vs. LiteRT Next

| 关键需求维度 | ONNX Runtime | LiteRT Next | 决策依据（摘要） |

| :— | :— | :— | :— |

| 性能: 服务器端GPU吞吐量 | 卓越 | 差 | ORT 通过 TensorRT EP 实现SOTA性能 [16, 12]。LiteRT 的通用 OpenCL 内核 [9, 14] 缺乏竞争力。 |

| 性能: 边缘/移动CPU延迟 | 良好 | 卓越 | LiteRT 的静态执行 和内存规划 几乎消除了运行时开销，在ARM上胜出 [10, 9]。 |

| 广泛的模型兼容性 (Opset) | 卓越 | 差 | ORT 是 ONNX 标准的参考实现。LiteRT 故意限制算子集 [14]，这是其核心风险。 |

| 最小化资源占用 (磁盘/RAM) | 良好 | 卓越 | LiteRT 的受限算子集 和静态内存规划 带来了极小的占用空间 [8, 22]。 |

| 部署敏捷性 (MLOps) | 卓越 | 可接受 | ORT 使用单一的 .onnx 制品 [4, 13]。LiteRT 引入了强制的、专有的转换步骤 [15, 18]，增加了复杂性。 |

| 生态系统成熟度与工具链 | 卓越 | 良好 (专注) | ORT 拥有庞大、成熟的生态 [2, 5]。LiteRT 提供了必要的工具 [15, 34]，但深度不足。 |

| 跨平台数值一致性 | 良好 (依赖EP) | 卓越 | ORT 依赖原生后端 (CoreML/NNAPI) [5, 7]，可能引入差异。LiteRT 运行自己的引擎 [8]，行为一致。 |

| 企业 API 集成 (C#, Java) | 卓越 | 有限 | ORT 覆盖所有主流企业语言 [5]。LiteRT 专注于 C++/Python/Java/Swift [19, 18]。 |

VII.C 结论：两种哲学，两种使命

对 ONNX Runtime 和 LiteRT Next 的深入分析表明，它们并非传统意义上的直接竞争对手，而是针对两个截然不同用例的特化工具。

• ONNX Runtime 是一个“通用的翻译器”和“委托总线”。它为复杂、异构、快速变化的软件环境而生。它优先考虑的是灵活性、兼容性和广泛的适用性 [1, 2, 3, 4]。它通过其 EP 架构 [5, 6, 7] 巧妙地将“支持所有模型”的复杂性与“在所有硬件上实现高性能”的复杂性解耦。

• LiteRT Next 是一个“高度特化的编译器”和“静态执行引擎”。它为资源极度受限、性能需求苛刻的嵌入式和移动环境而生 [8, 15]。它优先考虑的是在狭窄但明确定义的领域内实现极致的性能和效率 [10, 9]。它通过垂直整合 和静态编译 实现了这一目标，但代价是牺牲了通用性 和 MLOps 的简洁性。

最终，架构师的选择不应是“哪个更好？”，而应是“哪个更适合我当前的技术、产品和业务上下文？”。选择 ORT 是选择了稳健性与灵活性；选择 LiteRT Next 则是选择极致的特化性能，并接受随之而来的兼容性风险和工程开销。

1. 目标“线程安全”模型的定义与范围

将 PDFium 这样的重量级 C++ 库从非线程安全改造为线程安全，首要任务是精确定义“线程安全”的目标状态。一个不明确的目标将导致灾难性的架构妥协。

1.1. 线程安全模型的权衡

PDFium 的当前状态是在进程级别上非线程安全的。其全局初始化函数 FPDF_InitLibrary() [1] 及其管理的全局资源，使得任何并发调用都可能导致数据竞争 (Race Condition) [2]。

在改造时，我们面临两种主要模型：

1. 完全可重入 (Full Re-entrancy): 允许多个线程同时对同一个 FPDF_DOCUMENT 实例执行操作。这要求在库的极深层实现极其复杂的细粒度锁定 [3, 4]，极易出错，且可能导致严重的锁竞争。
2. 每实例线程安全 (Per-Instance Thread Safety): 这是我们推荐的目标模型。它保证，只要两个线程操作的是不同的 FPDF_DOCUMENT 实例，它们就是完全线程安全的。这是在社区讨论中被认为是可行且有价值的模型 [5]。

1.2. 目标架构：每实例线程安全

本方案定义的目标架构是**“每实例线程安全”**。

具体而言，这意味着：

• 安全场景： 线程 A 处理 document1.pdf，线程 B 同时处理 document2.pdf。即使它们共享某些全局资源（如字体缓存），这种并发操作也必须是安全的。
• 不安全场景： 线程 A 渲染 document1.pdf 的第 1 页，线程 B 同时渲染 document1.pdf 的第 2 页。

此模型为服务器端应用（例如，并行处理大量不同PDF的Web服务）提供了最大的可伸缩性和价值。

1.3. 关键边界：文档内同步的客户端责任

作为目标架构的必然推论，我们必须设定一个清晰的 API 契约：PDFium 库本身不会保护单个 FPDF_DOCUMENT 实例免受并发访问。

这意味着：

• 我们不会在 FPDF_DOCUMENT [6] 级别添加一个粗粒度的互斥锁（Mutex）。
• API 契约： API 的调用者（客户端）有绝对责任实现自己的锁定机制（例如 std::mutex），以确保任何单个 FPDF_DOCUMENT 实例在任何时候都只被一个线程访问 [7, 8]。

这种设计避免了在库内部实现有缺陷的锁（这无法防止客户端的 “check-then-act” 竞争），并将锁的粒度控制权完全交给最了解业务逻辑的客户端。

2. 深度分析：解构 PDFium 的全局状态架构

PDFium 线程不安全的根源在于其深度依赖的、贯穿整个代码库的全局状态和单例模式。

2.1. FPDF_InitLibrary 的全局初始化问题

公共 API FPDF_InitLibrary() [1] 和 FPDF_InitLibraryWithConfig() [6] 建立了一个进程范围的全局状态。在多组件环境中，这立即导致了初始化冲突和数据竞争 [2]。社区中提出的使用 std::call_once [2] 只是对症状的缓解，而非对根本架构缺陷的修复。

2.2. 核心病灶：非线程安全的单例模式 (CFX_GEModule)

对代码库的深入分析 [9] 揭示了全局状态的真正来源：CFX_GEModule 类。

1. 全局裸指针： 在 core/fxge/cfx_gemodule.cpp 中定义了一个全局裸指针 CFX_GEModule* g_pGEModule = nullptr; [9]。
2. 非原子创建： CFX_GEModule::Create(...)（由 FPDF_InitLibrary 调用）直接对这个全局指针进行赋值：g_pGEModule = new CFX_GEModule(...) [9]。
3. 全局访问： 代码库中任何地方都可以通过静态方法 CFX_GEModule::Get() [9] 来获取这个全局单例。

这是典型的数据竞争：

• 两个线程同时调用 Create() 会导致内存泄漏或双重初始化。
• 一个线程调用 Get() 而另一个线程正在调用 Destroy()，会导致“悬空指针”(use-after-free) 或空指针解引用。

更糟糕的是，这个全局 CFX_GEModule 实例 [10] 拥有其他关键的共享资源，特别是 m_pFontCache（字体缓存）[10]，从而将全局污染扩散到整个字体和图形引擎 (FXGE) 层。

2.3. 识别其他全局与静态风险点

除了 CFX_GEModule，还存在其他全局和静态变量，它们都是潜在的数据竞争来源：

• CPDF_ModuleMgr: 如社区所指出 [11]，这是一个必须被重构的全局管理器。其身影出现在多个模块中 [12]。
• 缓存对象： 诸如 CPDF_PageImageCache [13, 14, 15] 和 CPDF_DocPageData [14, 15, 16] 这样的缓存。幸运的是，分析显示它们目前被 CPDF_Document 所拥有 [17]。这在我们的新 API 契约（1.3节）下是安全的——只要客户端锁定了文档，这些缓存就是安全的。
• 遗留代码： PDFium 拥有悠久历史的遗留代码 [17]，很可能存在 C++11 之前的“魔术静态变量”(magic statics) [18]。这种变量的初始化在多线程环境中不是原子的，可能导致全局锁竞争或竞争条件。

2.4. 全局状态与单例分析

为了量化重构工作，下表识别了关键的全局状态问题点及其拟议的解决方案。

表 1：全局状态与单例分析

3. 核心架构解决方案：”上下文对象” (Context Object) 模式

要消除全局状态，我们必须引入一种新的机制来承载这些状态。

3.1. 方案评估：为何 thread_local 不足取

一个看似简单的解决方案是使用 thread_local [11, 19] 来存储原先的全局变量。这是一个技术陷阱，原因如下：

1. 生命周期噩梦： 在现代线程池架构中，线程会被复用。thread_local 对象的生命周期与线程绑定，而不是与任务绑定。这会导致状态在一个不相关的任务中“泄漏”，引发灾难性故障。
2. 资源浪费： 每个线程都将创建并拥有自己的全套 CFX_GEModule 和 CFX_FontCache [10]。在一个拥有 128 个线程的服务器上，这将产生 128 个完全独立、不共享的字体缓存，造成巨大的内存浪费和性能下降（缓存命中率暴跌）。
3. API 复杂性： API 契约会变得混乱。客户端是否需要在每个线程上都调用 FPDF_InitLibrary()？这是反直觉且容易出错的。

3.2. 提案：FPDF_CONTEXT 作为核心状态载体

我们选择的解决方案是“上下文对象” (Context Object) 模式，这是在 C/C++ 库设计中用于实现线程安全的黄金标准 [20, 21, 22]。

1. 定义新句柄： 我们将定义一个新的、公开的、不透明的 C API 句柄：FPDF_CONTEXT。
2. 客户端所有权： API 的调用者（客户端）将负责创建、拥有和销毁这个 FPDF_CONTEXT 实例。
3. 状态隔离： FPDF_CONTEXT 实例将拥有所有先前是全局的或 thread_local 的状态。

这种模式赋予客户端完全的控制权：

• 每线程一个上下文： 客户端可以为每个线程创建一个 FPDF_CONTEXT。
• 应用程序共享一个上下文： 客户端可以创建一个 FPDF_CONTEXT 并在所有线程中共享（由客户端自己的锁保护）。
• 每会话一个上下文： 客户端可以为每个用户会话创建一个 FPDF_CONTEXT。

这是最灵活、最健壮的架构。

3.3. 所有权与数据流重构

FPDF_CONTEXT 的 C++ 内部实现（例如 PDFiumContext 类）将是重构的核心：

1. CFX_GEModule 的新家： PDFiumContext 类将包含一个 std::unique_ptr<CFX_GEModule> 成员。CFX_GEModule 将被重构为一个普通类，其 Get() / Create() / g_pGEModule [9] 将被完全删除。

2. CPDF_Document 的关联： CPDF_Document [23] 将被修改，增加一个 UnownedPtr<PDFiumContext> 成员。当客户端调用新的 FPDF_LoadDocumentWithContext 函数时，该文档实例将存储指向创建它的上下文的指针。

3. 缓存的所有权：

   • CFX_FontCache [10]：它仍被 CFX_GEModule 拥有，而 CFX_GEModule 现在被 PDFiumContext 拥有。这是关键点： 为了允许客户端安全地在线程间共享一个 FPDF_CONTEXT（我们测试计划中的场景 2），CFX_FontCache 本身必须被改造为内部线程安全。它必须使用一个（例如 Chromium 的 base::Lock [24]）来保护其内部的 std::map，使其 GetFont() 和 SetFont() 操作是原子的。这是在唯一需要的地方（共享资源）应用细粒度锁定 [3] 的典范。
   • CPDF_PageImageCache [15]：它保持其在 CPDF_Document 内的所有权 [14, 17]。根据我们的 API 契约（1.3节），这是安全的。

4. 新的数据访问链： 这种设计建立了一个清晰的、自下而上的数据访问链。例如，当渲染 FPDF_PAGE [25] 需要访问字体时：

   1. FPDF_PAGE 句柄 -> CPDF_Page 实例
   2. CPDF_Page::GetDocument() [25] -> CPDF_Document*
   3. CPDF_Document::GetContext() (新方法) -> PDFiumContext*
   4. PDFiumContext::GetGEModule() (新方法) -> CFX_GEModule*
   5. CFX_GEModule::GetFontCache() [10] -> CFX_FontCache*
   6. CFX_FontCache::GetFont(...) (此函数内部使用 base::AutoLock [24] 来安全地访问其 map)

这个设计 [20, 22] 完美地实现了我们的目标：线程 A（处理文档 1）和线程 B（处理文档 2）共享同一个 FPDF_CONTEXT，它们可以并行地执行解析和渲染，只有在它们同时访问 CFX_FontCache 的 map 时，才会被 base::Lock 短暂地串行化。

4. 第三方依赖库的线程安全审计与修复

我们的“上下文对象”架构是健壮的，但它依赖于一个关键假设：我们的第三方依赖库是可控的。我们不能在不安全的依赖库之上构建安全的系统 [5, 11]。

4.1. 审计框架

我们必须审计 PDFium 使用的所有第三方库 [26]。我们的 FPDF_CONTEXT 是管理那些需要每线程句柄或上下文指针的 C 库的完美工具。

4.2. 审计结果与修复计划

• 安全库： FreeType (fx_freetype), libpng (fx_lpng), zlib (fx_zlib) 均被报告为线程安全 [11]。ICU 在其设计上对我们的使用模型（不同对象）是安全的 [11]。这些库不需要修改。

• lcms2 (fx_lcms2):

  • 问题： 全局非线程安全。PDFium 自己的源码树中包含的 lcms2.h [27] 显示了 cmsCreateContext() API。文档 [28, 29] 证实，线程安全要求使用 ThreadContext。
  • 修复方案： PDFiumContext 类（FPDF_CONTEXT 的实现）将在其构造函数中调用 cmsCreateContext()，并存储返回的 cmsContext 句柄。所有对 lcms2 的内部调用都必须被重构，以使用需要此 cmsContext 句柄的函数变体。

• libjpeg-turbo (jpeg):

  • 问题： 库本身在每个 tjhandle 上是线程安全的 [30]。但关键问题是：其全局错误处理函数 tjGetErrorStr() 使用一个静态缓冲区，因此它不是线程安全的 [30, 31, 32]。
  • 修复方案： 我们不能修复 libjpeg-turbo。相反，我们将在 PDFium 内部实现一个包装器，该包装器拥有一个 static base::Lock。任何调用 libjpeg-turbo 函数并需要通过 tjGetErrorStr() 获取错误信息的 PDFium 代码，都必须通过这个包装器，该包装器在 base::AutoLock 的保护下调用 tjGetErrorStr()。这是一个仅在错误路径上发生的、可接受的性能瓶颈。

• openjpeg (fx_libopenjpeg):

  • 问题： 这是最高风险的依赖项。该库“并非真正的线程安全” [33]。它是“在没有考虑线程安全的情况下设计的” [33]，并使用了全局变量。
  • 修复方案： 我们无法控制此库 [5]。维护一个 openjpeg 的“fork”在工程上是不可持续的。唯一安全的解决方案是假定该库 100% 是单线程的。我们将创建一个进程级的静态 base::Lock（例如 g_openjpeg_mutex），并用它来串行化对 openjpeg 库的所有调用（包括编码和解码）。
  • 性能影响： 这将导致在并发处理 JPEG2000 图像时出现严重的性能瓶颈。这是为了在不修改 openjpeg 的情况下获得正确性而必须付出的代价。此决策必须在文档中明确声明。

4.3. 第三方依赖库线程安全审计

表 2：第三方依赖库线程安全审计与修复计划

5. 内部并发：锁策略的演进

基于上述分析，我们最终的锁策略是一个清晰的两层模型。

5.1. 锁模型澄清：上下文 vs. 文档

1. 上下文级别（共享资源）：
   由 FPDF_CONTEXT 拥有且设计为在多个文档之间共享的资源（唯一的例子是 CFX_FontCache [10]），必须是内部线程安全的。它们将使用自己的细粒度 base::Lock [24] 来保护其内部状态（例如 std::map）。这允许了高并发性 [3, 34]。

2. 文档级别（独占资源）：
   FPDF_DOCUMENT [6]、FPDF_PAGE [35] 及其拥有的所有数据（例如 CPDF_PageImageCache [15]）被明确定义为非线程安全。

5.2. 客户端锁的必要性

在 1.3 节中，我们规定客户端必须锁定文档。这里是技术上的理由：

• 避免 API 陷阱： 假设我们试图“帮助”客户端，并在 FPDF_GetPageCount 和 FPDF_LoadPage 内部都添加了锁。客户端代码如下：

  1 2	int n = FPDF_GetPageCount(doc); FPDF_PAGE page = FPDF_LoadPage(doc, n - 1);

  在 FPDF_GetPageCount 调用返回之后和 FPDF_LoadPage 调用开始之前，另一个线程仍然可以修改文档（例如删除最后一页），导致 n-1 成为一个无效索引。

• 正确的“事务”： 客户端是唯一知道操作“事务”边界的。正确的、健壮的客户端代码必须如下所示：

  1 2 3

  my_mutex.lock(); int n = FPDF_GetPageCount(doc); FPDF_PAGE page = FPDF_LoadPage(doc, n - 1);

… // 渲染页面
FPDF_ClosePage(page);
my_mutex.unlock();
```
我们的 API 契约强制客户端采用这种正确的设计，而不是提供一种具有误导性的、虚假的“安全感”。

6. 分阶段实施与 API 演进路线图

如此大规模的架构更改必须分阶段进行，以保持向后兼容性，并为客户端提供清晰的迁移路径。

6.1. 阶段一：内部重构（”大爆炸”式改造）

目标： 在不修改任何 public/ 目录下的头文件 [36] 的前提下，重构所有内部代码以使用新的 PDFiumContext 模式。

实施方案：

1. 执行第 3 节和第 4 节中描述的所有内部重构。
2. 创建“遗留 API 垫片 (Legacy Shim)”： 在 fpdf_view.cpp [37] 中，创建一个单一的、静态的、全局的 PDFiumContext* g_legacy_context;。
3. 此 g_legacy_context 必须使用 std::call_once [2] 或等效的线程安全机制进行“惰性初始化”。
4. 创建一个新的全局锁：static base::Lock g_legacy_api_mutex;。
5. 重写旧 API：
   • FPDF_InitLibrary() [1] 的新实现是：调用 std::call_once 来初始化 g_legacy_context。
   • FPDF_DestroyLibrary() [11] 的新实现是：调用 std::call_once 来销毁 g_legacy_context（或者在进程退出时依赖操作系统清理）。
   • FPDF_LoadDocument() [38] 的新实现是：

     1 2	base::AutoLock lock(g_legacy_api_mutex); return FPDF_LoadDocumentWithContext(g_legacy_context,...);

   • 所有其他旧的 API（如 FPDF_RenderPage [1]）都必须以 base::AutoLock lock(g_legacy_api_mutex); 开始。

结果： 内部代码库已完全重构。旧的 API 仍然可以编译和运行（保持 ABI/API 兼容性），但现在它的所有操作都被 g_legacy_api_mutex 完全串行化了。这为不迁移的客户端提供了正确性（无数据竞争），但代价是巨大的性能惩罚，从而强烈激励他们迁移到新 API。

6.2. 阶段二：引入新的公共 API

目标： 引入新的、高性能的、线程安全的 API。这是C API演进的标准实践 [39, 40, 41]。

实施方案： 在 public/fpdfview.h [6, 36] 等头文件中添加新函数：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

// 新的上下文配置结构体 (用于传入分配器、V8 Isolate [6] 等)
typedef struct {... } FPDF_CONTEXT_CONFIG;

// 创建和销毁上下文
FPDF_EXPORT FPDF_CONTEXT FPDF_CALLCONV FPDF_CreateContext(FPDF_CONTEXT_CONFIG* config);
FPDF_EXPORT void FPDF_CALLCONV FPDF_DestroyContext(FPDF_CONTEXT context);

// 使用上下文加载文档
FPDF_EXPORT FPDF_DOCUMENT FPDF_CALLCONV FPDF_LoadDocumentWithContext(
    FPDF_CONTEXT context,
    FPDF_FILEACCESS* pFileAccess,
    FPDF_BYTESTRING password);

//... (以及 FPDF_LoadMemDocumentWithContext 等变体)

关键 API 设计： 只有 LoadDocument 及其变体需要显式接收 FPDF_CONTEXT。CPDF_Document 实例将存储该上下文指针。所有后续操作（如 FPDF_LoadPage、FPDF_RenderPageBitmap [42]）的签名保持不变。它们的内部实现将通过传入的 FPDF_PAGE 或 FPDF_DOCUMENT 句柄，间接获取所需的上下文（如 3.3 节所述）。这极大地简化了 API 的演进。

6.3. 阶段三：废弃与迁移

1. 在头文件中将所有旧的、不带上下文的 API 函数（如 FPDF_InitLibrary）标记为 @deprecated。
2. 发布详细的迁移指南 [43]，解释新的线程安全模型（1.3节）、新的 API（6.2节）以及不迁移的性能后果（g_legacy_api_mutex 串行化）。

6.4. API 演进对比

表 3：API 演进：遗留 vs. 线程安全

7. 验证策略：TSan 驱动的并发测试

并发错误是出了名的难以检测和复现 [44]。没有严格的验证策略，此方案将毫无价值。

7.1. 核心工具：ThreadSanitizer (TSan)

我们的主要验证工具必须是 ThreadSanitizer (TSan) [45, 46]。

• TSan 是一种动态分析工具，它能在运行时检测实际发生的数据竞争 [44, 47]。
• 所有 PDFium 测试套件必须在 CI（持续集成）上使用 -fsanitize=thread [46] 进行编译和运行。这是现代多线程系统开发的标准做法 [48]。

7.2. 构建新的多线程压力测试套件

PDFium 的现有测试可能主要是单线程的。我们必须创建一套新的、专门用于触发并发问题的多线程压力测试 [48, 49, 50]。此套件将仅使用第 6.2 节中的新 API。

• 测试 1：“上下文流失” (Context Churn):

  • 目的： 测试 FPDF_CreateContext / FPDF_DestroyContext 的数据竞争。
  • 方法： 启动 50 个线程。每个线程在循环中创建和销毁 FPDF_CONTEXT 100 次。
  • 预期： TSan 报告为零。

• 测试 2：“共享上下文，不同文档” (黄金路径):

  • 目的： 验证我们的核心目标（1.2节）。严格测试共享资源（如 CFX_FontCache [10]）的内部锁。
  • 方法： 创建一个 FPDF_CONTEXT。启动 50 个线程。每个线程在循环中从语料库中随机选择一个 PDF，使用共享的上下文调用 FPDF_LoadDocumentWithContext，加载并渲染一个随机页面，然后关闭文档。
  • 预期： TSan 报告为零。CFX_FontCache 中任何遗漏的 base::Lock 都会在这里立即暴露。

• 测试 3：“客户端锁（负面测试）”:

  • 目的： 验证我们的 API 契约（1.3节）——即客户端必须加锁。
  • 方法： 创建一个上下文并加载一个 FPDF_DOCUMENT。启动 10 个线程。所有线程同时对这同一个文档句柄调用 FPDF_RenderPageBitmap，不使用任何外部锁。
  • 预期： 此测试必须失败——无论是崩溃、ASan 报告 [13]、TSan 报告，还是产生损坏的图像。这证明了我们的 API 契约是必要的。

• 测试 4：“客户端锁（正面测试）”:

  • 目的： 证明我们的客户端锁模型（1.3节）是可行且正确的。
  • 方法： 与测试 3 相同，但测试工具在所有 10 个线程的 FPDF_RenderPageBitmap 调用外围包裹一个 std::mutex。
  • 预期： 测试必须 cleanly 通过，TSan 报告为零。

7.3. CI 集成与质量门禁

• 所有 TSan 启用的构建和测试必须在 CI 中运行。
• 来自 TSan [44] 的任何数据竞争报告都必须自动导致构建失败。零容忍。

8. 结论与核心技术建议

此方案提出了一个将 PDFium 从进程级非线程安全转变为健壮的、每实例线程安全的库的完整路线图。该计划的核心是放弃 thread_local 等捷径，转而采用更健壮但更复杂的“上下文对象”模式。

成功的关键在于严格执行以下技术建议：

1. 全局状态： 必须彻底消除所有可变全局状态。CFX_GEModule [9] 单例是首要目标。
2. API 演进： 必须采用“上下文对象”模式 [20, 40]。引入 FPDF_CreateContext 和 FPDF_LoadDocumentWithContext [40, 41]。旧 API 必须降级为使用全局锁的“遗留垫片”，以激励迁移。
3. 第三方依赖： 必须通过 FPDF_CONTEXT 传递 cmsContext [27] 来修复 lcms2。必须接受 openjpeg [33] 带来的性能瓶颈，并对其所有调用进行全局串行化。
4. 锁模型： 必须采用双重锁策略：对上下文拥有的共享资源（CFX_FontCache [10]）使用内部细粒度锁 [24]，同时明确要求客户端对独占资源（FPDF_DOCUMENT）进行外部锁定。
5. 验证： 必须将 TSan [45, 46] 作为质量门禁，并构建一个全新的、专门设计用于触发并发问题的多线程压力测试套件 [48]。

参考资料

1. public/fpdfview.h - pdfium - Git at Google, accessed November 4, 2025, https://pdfium.googlesource.com/pdfium/+/main/public/fpdfview.h
2. PDFium initialization conflict across isolates · Issue #474 · espresso3389/pdfrx - GitHub, accessed November 4, 2025, https://github.com/espresso3389/pdfrx/issues/474
3. CS 111 – Spring 2005, accessed November 4, 2025, https://read.seas.harvard.edu/~kohler/class/cs111-s05/notes/notes8.html
4. Performance Impact of Memory Ordering in Concurrent C++ - ULB : Dok - Universität Innsbruck, accessed November 4, 2025, https://ulb-dok.uibk.ac.at/download/pdf/10046094.pdf
5. PDFium thread safety - Google Groups, accessed November 4, 2025, https://groups.google.com/g/pdfium/c/HeZSsM_KEUk
6. Getting Started with PDFium, accessed November 4, 2025, https://pdfium.googlesource.com/pdfium/+/HEAD/docs/getting-started.md
7. pdfium - Rust - Docs.rs, accessed November 4, 2025, https://docs.rs/pdfium
8. lifetime problems with self-referential struct · Issue #44 · ajrcarey/pdfium-render - GitHub, accessed November 4, 2025, https://github.com/ajrcarey/pdfium-render/issues/44
9. core/fxge/cfx_gemodule.cpp - pdfium.git - Git at Google, accessed November 4, 2025, https://pdfium.googlesource.com/pdfium.git/+/refs/heads/chromium/4182/core/fxge/cfx_gemodule.cpp
10. core/fxge/cfx_gemodule.h - pdfium - Git at Google, accessed November 4, 2025, https://pdfium.googlesource.com/pdfium/+/refs/heads/chromium/6173/core/fxge/cfx_gemodule.h
11. PDFium thread safety - Google Groups, accessed November 4, 2025, https://groups.google.com/d/msgid/pdfium/40a6eb27-5318-4bee-afd6-b25531931c1d%40googlegroups.com
12. core/fpdfapi/page/cpdf_streamparser.cpp - pdfium - Git at Google, accessed November 4, 2025, https://pdfium.googlesource.com/pdfium/+/refs/heads/chromium/2964/core/fpdfapi/page/cpdf_streamparser.cpp
13. Pdfium Out-Of-Bounds Read in CPDF_DIB::LoadJpxBitmap [345518608] - Chromium Issue, accessed November 4, 2025, https://issues.chromium.org/issues/345518608
14. fpdfsdk/fpdf_editpage.cpp - pdfium - Git at Google, accessed November 4, 2025, https://pdfium.googlesource.com/pdfium/+/refs/heads/main/fpdfsdk/fpdf_editpage.cpp
15. platform/external/pdfium - Git at Google - Android GoogleSource, accessed November 4, 2025, https://android.googlesource.com/platform/external/pdfium/+/03925281cf25fec70318bf2225356d022b12b566
16. core/fpdfdoc/cpdf_formfield.cpp - pdfium - Git at Google, accessed November 4, 2025, https://pdfium.googlesource.com/pdfium/+/refs/heads/main/core/fpdfdoc/cpdf_formfield.cpp
17. Diff - bc260fd7e338f266d4e41e979c57c100ae9661b6^1..bc260fd7e338f266d4e41e979c57c100ae9661b6 - platform/external/pdfium - Git at Google - Android GoogleSource, accessed November 4, 2025, https://android.googlesource.com/platform/external/pdfium/+/bc260fd7e338f266d4e41e979c57c100ae9661b6%5E1..bc260fd7e338f266d4e41e979c57c100ae9661b6/
18. Are function static variables thread-safe in GCC? - Stack Overflow, accessed November 4, 2025, https://stackoverflow.com/questions/1270927/are-function-static-variables-thread-safe-in-gcc
19. Making global static variables multithread safe - Stack Overflow, accessed November 4, 2025, https://stackoverflow.com/questions/2662575/making-global-static-variables-multithread-safe
20. Google C++ Style Guide for Drake - MIT, accessed November 4, 2025, https://drake.mit.edu/styleguide/cppguide.html
21. C++ Development – Basics, Guidelines and Best Practices - For the love of challenges, accessed November 4, 2025, https://lionadi.wordpress.com/kiss-software-development-guide/programming-languages/c-development-basics-guidelines-and-best-practices/
22. Non-Send Futures When? - matklad, accessed November 4, 2025, https://matklad.github.io/2023/12/10/nsfw.html
23. core/fpdfapi/parser/cpdf_document.cpp - pdfium - Git at Google, accessed November 4, 2025, https://pdfium.googlesource.com/pdfium/+/refs/heads/main/core/fpdfapi/parser/cpdf_document.cpp
24. cef_base.h, accessed November 4, 2025, https://magpcss.org/ceforum/apidocs3/projects/(default)/cef_base.h.html
25. core/fpdfapi/page/cpdf_page.h - pdfium - Git at Google, accessed November 4, 2025, https://pdfium.googlesource.com/pdfium/+/refs/heads/main/core/fpdfapi/page/cpdf_page.h
26. pypdfium2-team/pypdfium2: Python bindings to PDFium, reasonably cross-platform. - GitHub, accessed November 4, 2025, https://github.com/pypdfium2-team/pypdfium2
27. lcms2.h - PDFium, accessed November 4, 2025, https://pdfium.googlesource.com/pdfium/+/5110c4743751145c4ae1934cd1d83bc6c55bb43f/core/src/fxcodec/lcms2/lcms2-2.6/include/lcms2.h
28. Transform in lcms2 - Rust - Docs.rs, accessed November 4, 2025, https://docs.rs/lcms2/latest/lcms2/struct.Transform.html
29. lcms2 - Rust - Docs.rs, accessed November 4, 2025, https://docs.rs/lcms2
30. Re: [Libjpeg-turbo-users] Is the TurboJPEG API thread-safe? - SourceForge, accessed November 4, 2025, https://sourceforge.net/p/libjpeg-turbo/mailman/message/30336128/
31. It is not possible to safely use libjpeg-turbo in multithreaded application through the turbo API #396 - GitHub, accessed November 4, 2025, https://github.com/libjpeg-turbo/libjpeg-turbo/issues/396
32. Documentation / Official Binaries - libjpeg-turbo, accessed November 4, 2025, https://libjpeg-turbo.org/Documentation/OfficialBinaries
33. Thread Safety, accessed November 4, 2025, https://galfar.vevb.net/imaging/smf/index.php?topic=840.0
34. Implementing a flexible network stack - DTU Informatics, accessed November 4, 2025, https://www2.imm.dtu.dk/pubdb/edoc/imm6627.pdf
35. public/fpdf_edit.h - pdfium - Git at Google, accessed November 4, 2025, https://pdfium.googlesource.com/pdfium/+/refs/heads/main/public/fpdf_edit.h
36. public/fpdfview.h - pdfium - Git at Google, accessed November 4, 2025, https://pdfium.googlesource.com/pdfium/+/refs/heads/chromium/4016/public/fpdfview.h
37. fpdfsdk/fpdf_view.cpp - pdfium - Git at Google, accessed November 4, 2025, https://pdfium.googlesource.com/pdfium/+/refs/heads/chromium/4542/fpdfsdk/fpdf_view.cpp
38. ajrcarey/pdfium-render: A high-level idiomatic Rust wrapper around Pdfium, the C++ PDF library used by the Google Chromium project. - GitHub, accessed November 4, 2025, https://github.com/ajrcarey/pdfium-render
39. Standard Co-Emulation Modeling Interface (SCE-MI) Reference Manual Version 2.2 January 20 - Accellera Systems Initiative, accessed November 4, 2025, https://www.accellera.org/images/downloads/standards/sce-mi/SCE-MI_v22-140120-final.pdf
40. 4.4. Using CVODE for IVP Solution - SUNDIALS documentation - Read the Docs, accessed November 4, 2025, https://sundials.readthedocs.io/en/v6.1.1/cvode/Usage/
41. Pro*C/C++ - Developer’s Guide - Oracle Help Center, accessed November 4, 2025, https://docs.oracle.com/en/database/oracle/oracle-database/23/lnpcc/c-c-developers-guide.pdf
42. fpdfview.h - Android Code Search, accessed November 4, 2025, https://cs.android.com/android/platform/superproject/+/master:external/pdfium/public/fpdfview.h;l=710-711;drc=master;bpv=1;bpt=1
43. API Backwards Compatibility Best Practices | Zuplo Learning Center, accessed November 4, 2025, https://zuplo.com/learning-center/api-versioning-backward-compatibility-best-practices
44. ThreadSanitizer: data race detection in practice - Google Research, accessed November 4, 2025, https://research.google.com/pubs/archive/35604.pdf
45. Debugging Race Conditions in C++ & C Programming with ThreadSanitizer (TSan), accessed November 4, 2025, https://www.youtube.com/watch?v=SiI3-pJ6MMU
46. ThreadSanitizer — Clang 22.0.0git documentation - LLVM, accessed November 4, 2025, https://clang.llvm.org/docs/ThreadSanitizer.html
47. ThreadSanitizerCppManual · google/sanitizers Wiki - GitHub, accessed November 4, 2025, https://github.com/google/sanitizers/wiki/threadsanitizercppmanual
48. Designing a Browser to Benefit from Multi-core Silicon | Ekioh, accessed November 4, 2025, https://www.ekioh.com/wp-content/uploads/Designing-a-Browser-to-Benefit-from-Multi-core-Silicon.pdf
49. (PDF) DataRaceBench: a benchmark suite for systematic evaluation of data race detection tools - ResearchGate, accessed November 4, 2025, https://www.researchgate.net/publication/320954178_DataRaceBench_a_benchmark_suite_for_systematic_evaluation_of_data_race_detection_tools
50. Selectively Uniform Concurrency Testing - Dylan Wolff, accessed November 4, 2025, https://dylanjwolff.com/assets/surw.pdf

I. PDFium 项目概览与架构蓝图

1.1 项目起源：从 Foxit 到 Google Chromium

PDFium 是一个高性能的开源 PDF 库，其技术血统源自两大行业巨头：Foxit（福昕软件）和 Google [1, 2]。该项目于 2014 年 6 月正式宣布，其初始代码库由 Foxit 提供 [1]。这一渊源至关重要，因为它决定了 PDFium 的核心架构 DNA。

Foxit 是一家领先的 PDF 解决方案提供商，其商业 PDF SDK 以跨平台能力和功能完整性著称 [3, 4]。PDFium 共享了驱动 Foxit 商业 SDK 的底层技术 [1, 3]，这意味着其初始架构（2014 年之前）是为一个功能全面、商业级的 SDK 设计的。

然而，自 2014 年 Google 接管并将其开源以来，PDFium 的演进方向被注入了“浏览器级”的基因。它被深度集成到 Chromium 项目中 [5]，并成为 Google Chrome 浏览器内置的 PDF 渲染引擎 [2]。这一转变使得项目的开发重点转向了极致的安全加固、高性能渲染以及与 Chromium 庞大构建体系的深度集成 [6, 7]。

这种“Foxit 商业”与“Google 开源”的双重起源，在架构上形成了一种微妙的“张力”。Foxit 的商业 SDK 提供了包括高级编辑、注释、安全和条形码在内的广泛功能 [4]。但对于 Google 而言，其核心目标是为 Chrome 浏览器维护一个最小化、最安全、最高效的渲染器。

对于需要评估此库的架构师而言，关键的结论是：不能假设 Foxit 商业 SDK [3] 的所有高级功能（特别是 PDF 编辑）在 PDFium 中都（免费）可用，即使它们“共享底层技术” [1]。PDFium 的核心是围绕 Google 的需求演进的：即“查看、搜索、打印和表单填写” [1]。

1.2 核心价值主张：为何 PDFium 是一个“浏览器级” PDF 引擎

PDFium 的核心价值主张不是其功能集，而是其安全性和健壮性。作为一个“浏览器级”引擎，它在 Chromium 项目中经受了实战检验，其设计目标是能够抵御来自互联网的、不可信的、甚至包含恶意负载的 PDF 文件的攻击，而不会损害宿主应用程序（如 Chrome 浏览器） [2]。

这种顶级的安全性是通过 Google 的大规模、持续的基础设施投入来实现的，特别是：

1. 持续的模糊测试 (Fuzzing)： PDFium 是 Google ClusterFuzz [8] 等模糊测试框架的核心目标 [9]。它会持续不断地向 PDFium 注入自动生成的、损坏的输入数据，以发现潜在的安全漏洞 [10, 11, 12, 13]。
2. Chromium 集成： 作为 Chromium [5] 的 third_party 依赖 [9]，它享受着与浏览器内核同等级别的安全审查和加固标准。

对于技术决策者而言，这意味着 PDFium 是处理不可信来源 PDF（例如，SaaS 平台的用户上传、邮件服务器的附件处理、公共文档库）的黄金标准。

为这种顶级安全付出的“代价”是架构层面的：

• 沉重的构建系统： 它强制要求使用 Chromium 的 depot_tools 工具链 [6, 7]，集成复杂度远高于常规 C++ 库。
• 严格的 API 合约： 它对嵌入者（Embedder）提出了严苛的要求，例如强制的单线程模型 [14]，以牺牲“易用性”换取内部状态的一致性和可预测性。

架构上的权衡非常清晰：PDFium 是以“高集成复杂性”换取“世界级的安全性”。

1.3 架构蓝图：顶层目录与核心模块职责划分

PDFium 源码库的顶层目录 [5] 揭示了一个经过深思熟虑的、高度模块化的分层设计，这是大型 C++ 项目的典范。理解这些模块的职责是理解整个系统的关键。

表 1：顶层模块职责

理解 PDFium 的关键在于掌握其核心调用链：public -> fpdfsdk -> core。

当嵌入者调用一个公共 C API 时，例如 FPDF_LoadDocument() [14, 24]，该调用会按以下顺序穿透架构：

1. public/fpdfview.h [14]：C API 的定义，这是一个不透明的句柄 FPDF_DOCUMENT。
2. fpdfsdk/fpdfview.cpp [25]：C API 的实现。此文件将 C 调用（和 C 句柄）转换为 C++ 调用，创建并管理内部 C++ 对象。
3. core/fpdfapi/parser/cpdf_document.cpp [16]：核心 C++ PDF 文档对象模型（CPDF_Document）的实际实现，负责解析和管理页面树。

这种严格的分层（C API -> C++ 桥接 -> C++ 核心）确保了 API 的稳定性和内部实现的高度可维护性。

1.4 许可证分析：Apache 2.0 及其对企业集成的意义

PDFium 项目的 LICENSE 文件明确指定其采用 Apache License, Version 2.0 [26]。

这是一个对商业极其友好的“宽容型”（Permissive）许可证。与 GPL/AGPL [27, 28] 许可证不同，Apache 2.0 没有“强拷贝左”（Strong Copyleft）的限制。这意味着：

• 允许商业闭源使用： 企业可以在其闭源的商业产品中合法地使用、修改和分发 PDFium，而无需开源其产品的代码 [29]。
• 专利授权： Apache 2.0 包含一个明确的专利授权条款 [26]，这有助于降低企业在集成时面临的专利诉讼风险。

这是 Google 推动 PDFium（特别是作为 Chromium 的一部分 [5]）广泛采用的关键法律决策。

然而，对于架构师而言，真正的许可证风险不在 PDFium 本身，而在其庞大且复杂的依赖项 (DEPS) [27]。DEPS 文件 [5] 中列出的所有依赖项（如 V8, FreeType [20], lcms2, libjpeg-turbo, openjpeg 等）各自拥有不同的开源许可证。

[27] 资料中明确指出，“PDFium’s license as well as dependency licenses have to be shipped with binary distributions”。（PDFium 的许可证及其依赖项许可证必须随二进制分发版一起提供）。

这对任何大型企业都是一项严肃的法律合规工作。架构师必须对 DEPS 文件中的所有依赖项进行完整的许可证审计。这也解释了为什么市场上会存在如 pdfium.patagames.com [30, 31] 这样的商业封装：它们通过收费的方式，为您处理了构建、封装和法律合规的复杂性。

II. 依赖项、构建与集成体系结构

2.1 构建系统：深入分析 depot_tools, gclient, GN 与 Ninja

PDFium 的集成对架构师的第一个，也是最大的挑战，在于其构建系统。PDFium 无法通过常规的 cmake, make 或 Visual Studio 解决方案（sln）来构建 [7]。

它强制要求使用与 Chromium 完全相同的构建工具链 [5, 6, 22]。这套工具链包括：

1. depot_tools：这是 Google 的一套工具脚本，提供了 gclient 等核心工具 [7]。它是整个构建系统的入口。
2. gclient：一个元数据（meta）检出工具。它负责读取 DEPS 配置文件 [5]，并通过 gclient sync [7, 22] 命令，递归地检出 PDFium 源码及其所有（庞大的）依赖项。
3. GN (Generate Ninja)：一个元构建系统 [32]。开发者通过 gn gen <directory> [7, 22] 命令来配置构建。GN 会解析 .gn 和 .gni 文件，生成 Ninja 构建脚本 [32]。
4. Ninja：一个为速度而生的小型构建系统 [22]。gn 生成文件后，开发者运行 ninja -C <directory> [22, 33] 来实际执行（并行的）编译和链接。

对于一个不熟悉 Chromium 生态的团队来说，这套流程是一个巨大（但不可避免）的学习曲线和基础设施投入。任何试图“绕过”这个系统（例如，寻找预编译的 .dll [34]）的尝试，都将在未来升级和维护时导致灾难。

架构师的决定是：必须全盘接受 Chromium 构建体系。 您的 CI/CD 系统必须安装 depot_tools [7]，并学习 gclient [22]、GN [32] 和 Ninja [22] 的整套工作流。

2.2 关键构建配置：pdf_enable_v8, pdf_enable_xfa, pdf_use_skia 等标志的架构影响

GN [32] 提供了一个极其灵活的配置系统。通过 gn args <directory> [22] 设置的构建标志（flags），是架构师对 PDFium 进行“功能裁剪”和“架构决策”的主要控制点。

这些标志（定义在 pdfium.gni [18] 等文件中）允许在编译时裁切掉不需要的子系统，从而在功能、性能和安全攻击面之间做出权衡。

表 2：关键 GN 构建标志的架构影响

2.3 外部依赖 (DEPS) 分析

PDFium 不是一个单一的库，它是一个发行版（Distribution），通过 DEPS 文件 [5] 和 gclient [22] 捆绑了所有必需的依赖项。

关键依赖项包括：

• V8：用于 JavaScript [18, 22]。
• FreeType：字体渲染的基石 [20, 39]。
• Skia：实验性图形后端 [18, 37]。
• AGG (Anti-Grain Geometry)：默认图形后端 [19, 37]。
• 其他库：lcms2 (色彩管理), libjpeg-turbo / openjpeg (图像解码), icu (国际化，V8 依赖) [40, 41]。

在这些依赖中，FreeType 的集成方式是一个主要的架构风险点。third_party/freetype/README.pdfium [20] 文件明确指出，PDFium 不使用标准的 FreeType 公共 API。相反，它依赖于 FreeType 的内部头文件（例如 pstables.h） [20, 38]。

这意味着，任何试图通过设置 pdf_bundle_freetype = false [18] 来链接到“系统 FreeType” [39] 以节省空间的尝试，几乎注定会因为缺少这些内部头文件而构建失败 [38]。

架构师必须接受这一事实：必须使用 PDFium 捆绑的、经过轻微修改的 FreeType 版本。

2.4 集成成本与架构决策：将 PDFium 引入现有大型项目的挑战

综上所述，集成 PDFium 的成本主要在基础设施和架构决策，而非代码编写。

1. CI/CD 成本：必须重塑现有的构建流程，以完全适应 depot_tools 工具链 [7, 22]。
2. 依赖项成本：必须接受 PDFium 的 DEPS [5] 文件所定义的特定、固定版本的依赖。如果您现有的项目也依赖 V8 或 FreeType，但版本不同，您将面临严峻的“依赖地狱”冲突 [39]。
3. 封装成本：必须编写一个健壮的 C++ / Rust 包装器 [42, 43]，以安全地管理 C API [14] 的生命周期和严格的线程模型 [14]。
4. 功能裁剪成本：必须投入架构时间，分析并主动（通过 GN [22]）禁用 V8 和 XFA [35]，以避免不必要的“功能臃肿”。

III. 公共 API 层 (public/)：嵌入者的合约

public/ 目录 [5, 44] 是 PDFium 的“门面”。它包含了所有面向嵌入者的头文件，这些头文件共同定义了 PDFium 的公共 API。这是嵌入者与 PDFium 内部实现之间的“铁律合约”。

3.1 API 设计哲学：纯 C、句柄（Handle）与不透明指针

PDFium 的公共 API [14] 遵循一个经典且健壮的 C 语言 SDK 设计模式：

• 纯 C 接口：所有公共 API 都是纯 C 函数 [14]。
• 不透明指针 (Opaque Pointers)：API 通过“句柄”（Handles）来操作所有对象。这些句柄被 typedef 为不透明的指针，例如 typedef struct fpdf_document_t__* FPDF_DOCUMENT; [14]。其他句柄包括 FPDF_PAGE、FPDF_BITMAP、FPDF_TEXTPAGE 等 [14, 45]。

这是一个深思熟虑的架构决策，带来了三大好处：

1. ABI 稳定性 (Application Binary Interface)：C++ 缺乏稳定的 ABI（由于名称修饰、虚表布局等）。纯 C API 确保了稳定的 ABI。这意味着 PDFium 的 C++ 内部实现可以随意重构（例如，切换 std::map 为 absl::flat_map），而不需要重新编译嵌入者的代码，只要 C API 签名不变。
2. 语言互操作性 (Interoperability)：C API 是“通用语言”。这使得 PDFium 可以被任何能调用 C 的语言轻松封装，如 C# (Patagames [30, 46])、Go (go-pdfium [47, 48])、Rust (pdfium-render [42, 43])、Python (pypdfium2 [27]) 和 Dart [49]。
3. 强制封装 (Encapsulation)：嵌入者无法（也不应该）直接访问内部的 C++ 对象（如 CPDF_Document [16]）。这强制执行了严格的封装，防止了实现细节的泄露，并使得 API 团队可以自由地改进内部实现，而不必担心破坏外部依赖 [50]。

3.2 fpdfview.h 详解：库、文档、页面的生命周期管理

fpdfview.h [14] 是最核心的头文件，它定义了库和文档的基本生命周期。

API 强制执行了一个严格、手动的资源生命周期管理模型 [51]：

1. 库 (Library)：FPDF_InitLibraryWithConfig() [14, 24] 必须在任何其他调用之前被调用，以初始化全局资源。FPDF_DestroyLibrary() [14, 24] 必须在最后被调用，以释放这些资源。
2. 文档 (Document)：FPDF_LoadDocument() [24]、FPDF_LoadMemDocument() [14, 52] 或 FPDF_LoadCustomDocument() [53] 用于加载 PDF 并返回一个 FPDF_DOCUMENT 句柄。操作完成后，必须调用 FPDF_CloseDocument() [24, 51] 来释放文档句柄和相关的所有资源。
3. 页面 (Page)：FPDF_LoadPage() [14, 51] 用于加载特定页面并返回 FPDF_PAGE 句柄。操作完成后，必须调用 FPDF_ClosePage() [51] 来释放页面资源。

这是 C API 最大的危险。资源管理完全依赖于开发者的纪律。忘记调用 FPDF_ClosePage [54] 或 FPDF_CloseDocument 将导致严重的内存泄漏 [54, 55]。

对于架构师而言，这意味着任何 PDFium 集成必须做的第一件事就是构建 RAII (Resource Acquisition Is Initialization) 包装器。

• 在 C++ 中，这意味着使用 std::unique_ptr 配合自定义 Deleter（例如，std::unique_ptr<fpdf_document_t__, decltype(&FPDF_CloseDocument)>）。
• 在 Rust 中，这意味着为 FPDF_DOCUMENT 包装器实现 Drop trait [42]。
• 在 Go 中，这意味着使用 runtime.SetFinalizer。

绝不允许在生产代码中手动调用这些 Close 函数。

3.3 线程模型：非线程安全（Single-Threaded）的设计及其对嵌入者的要求

fpdfview.h 的头文件注释 [14] 中包含一个至关重要的架构警告：

“NOTE: None of the PDFium APIs are thread-safe.”

“Barring that, embedders are required to ensure (via a mutex or similar) that only a single PDFium call can be made at a time.”

这是一个有意的设计选择，而不是一个缺陷。使一个像 PDFium 这样复杂的 C++ 库（充满缓存、状态和复杂的对象图）线程安全，将带来巨大的性能开销（例如，到处都是细粒度锁）和复杂性。PDFium 选择将此责任完全推给嵌入者，以换取无锁的单线程性能。

这对并发应用程序的架构有重大影响：

1. “简单”模型（全局锁）：在所有 PDFium 调用周围放置一个全局互斥锁 (Global Mutex)。pdfium-render [56] 库就是这样做的。这保证了安全 [14]，但扼杀了所有并行性。在一个 32 核的服务器上，您的 PDFium 实例仍然一次只能处理一个请求，使其成为系统瓶颈。
2. “高性能”模型（工作池）：创建一个工作池 (Worker Pool)。池中的每个工作线程（或进程）都拥有其自己的、完全独立的 PDFium 实例（可能需要 FPDF_InitLibrary）。一个主线程将 PDF 渲染任务分派到队列中，工作线程（在它们自己的线程上）串行地处理这些任务。

go-pdfium 库 [48] 明确地实现了这种高性能模型。对于任何严肃的服务器端应用，架构师必须选择“高性能”模型。这意味着 PDFium 不是一个简单的“链接库”，而是需要围绕它构建一个服务架构（例如，一个微服务或一个线程池服务）。

3.4 错误处理机制：FPDF_GetLastError()

PDFium 采用了一种类似于 Win32 GetLastError() 或 C errno 的错误处理机制。

当一个函数（如 FPDF_LoadDocument [24]）失败时，它通常会返回一个哨兵值（如 NULL 或 FPDF_BOOL 的 false）。fpdfview.h [14] 的注释指引开发者：“If this function fails, you can use FPDF_GetLastError() to retrieve the reason why it failed.”

FPDF_GetLastError() 会返回一个线程局部存储（Thread-Local Storage）中的错误代码。这种机制简单但脆弱：

1. 非线程安全：如果您违反了 3.3 中的单线程规则，FPDF_GetLastError() 返回的值将是不可预测的（竞态条件）。
2. 必须立即调用：您必须在失败的 API 调用之后立即调用 FPDF_GetLastError()。任何成功的 PDFium API 调用都可能会清除这个错误代码。

架构师的责任：在 RAII 包装器中（见 3.2），在检查到 NULL 或 false 返回值时，必须立即调用 FPDF_GetLastError() 并将其转换为一个更健壮的错误类型（如 C++ 异常、std::error_code 或 Rust Result），然后再执行任何其他操作。

3.5 平台抽象层 (Platform Abstraction Layer)

PDFium 是一个被动的库。它不直接执行任何平台相关的操作，如文件 I/O 或系统字体查找。相反，它通过 C 回调结构（Callback Structs）要求嵌入者（Embedder）为其执行这些操作。

这是 PDFium 得以跨平台（从 Windows [57] 到 Android [5, 58] 再到 WebAssembly [59]）的核心架构模式。

1. I/O 抽象 (FPDF_FILEACCESS)：
   FPDF_LoadDocument() [24] 接受一个文件路径，但这是最不灵活的方式。FPDF_LoadCustomDocument() [52, 53] 接受一个 FPDF_FILEACCESS [53] 结构体。这个结构体 [41, 60] 基本上只包含两个字段：文件大小和一个函数指针 m_GetBlock [61]。
   嵌入者需要实现 m_GetBlock [61] 回调。PDFium 在解析时会调用它，说：“请给我从偏移量 X 开始的 Y 字节数据”。这使得嵌入者可以从任何地方（内存、网络、数据库）为 PDFium 提供数据流，而 PDFium 对此一无所知。fpdf_dataavail.h [62] 中定义的 FX_FILEAVAIL 接口进一步增强了这一点，允许检查数据是否可用，以支持线性化 PDF 的渐进式加载。

2. 字体抽象 (FPDF_SYSFONTINFO)：
   fpdf_sysfontinfo.h [63] 定义了 FPDF_SYSFONTINFO 接口。PDFium 不知道如何从 /usr/share/fonts 或 C:\Windows\Fonts 读取字体。当它遇到一个 PDF 中引用但未嵌入的字体时，它会通过这个回调接口询问嵌入者：“我需要 ‘Arial’，请给我它的数据流。”
   或者，嵌入者也可以在 FPDF_InitLibraryWithConfig() [24, 64] 中提供一个 m_pUserFontPaths 路径列表。
   如果嵌入者（例如，一个 Wasm 应用 [65] 或一个最小的 Docker 容器）未能提供此接口或字体路径，PDFium 将无法找到任何系统字体，导致文本显示为乱码或空白 [65]。

架构师的责任：您必须实现这些平台回调。 它们是集成的必要部分，而不是可选的。

IV. 核心内部机制：PDF 对象模型与内存管理

public/ 层之下是 fpdfsdk/（桥接层），fpdfsdk/ 之下是 core/（核心引擎）。core/ 目录是 PDFium 的心脏，它在 C++ 层面实现了 PDF 规范。

4.1 core/fpdfapi/parser：PDF 解析器与对象工厂

core/fpdfapi/parser [16, 17] 目录包含了 PDF 的核心解析逻辑。cpdf_parser.cpp [66] 包含了解析器本身，它负责：

1. 读取原始的 PDF 字节流。
2. 查找和解析 xref（交叉引用表）或 Cross-Reference Streams。
3. 根据这些信息构建一个内存中的对象图。
4. cpdf_document.cpp [16] 则负责管理文档级结构，例如页面树（Page Tree, /Type /Pages）。

PDF 解析是一个高度复杂且充满安全风险的过程。这个模块是 PDFium 的主要攻击面之一，也是 ClusterFuzz [12] 的重点测试对象。此模块必须能够优雅地处理来自 Fuzzer 的各种损坏和恶意的输入。

4.2 CPDF_Object 继承体系：CPDF_Dictionary, CPDF_Array, CPDF_Stream 等

core/fpdfapi/parser/cpdf_object.h [67] 定义了 PDF 内存对象模型的基类 CPDF_Object。

PDFium 采用了经典的多态面向对象设计。CPDF_Object 是一个基类，它有多个子类，直接对应于 PDF 规范中的基本数据类型 [14, 45]：

• CPDF_Dictionary [17] (对应 /Type /Dict)
• CPDF_Array [16] (对应 [...])
• CPDF_Stream [16] (对应 stream/endstream)
• CPDF_Number [66] (对应数字)
• CPDF_Name (对应 /Name)
• CPDF_String (对应 (...) 或 <...> )
• CPDF_Reference (对应 1 0 R)
• CPDF_Null (对应 null)

cpdf_parser [66] 的工作就是将 PDF 字节流物化（Materialize）为这个强类型的 C++ 对象图。例如，CPDF_Dictionary [17] 内部使用 std::map 来存储键值对。

这种设计是其性能的关键：PDFium 是一个**“解析一次，多次访问”**的系统。一旦 PDF 被解析为这个对象图，后续的渲染、文本提取等操作都将访问这个内存中的强类型结构，而不需要重新解析原始字节流。

4.3 内存管理：侵入式引用计数与 RetainPtr<T> 智能指针

PDFium 不使用 C++11 的 std::shared_ptr。它实现了一套自定义的、侵入式（Intrusive）的引用计数系统。

1. 侵入式设计：对象（如 CPDF_Object、CFX_GlyphCache [68]）会继承自一个 Retainable 基类（该基类在对象内部维护一个原子引用计数器），并实现 Retain() 和 Release() 方法。
2. RetainPtr<T>：core/fxcrt/retain_ptr.h [69] 中定义了 RetainPtr<T>。这是一个智能指针，其行为类似于 std::shared_ptr：它在构造/赋值时调用对象的 Retain()，在析构时调用 Release()。当引用计数降至零时，Release() 方法会 delete this。
3. 广泛使用：RetainPtr<T> 在 PDFium 的 core C++ 代码中被广泛使用 [66, 70]。CONSTRUCT_VIA_MAKE_RETAIN [69, 71] 宏被用来强制使用 MakeRetain<T>() 工厂函数来创建对象，确保其在堆上分配并正确初始化。

为什么不使用 std::shared_ptr？

这是一个性能和内存的权衡。std::shared_ptr 需要一个单独的控制块（Control Block）来存储引用计数，这会（轻微地）增加内存开销（每次分配 shared_ptr 都需要额外分配控制块）和内存局部性（Indirection）开销。侵入式引用（计数器在对象内部）更快，内存布局更紧凑。这是高性能 C++ 库（如游戏引擎、浏览器内核）的常见模式。

架构风险：循环引用 (Circular References)。

这种系统的最大风险是循环引用。如果 CPDF_Dictionary A 持有一个指向 B 的 RetainPtr，而 B 同时持有一个指向 A 的 RetainPtr，它们的引用计数将永远不会降到零，从而导致内存泄漏。[17] 中 CPDF_Dictionary 的头文件也引入了 weak_ptr.h，这表明 PDFium 确实使用弱指针（Weak Pointers）来解决这个问题，但这依赖于开发人员的纪律。

4.4 PDF 对象生命周期与潜在的内存泄漏风险

PDFium 的内存模型因缓存和 C API 边界而变得复杂。

• 对象缓存：[54] 中报告了一个典型的内存泄漏问题：调用 FPDF_RenderPageBitmap 然后 FPDF_ClosePage 后，内存使用量持续增加，并不会在页面关闭时释放。内存只有在 FPDF_CloseDocument 时才被释放。这表明页面引用的资源（如字体 CPDF_Font 或图像）在文档级别（CPDF_Document）被缓存 [72]。FPDF_ClosePage 只是释放了页面对象本身，但并未清除文档级的缓存。
• C API 边界泄漏：[55] 报告了在 FPDF_LoadCustomDocument 加载失败时，GetBlockCallback 回调仍可能被引用，导致 PdfCustomLoader 无法被垃圾回收，从而泄漏整个 PDF 文件的内存。
• API 包装困难：[42] 中一位 Rust 开发者详细描述了包装 PDFium C API 的困难。C API（如 FPDF_LoadCustomDocument [60]）要求 FPDF_FILEACCESS [53] 中的数据缓冲区在 FPDF_DOCUMENT 的整个生命周期内都保持有效。这在 Rust 的安全借用检查器（Borrow Checker）下创建了一个“自引用结构”（PdfDocument 引用了它自己拥有的 bytes），这是极其困难的 [42]。

架构师结论：PDFium 的 C API虽然具有跨语言互操作性，但其生命周期管理规则是为 C/C++ 的“不安全”内存模型设计的。将其封装到 Rust 或 Swift 等具有严格生命周期管理的语言中时，必须特别注意 I/O 和内存的生命周期，这比在 C++ 或 Go [48] 中要复杂得多。

V. 渲染管线深度解析 (fxge)

fxge (Foxit Graphics Engine) 是 PDFium 渲染管线的核心。它是一个抽象层，将 core 引擎的抽象绘制命令转换为具体的像素。

5.1 FPDF_RenderPageBitmap 调用流

FPDF_RenderPageBitmap() [54] 是一个高层 API，用于将 PDF 页面渲染到内存位图（Bitmap）[73]。它是一个便捷封装。

真正的入口点是 FPDF_RenderPage() [57, 74]。此函数可以渲染到各种“设备”，例如 Windows 的设备上下文（DC），这允许直接渲染到打印机 [57] 或 EMF（增强型图元文件）[74]。

一个简化的渲染调用流如下：

1. Embedder (C API)：调用 FPDF_RenderPage(..., page,...) [74]。
2. fpdfsdk (Wrapper)：将 FPDF_PAGE 句柄转换为内部的 CPDF_Page [75] C++ 对象。创建一个具体的 CFX_RenderDevice [76]（例如，基于 GDI DC [74] 或 DIBitmap [73]）。
3. core (Engine)：创建一个 CPDF_RenderContext [77] 和一个 CPDF_RenderStatus [78]。
4. core (Engine)：遍历 CPDF_Page [75] 上的所有 CPDF_PageObject（页面对象，如路径、文本、图像）[77]。
5. core (Engine)：对于每个对象，调用 CFX_RenderDevice [76] 上的相应虚方法（例如 device->DrawPath()）。
6. fxge (Device)：CFX_RenderDevice 的具体实现（如 CFX_AggDevice 或 CFX_SkiaDevice [79]）接收这些抽象命令，并将它们转换为最终的像素。

5.2 渲染上下文：CPDF_RenderContext 的角色

cpdf_rendercontext.h [77] 定义了 CPDF_RenderContext。它是一个状态机。

它在构造时需要 CPDF_Document 和 CPDF_PageImageCache [77]，持有渲染一个页面所需的所有“上下文”信息，例如对文档对象（CPDF_Document）的引用、页面资源（字体、图像）以及对图像缓存（CPDF_PageImageCache）的访问。

CPDF_RenderContext 的存在是为了支持渐进式渲染（Progressive Rendering）。CPDF_ProgressiveRenderer [78]（在 public/fpdf_progressive.h 中暴露）会持有 CPDF_RenderContext [77]。Continue() [78] 方法可以被多次调用，它会使用 CPDF_RenderContext 来恢复上一次的渲染状态，并继续渲染接下来的 kStepLimit（例如 100 个）[78] 对象，然后返回 ToBeContinued 状态。

这允许嵌入者在渲染一个复杂的页面时（不会阻塞主线程）可以“让出”CPU，从而实现响应式 UI。

5.3 图形设备抽象：CFX_RenderDevice 接口

CFX_RenderDevice [76, 80] 是 fxge 中最关键的接口。它被 CPDF_RenderContext [77] 和 CPDF_ProgressiveRenderer [78] 持有和调用。

这是一个经典的“访问者模式”或“端口与适配器”架构。core 渲染引擎（“端口”）是完全不可知的。它只知道如何调用 CFX_RenderDevice 上的虚方法（例如 DrawPath, DrawImage, DrawText）。

具体的 CFX_RenderDevice（“适配器”）负责将这些抽象的“绘制”命令转换为实际的输出：

• CFX_AggDevice [37] 会将其转换为 AGG 栅格化调用。
• CFX_SkiaDevice [79] 会将其转换为 Skia 画布调用。
• [74] 中 FPDF_RenderPage(dc,...) 使用的 CFX_WindowsDevice [80] 会将其转换为 Windows GDI 调用（例如 Rectangle()）。

这是 PDFium 中最强大的（尽管是内部的）扩展点。理论上，架构师可以实现自己的 CFX_RenderDevice，将 PDF 页面“渲染”到任何后端（例如，SVG 文本、OpenGL 调用、3D 纹理）。

5.4 实现对比：AGG vs. Skia

PDFium 内部支持两个主要的栅格化后端：

1. AGG (Anti-Grain Geometry)：这是默认的后端 [37]。它通过 pdf_use_skia = false [22] 启用，并依赖于 third_party/fx_agg [19]。AGG 是一个高质量的 2D 矢量图形栅格化库。这是 Foxit 时代 [1] 继承的技术遗产，久经考验且非常稳定 [28]。
2. Skia：这是一个实验性后端 [18]，通过 pdf_use_skia = true [22] 启用。CFX_SkiaDevice [79] 是其实现。Skia 是 Google 的 2D 图形库，是 Chrome、Android 和 Flutter 的基石。

这是一个关键的架构合并决策。

• 使用 AGG（默认）：这是最稳定、最久经考验的路径。对于纯 CPU 栅格化，性能可能非常高。
• 使用 Skia [22]：这是未来的方向。其最大的好处是资源合并。如果您的应用程序已经使用了 Skia（例如，您是 Electron、CEF 或 Flutter 应用），启用此标志 [18] 意味着您不需要同时交付和运行 AGG 和 Skia 这两个庞大的图形库。这显著减小了二进制大小和内存占用。尽管它被标记为“实验性” [18]，但它在 Chromium [37] 中使用，并受到 Fuzzer [13] 的严格测试，因此非常稳定。

VI. 关键子系统：字体引擎与 FreeType 集成

字体是 PDF 渲染的核心，也是最复杂的部分之一。PDFium 的字体引擎（fxge 的一部分）与 FreeType 库深度集成。

6.1 fxge 中的字体管理与替换逻辑

core/fxge/fx_font.h [81] 定义了字体的核心属性（如 FXFONT_BOLD, FXFONT_FF_ROMAN）。当 PDF 请求一个字体（例如，”Helvetica”）但该字体未嵌入在 PDF 文件中时，PDFium 的字体管理器必须执行字体替换。

这是一个双重责任架构：

1. PDFium 的责任：处理所有嵌入在 PDF 流中的字体，以及 14 种 PDF 标准字体（如 Helvetica, Times-Roman）。
2. 嵌入者的责任：提供系统字体。如 3.5 节所述，PDFium 通过 FPDF_SYSFONTINFO [63] 回调接口或 m_pUserFontPaths [24, 64] 列表来请求系统字体。

如果嵌入者（例如，一个 WebAssembly 应用 [65] 或一个最小的 Docker 容器）未能履行其责任，PDFium 将无法找到系统字体，导致文本（如 [65] 中的土耳其语字符）无法正确显示。

6.2 CFX_GlyphCache：字形缓存机制

core/fxge/cfx_glyphcache.h [68] 定义了 CFX_GlyphCache 类。这是一个关键的性能优化层。

文本渲染很慢，因为它涉及两个步骤：

1. 栅格化：使用 FreeType 将矢量字形（字符形状）转换为位图。
2. 绘制：将该位图绘制到 CFX_RenderDevice 上。

步骤 1（栅格化）非常耗时。CFX_GlyphCache [68] 是一个*“记忆” (memoization)* 层。当渲染引擎请求一个字形时（通过 LoadGlyphBitmap() [68]），缓存会检查它是否（在特定字体和尺寸下）已被栅格化：

• Cache Miss (缓存未命中)：缓存调用 FreeType（慢速路径），将生成的位图存储在 std::map [68] 中，然后返回它。
• Cache Hit (缓存命中)：缓存直接从 map 中返回先前栅格化的位图（快速路径）。

对于 CJK（中日韩）等具有数万个字形的字体，此缓存的内存占用可能相当可观，这是架构师应注意的内存权衡。

6.3 FreeType 集成：PDFium 如何封装和调用 FreeType

如 2.3 节所述，PDFium 与 FreeType 的集成是高度耦合和脆弱的。

• PDFium 默认捆绑 FreeType (pdf_bundle_freetype = true [18])。
• FreeType 源码位于 third_party/freetype [20]。
• PDFium 对 FreeType 有本地修改，包括依赖一个非公开的头文件 pstables.h [20, 38]。
• 尝试使用系统 FreeType [39] 会导致构建失败，因为它缺少 pstables.h [38]。

这是一个针对“使用系统库”的主要架构红灯。架构师必须放弃“链接到系统 FreeType 以减小二进制大小”的想法。必须使用 PDFium 捆绑的、经过修补的 FreeType 版本。

6.4 平台字体与嵌入字体的处理

架构师必须区分渲染和文本提取这两个完全不同的概念。

• 渲染 (Rendering)：只需要字形（Glyphs）。PDFium 从（1）嵌入字体，（2）系统字体（通过 [63] 回调），或（3）替换字体中获取字形并绘制 [81]。
• 文本提取 (Text Extraction)：需要Unicode 字符。公共 API fpdf_text.h [82] 提供了 FPDFText_LoadPage 来提取文本。这依赖于 PDF 内部的 ToUnicode 映射表 [83]。

PDF 内部可能只存储了“字符代码 1”，ToUnicode 映射表会告诉 PDFium“代码 1 = ‘A’”。如果此映射表丢失或损坏，FPDFText_LoadPage [82] 将返回无意义的字符（如 [83] 中的 “VFKDDO”），即使 PDF 渲染看起来完全正确。

当用户报告“文本无法复制” [83] 或“文本显示不正确” [65] 时，必须区分这是渲染问题（[65]，可能是字体可用性问题）还是文本提取问题（[83]，可能是 ToUnicode 映射问题）。

VII. 深入字体处理：渲染回退与编辑策略

在 PDFium 中，“字体处理”在渲染（查看）和编辑（创建）两个场景下的逻辑截然不同。架构师必须理解这两种模式下的回退（Fallback）策略。

7.1 字体类型：嵌入、子集与未嵌入

首先，PDF 中的字体可以分为三类：

1. 完全嵌入 (Embedded)：整个字体文件（如 .ttf）包含在 PDF 中。这保证了在任何系统上都能完美渲染，但会使文件变大。
2. 子集嵌入 (Subset)：仅嵌入 PDF 中实际使用到的字符（例如，只嵌入 “H”, “e”, “l”, “o” 的字形）。这在保证渲染的同时显著减小了文件大小。PDFium 在保存时通常会执行此操作。
3. 未嵌入 (Non-Embedded)：PDF 仅引用一个字体名称，例如 “Helvetica” 或 “ArialMT”。它期望查看器（PDFium）在宿主操作系统上找到这个字体。

7.2 渲染回退 (Viewing Fallback)：字体替换

当 PDFium 渲染一个未嵌入字体的 PDF 时，会触发**字体替换（Substitution）**机制。这是最常见的回退场景。

1. CFX_FontMapper：此机制的核心是 core/fxge/cfx_fontmapper.cpp。当 CPDF_RenderContext 需要一个未嵌入的字体时，它会请求 CFX_FontMapper 去查找一个替代品。
2. 查找逻辑 (FindSubstFont)：CFX_FontMapper::FindSubstFont 的逻辑大致如下：
   • 清理名称：它会智能地清理字体名称。例如，对于子集字体，它会剥离随机前缀（如 YATXCX+Arial 会被识别为 Arial）。
   • 映射标准字体：它会将 PDF 规范定义的 14 种标准字体（如 “Helvetica”, “Times-Roman”）映射到常见的系统字体（如 “Arial”, “Times New Roman”）。例如，”Symbol” 字体会被特殊处理，以强制回退到 PDFium 内置的 Symbol 字体。
   • 询问嵌入者：如果字体非标准，PDFium 会通过 3.5 节中提到的平台抽象层询问嵌入者。这有两种方式：
     1. m_pUserFontPaths：在 FPDF_InitLibraryWithConfig [24, 64] 时传入一个字体目录列表。PDFium 会扫描这些目录。
     2. FPDF_SYSFONTINFO：实现这个回调接口 [63]，PDFium 会主动调用它来枚举或映射字体。
3. 失败的后果：如果上述所有步骤都失败（例如，在 Wasm [65] 或最小 Docker 容器 中，没有提供系统字体），CFX_FontMapper 将无法找到合适的替代品。这会导致 CJK（中日韩）等非拉丁字符显示为“豆腐块”（tofu, □）或空白，或者像 中那样，Cyrillic 字符无法显示。

7.3 渲染回退 (Viewing Fallback)：字形回退

这是一个更复杂、更细粒度的回退，发生在字体已找到（无论是嵌入的还是替换的），但该字体不包含所有需要的字形时。

例如，一个 PDF 页面使用了一个（未嵌入的）韩语 Hangul 字体，PDFium 成功将其替换为系统上的韩语字体。但如果这段文本中混杂了拉丁字符（如 “Hangul text with Latin chars”），而这个韩语字体本身不包含拉丁字母，会发生什么？

• 内部回退列表：PDFium 在内部 CPDF_Font 类中维护一个 font_fallbacks_ 向量（列表）。
• 逐字检查：在渲染文本时，如果 CPDF_Font 发现其主字体（m_Font）不支持某个字符（例如，”L”），它会遍历 font_fallbacks_ 列表，尝试用列表中的字体来渲染该字符。
• 硬编码的后备：在历史上（如一个 2016 年的提交 中），这个回退列表被硬编码为包含 “Arial”。这样做的目的是确保即使用户正在查看的（例如）韩语字体不包含拉丁字符，那些拉丁字符也能被 “Arial” 抓取并正确显示，而不是变成空白。
• 渲染优化：渲染器（CPDF_TextRenderer）足够智能，它不会为每个字符都切换字体。它会“批处理”使用相同字体（无论是主字体还是回退字体）的连续字符，以最小化对 CFX_RenderDevice 的绘制调用。

7.4 编辑场景 (Editing Scenario)：回退即责任

这是您问题的核心。当使用 public/fpdf_edit.h API 添加新文本时，回退逻辑完全不同：几乎没有自动的字形回退，责任完全在于嵌入者。

1. 编辑的字体 API：要在 PDF 上创建新文本，嵌入者必须：

   • 获取 FPDF_FONT 句柄：你不能只告诉 PDFium “用 Arial 字体”。你必须提供一个字体。
   • FPDFText_LoadFont：这是关键 API。嵌入者必须从文件系统（或内存）加载一个 .ttf 或 .otf 文件的原始字节，并将这些字节传递给 FPDFText_LoadFont。PDFium 会（在文档内部）创建一个字体对象，并返回一个 FPDF_FONT 句柄。这实际上是将该字体嵌入到了 PDF 中（或至少是其子集，当保存时）。
   • FPDFPageObj_CreateTextObj：然后，嵌入者使用这个 FPDF_FONT 句柄来创建文本对象。

2. “回退”在哪里？

   • 回退在于嵌入者的应用逻辑，而不是 PDFium 内部。
   • 假设一个 C# 嵌入者加载了 arial.ttf 并获得了 FPDF_FONT arialFont 句柄。如果用户试图输入 “你好” 并使用 arialFont 句柄去创建文本对象，PDFium 不会自动去系统里寻找 CJK 字体 来回退。它只会尝试使用 arialFont 来渲染 “你好”，结果将是无意义的乱码（如 中报告的 “ÿÿÿÿÿ”）。
   • 正确的编辑架构：一个健壮的 PDF 编辑器（嵌入者）必须自己实现类似 CSS font-family 的回退栈。
     1. 应用在启动时，通过 FPDFText_LoadFont 加载多种字体，例如：arial_font = FPDFText_LoadFont("arial.ttf"...)、noto_cjk_font = FPDFText_LoadFont("NotoSansCJK.otf"...) 等。
     2. 当用户输入文本时，应用自己必须分析文本内容。
     3. 如果文本是 “Hello”，应用选择 arial_font 句柄调用 FPDFPageObj_CreateTextObj。
     4. 如果文本是 “你好”，应用必须智能地切换到 noto_cjk_font 句柄来调用 FPDFPageObj_CreateTextObj。
     5. 如果文本是 “Hello 你好”，应用必须创建两个独立的文本对象（FPDFPageObject），一个用于 “Hello”（使用 arial_font），另一个紧邻其后，用于 “你好”（使用 noto_cjk_font）。

总之，在渲染时，PDFium 拥有复杂的自动字体替换 和字形回退 机制。但在编辑时，PDFium 假设嵌入者是专业的，它只提供加载字体 和使用字体的工具；而选择哪个字体的“回退”责任，则完全交给了嵌入者。

VIII. 关键子系统：JavaScript 引擎 (fxjs) 与 V8 绑定

PDFium 能够执行嵌入在 PDF 文档中的 JavaScript，主要用于 AcroForms（标准表单）和 XFA（动态表单）的交互逻辑。这是通过 fxjs 模块和 Google 的 V8 引擎实现的。

8.1 fxjs 模块职责：连接 PDF 运行时与 V8 虚拟机

fxjs 是一个顶层目录 [5, 21]，它是一个翻译层或绑定层。它是 PDFium 内部唯一同时理解 PDFium C++ 内部对象（例如，CPDF_Annot）和 V8 C++ API（例如，v8::Object）的模块。

该模块包含：

• cfx_v8.cpp / cfx_v8.h：V8 引擎的通用绑定和帮助类 [21]。
• cjs_app.cpp, cjs_annot.cpp：PDF 特定 JavaScript 对象（如 app, Annot）的 C++ 实现 [21]。

这是 PDFium 的核心安全边界之一。除了 PDF 解析器，fxjs 是第二大攻击面。此处的漏洞（例如，cfx_v8.cpp [21] 中的类型混淆或生命周期错误 [84]）可能导致 V8 沙箱逃逸。

架构师的黄金法则：如果您不需要 AcroForms [85] 或 XFA [36] 脚本，必须在构建时设置 pdf_enable_v8 = false [35, 64]。 这将极大地减小二进制大小、内存占用和安全攻击面。

8.2 cfx_v8.h：C++ 与 JavaScript 的绑定层

PDFium 实现了一个自定义的 C++ 到 V8 的绑定框架，而不是直接使用 V8 的（复杂的）C++ API。fxjs_v8.h [86, 87] 是一个内部帮助层，”makes it easier to define native objects in V8”。

它提供了 CFX_V8 [88] 等帮助类，用于管理 v8::Isolate、v8::Context 和 v8::ObjectTemplate [89] 的创建。

这是 V8 嵌入的经典模式。fxjs/ [21] 中的 C++ 代码会为 PDF JS 对象（如 “App”, “Annot”）创建 v8::ObjectTemplate，并将 C++ 回调函数（如 cjs_app.cpp）附加到 JS 函数名上。当 PDF 中的 JS 调用 app.alert() [90] 时，V8 将此调用路由回 cjs_app.cpp 中绑定的 C++ 函数。

8.3 V8 Isolate 与 Context 管理：FPDF_InitLibraryWithConfig 的角色

v8::Isolate 是一个重量级的对象，代表一个独立的 VM 实例、堆和垃圾收集器。高效地管理 Isolate 是 V8 集成的核心。

FPDF_InitLibraryWithConfig() [24, 64] API 通过 FPDF_LIBRARY_CONFIG 结构体 [91] 为架构师提供了一个关键的决策点。该结构体包含 m_pIsolate 和 m_pPlatform 字段 [24, 64]。

1. 传入 NULL（简单方式）：如 simple_with_v8.cc [91] 示例所示，如果 config.m_pIsolate 为 NULL [92]，PDFium 将创建并拥有自己的 V8 Isolate。这很简单，但如果您的主应用程序也使用 V8（例如，您是 Node.js、Electron 或 CEF 应用），您的进程中现在将有两个（或更多）V8 实例，这是巨大的内存浪费和性能开销。
2. 传入现有的 Isolate（合并方式）：这是 Chromium 的方式 [39]。浏览器管理一个主 Isolate，并将其“借”给 PDFium [24]。simple_with_v8.cc [91] 展示了嵌入者如何初始化 V8 并将 Isolate 和 Platform 传入 FPDF_InitLibraryWithConfig()。

架构师建议：如果您的宿主应用已使用 V8，您必须选择合并方式 [39]。 尽管这增加了集成复杂性（您需要管理 V8 的生命周期），但它可以避免“V8 in V8”的资源灾难。

8.4 AcroForms 脚本支持的实现

PDFium 中的 JavaScript 不是一个浏览器环境。它是一个沙盒化的、最小化的Acrobat JS API [90] 实现。此 API 是特定于 PDF 的，包含 app、doc、field [93] 等对象，并提供 FORM_DoDocumentJSAction [85] 等 API 来执行它们。

[90] 中的分析是关键：PDFium 支持 app.alert(1)（Acrobat JS API）但不支持 confirm(1)（浏览器 JS API）。这是一个安全特性，而不是一个 bug。它证明了沙箱是有效的，防止 PDF 中的 JS 访问浏览器级别的功能或执行任意的 Web 脚本。

架构师必须告知产品经理，PDFium 的“JS 支持”仅限于 PDF 表单逻辑 [85]，不能用于运行任意的 Web 脚本。

IX. 关键子系统：表单架构 (AcroForms 与 XFA)

PDFium 支持两种完全不同且互不兼容的表单技术。

9.1 AcroForms：标准 PDF 表单的实现

AcroForms 是 PDF 规范原生的、标准的交互式表单技术 [93]。

• API：fpdf_formfill.h [44] 是其公共 API。
• 实现：fpdfsdk/formfiller/ [15] 是 SDK 层的实现。
• 对象模型：AcroForms 是一个“跨越整个文档的单一、全局交互式表单” [93]。它由 PdfField（字段，定义数据）和 PdfControl（控件，定义外观）组成 [93]。

AcroForms 具有双重依赖：

1. 数据模型：字段、值、外观 [93] 是 core 和 fpdfsdk/formfiller [15] 的一部分。
2. 脚本：字段的计算、验证和格式化（例如，日期或数字）[85] 依赖于 fxjs/V8。

架构师结论：要获得完整的 AcroForms 功能，您必须启用 V8 (pdf_enable_v8 = true [22])。如果禁用 V8 [35]，表单字段可能可见但无法交互，或者计算字段将无法更新。

9.2 XFA 架构 (xfa/)：一个并行的 XML 表单世界

xfa [5, 23, 94] 是一个独立的顶层目录。XFA (XML Forms Architecture) [23] 不是 PDF。它是一个 XML 数据包，被嵌入在一个 PDF “包装器”中。

渲染一个 XFA PDF 意味着 PDFium 完全绕过其 core PDF 渲染管线。

xfa/ [23] 目录是 PDFium 内部的“第二引擎”。它有自己的 XML 解析器、自己的布局引擎（需要实现 CSS 的一个子集）和自己的渲染逻辑。这是一个极其庞大和复杂的子系统。

9.3 XFA 对 V8 的强依赖及其性能影响

XFA 规范深度依赖 JavaScript 来实现其所有动态逻辑（例如，表单的动态增长、计算和 Web 服务调用）。

• 构建配置 pdf_enable_xfa “暗示了 JS 支持” [22]。
• README 中明确指出“XFA 功能需要 JavaScript” [36]。

这是对架构师的终极配置警告。启用 pdf_enable_xfa = true [18, 22] 会带来：

1. 整个 xfa/ [23] 模块（一个 XML 布局和渲染引擎）。
2. 整个 fxjs [21] 模块（V8 绑定）。
3. 整个 V8 虚拟机。

这将导致二进制大小、内存占用和安全攻击面的爆炸性增长。

*架构师建议：除非您的客户（例如，政府、银行、保险）用 XFA 表单（通常是动态的）明确要求您支持，否则必须通过 pdf_enable_xfa = false [35] 禁用此功能。*

X. 安全性与稳定性架构：Fuzzing 与加固

PDFium 的核心价值在于其“浏览器级”的安全性。这种安全性不是偶然的，而是其架构设计和 Google 开发流程的直接结果。

10.1 Chromium 的安全模型：沙箱（Sandbox）与 PDFium

一个常见的误解是 PDFium 是一个沙箱。事实并非如此。

PDFium 本身不是沙箱。它是一个 C++ 库。在 Chrome 中，PDFium 运行在一个独立的、受沙箱限制的进程中。

fpdfview.h [95] 中有一个 FPDF_SetSandBoxPolicy() API，它允许设置 FPDF_POLICY_MACHINETIME_ACCESS [95, 96] 等策略。这个 API 的作用是允许沙箱（即 Chrome 进程）通知 PDFium 库：“你正处于沙箱中，不要尝试访问机器时间（例如 time()）”。

这是嵌入者（您）的责任，而不是 PDFium 的功能。简单地链接 PDFium 库不会给您带来 Chrome 级别的安全性。要实现这一点，架构师必须设计一个进程沙箱架构，在单独的、低权限的进程中运行 PDFium，并使用 IPC（进程间通信）与其通信。FPDF_SetSandBoxPolicy [95] 是这个庞大架构工作的最后一步，而不是其本身。

10.2 ClusterFuzz：PDFium 得以健壮的核心

PDFium 稳定性的主要原因是 ClusterFuzz [8]。

ClusterFuzz [8] 是 Google 的可扩展、分布式 Fuzzing 基础设施，它用于 Fuzzing 所有 Google 产品 [8]，包括 Chromium [10] 和 PDFium [9]。

Fuzzing (模糊测试) [10] 是一种测试技术，它将自动生成的、无效的、意外的或随机的数据（“inputs” [10]）作为输入，喂给目标程序，直到其崩溃。

这不是一个一次性的测试；这是一个持续的过程。Google 的庞大基础设施 [8] 正在不断地、大规模地攻击 PDFium [10]。它能发现（如 [11, 12, 13] 所示）人类编写的单元测试永远无法捕获的、复杂的内存损坏漏洞。

这是采用 PDFium 的最大理由。您将免费“继承”Google 顶级的安全测试基础设施。

10.3 关键的 Fuzzers 目标（pdfium_fuzzer）

Fuzzing 是细粒度的。团队不仅 Fuzz FPDF_LoadDocument，还 Fuzz 堆栈深处的单个组件。

• pdfium_fuzzer [12, 13] 是主 Fuzzer，用于测试 PDF 的解析和渲染。
• libfuzzer_pdf_codec_png_fuzzer [11] 是一个专门针对 PNG 编解码器的 Fuzzer。

[11] 中的崩溃报告（”Crash Type: Heap-buffer-overflow READ 1”）显示 Fuzzer 在 CCodec_BmpModule::ReadHeader（BMP 图像的头解析器）中发现了一个堆缓冲区溢出。

这是一种“纵深防御”的测试理念。它表明不仅是 PDFium 的“主干” [12]（如 PDF 解析器），甚至连“毛细血管”（如 [11] 中的 PNG/BMP 解码器）都经过了安全加固。这为架构师提供了极高的信心，相信该库能够抵御恶意文件的攻击。

XI. 资深架构师总结与集成建议

11.1 PDFium 的核心优势（性能、安全性、完整性）

1. 安全性与健壮性 (Security & Robustness)：这是第一优势。 得益于 ClusterFuzz [8, 10] 的持续加固，PDFium 能够抵御恶意的、不可信的输入，使其成为处理用户上传内容（UGC）的理想选择。
2. 性能 (Performance)：专为高性能构建，具有 CFX_GlyphCache [68] 等内部缓存，侵入式引用计数 [69]，以及可切换的图形后端（AGG vs. Skia [18, 37]）。
3. 许可证 (License)：Apache 2.0 [26] 对商业闭源极其友好 [29]。
4. 完整性 (Completeness)：提供了对 PDF 规范（包括 AcroForms [93] 和 XFA [23]）的完整实现，用于“查看、搜索、打印和表单填写” [1]。

11.2 主要架构挑战（构建依赖、线程模型、C API 封装）

挑战是重大的，并且完全是架构层面的。

1. 构建系统 (Build System)：这是最大的集成障碍。 PDFium 不是一个“即插即用”的库。它强制要求使用全套 Chromium depot_tools [6, 7, 22]。您的 CI/CD 必须集成 gclient, GN 和 Ninja。这是不可协商的。
2. 线程模型 (Threading Model)：API 明确非线程安全 [14]。嵌入者必须在外部提供串行化（例如，全局互斥锁 [56]）。对于高并发服务器，这强制要求您构建一个工作池架构 [48]，从而增加了复杂性。
3. C API 封装 (C API Wrapper)：C API [14] 是一个高风险的边界。它强制要求手动、易错的资源管理（Close [51, 54]）。您的团队必须编写一个健壮的 RAII 包装器（例如，C++ unique_ptr [97] 或 Rust Drop [42]）来管理这一切。
4. 功能臃肿 (Feature Bloat)：默认构建 [22] 包含了 V8 和 XFA [36]，它们非常庞大。架构师必须主动地、有意识地裁剪功能（pdf_enable_v8 = false [35]）以获得精简的构建。

11.3 平台抽象层 - 嵌入者责任

以下表格总结了 PDFium 不做什么，以及架构师必须实现什么。

表 3：公共 API - 嵌入者责任

11.4 集成路线图建议

1. 阶段 1：构建与配置 (Build & Config)。投入 1-2 名工程师，只为了在所有目标平台（Linux, Windows, Mac [7]）上成功编译 pdfium_test [22]。可以使用 pdfium-binaries [49] 进行原型设计，但不能用于生产。此阶段的产出是一个可以检出 DEPS [5] 并成功构建的 CI 管道。
2. 阶段 2：功能裁剪 (Feature Pruning)。在编写包装器之前，决定您的功能集。构建一个“精简版”（pdf_enable_v8 = false, pdf_enable_xfa = false [35]）和一个“完整版” [22]。测量二者的二进制大小和内存占用，然后做出架构决策。
3. 阶段 3：C++ 包装器 (C++ Wrapper)。构建您的内部 SDK。这个包装器将使用 RAII 模式（例如，带自定义 deleters 的 std::unique_ptr [97]）来管理 C API 的生命周期 [14, 51]，并实现线程模型（例如，一个单例服务，其所有方法都被互斥锁 [56] 保护）。
4. 阶段 4：平台抽象 (Platform Abstractions)。实现阶段 3.5 中所需的平台回调。这必须包括一个字体策略（实现 FPDF_SYSFONTINFO [63] 或提供 m_pUserFontPaths [24]）和一个自定义 I/O 策略 (FPDF_FILEACCESS [53])。
5. 阶段 5：应用集成 (App Integration)。将您的主应用程序链接到您的内部包装器，而不是直接链接到 PDFium C API。

11.5 风险评估：何时选择 PDFium，何时应避免

• 何时选择 (Choose PDFium if):

  1. 您的首要任务是处理不可信文件的安全性和健壮性 [8, 10]。
  2. 您需要一个高吞吐量的服务器端渲染或数据提取（FPDFText_LoadPage [82]）引擎。
  3. 您需要跨平台（Win, Mac, Linux [9], Android [5]）的一致渲染。
  4. 您的团队已有或愿意投资于 Chromium 构建生态 [6, 7]。
  5. 您需要一个对商业友好的 Apache 2.0 许可证 [26]。

• 何时避免 (Avoid PDFium if):

  1. 您需要一个轻量级的、“只需几 MB”的库，并且无法承担 depot_tools [7] 的构建开销。
  2. 您的主要需求是创建或高级编辑 PDF。PDFium 是查看器优先的 [1]。
  3. 您无法承担工程开销来构建 C API 包装器 [42] 和线程模型 [14]。
  4. 您处于一个极端的资源受限环境（例如，某些 IoT 设备），V8/XFA 的开销 [22] 是不可接受的。在这种情况下，“精简版”构建 [35] 是您唯一的选择。

参考资料

1. Foxit® PDF technology chosen for Google® Open-Source, accessed November 6, 2025, https://www.foxit.com/company/press/1614.html
2. The interesting history (and fascinating future) of PDF software - Foxit, accessed November 6, 2025, https://www.foxit.com/blog/the-interesting-history-and-fascinating-future-of-pdf-software/
3. Foxit® extends PDF software development kit to Mobile devices, accessed November 6, 2025, https://www.foxit.com/company/press/1616.html
4. Foxit PDF SDK (PDFium), accessed November 6, 2025, http://cdn01.foxitsoftware.com/pub/foxit/manual/en_us/FoxitPDFium5_2_DeveloperGuide.pdf
5. chromium/pdfium: The PDF library used by the Chromium project - GitHub, accessed November 6, 2025, https://github.com/chromium/pdfium
6. README.md - pdfium - Git at Google, accessed November 6, 2025, https://pdfium.googlesource.com/pdfium/+show/HEAD/README.md
7. PDFium, accessed November 6, 2025, https://pdfium.googlesource.com/pdfium/+/da587fab57602e5e10c058e6e632df513fba0c93/README.md
8. google/clusterfuzz: Scalable fuzzing infrastructure. - GitHub, accessed November 6, 2025, https://github.com/google/clusterfuzz
9. Git at Google - PDFium, accessed November 6, 2025, https://pdfium.googlesource.com/pdfium/
10. Fuzz testing in Chromium, accessed November 6, 2025, https://chromium.googlesource.com/chromium/src/+/main/testing/libfuzzer/README.md
11. Security: PDFium: Out-Of-Bounds Read in GetDWord_LSBFirst [40084446] - Chromium, accessed November 6, 2025, https://issues.chromium.org/40084446
12. pdfium_fuzzer: Abrt in CPDF_StreamContentParser::AddForm [400244796] - Issue Tracker, accessed November 6, 2025, https://issuetracker.google.com/issues/400244796
13. pdfium_fuzzer: Unexpected-exit in SkAbort_FileLine [41486084] - Issue Tracker, accessed November 6, 2025, https://issuetracker.google.com/issues/41486084
14. public/fpdfview.h - pdfium - Git at Google, accessed November 6, 2025, https://pdfium.googlesource.com/pdfium/+/main/public/fpdfview.h
15. fpdfsdk - pdfium - Git at Google, accessed November 6, 2025, https://pdfium.googlesource.com/pdfium/+/master/fpdfsdk
16. core/fpdfapi/parser/cpdf_document.cpp - pdfium - Git at Google, accessed November 6, 2025, https://pdfium.googlesource.com/pdfium/+/refs/heads/main/core/fpdfapi/parser/cpdf_document.cpp
17. core/fpdfapi/parser/cpdf_dictionary.h - pdfium - Git at Google, accessed November 6, 2025, https://pdfium.googlesource.com/pdfium/+/refs/heads/main/core/fpdfapi/parser/cpdf_dictionary.h
18. pdfium.gni - pdfium - Git at Google, accessed November 6, 2025, https://pdfium.googlesource.com/pdfium/+/refs/heads/main/pdfium.gni
19. Diff - a5bd1f122db00bf5316586a8ddf4fbacc44c7d80^1..a5bd1f122db00bf5316586a8ddf4fbacc44c7d80 - platform/external/pdfium - Git at Google - Android GoogleSource, accessed November 6, 2025, https://android.googlesource.com/platform/external/pdfium/+/a5bd1f122db00bf5316586a8ddf4fbacc44c7d80%5E1..a5bd1f122db00bf5316586a8ddf4fbacc44c7d80/
20. third_party/freetype/README.pdfium, accessed November 6, 2025, https://pdfium.googlesource.com/pdfium/+/refs/heads/main/third_party/freetype/README.pdfium
21. fxjs - pdfium - Git at Google, accessed November 6, 2025, https://pdfium.googlesource.com/pdfium/+/refs/heads/chromium/5812/fxjs
22. PDFium, accessed November 6, 2025, https://pdfium.googlesource.com/pdfium/+/master/README.md
23. xfa - pdfium - Git at Google, accessed November 6, 2025, https://pdfium.googlesource.com/pdfium/+/master/xfa
24. Getting Started with PDFium, accessed November 6, 2025, https://pdfium.googlesource.com/pdfium/+/HEAD/docs/getting-started.md
25. fpdfsdk/fpdfview.cpp - pdfium - Git at Google, accessed November 6, 2025, https://pdfium.googlesource.com/pdfium/+/refs/heads/chromium/3237/fpdfsdk/fpdfview.cpp
26. LICENSE - pdfium - Git at Google, accessed November 6, 2025, https://pdfium.googlesource.com/pdfium/+/main/LICENSE
27. pypdfium2 - PyPI, accessed November 6, 2025, https://pypi.org/project/pypdfium2/
28. PDF rendering engine performance and fidelity comparison - Hyland Connect, accessed November 6, 2025, https://connect.hyland.com/t5/alfresco-blog/pdf-rendering-engine-performance-and-fidelity-comparison/ba-p/125428
29. PDFium in a commercial closed-source software. - Google Groups, accessed November 6, 2025, https://groups.google.com/g/pdfium/c/BkbitJ58PRM
30. Simple pricing for everyone - Pdfium.Net SDK, accessed November 6, 2025, https://pdfium.patagames.com/Purchase/
31. One time pay, yearly fee and future upgrades - Pdfium.Net SDK - Patagames.com, accessed November 6, 2025, https://pdfium.patagames.com/help/html/Licensing_Renewal.htm
32. GN is a meta-build system that generates build files for Ninja. - gn Git repositories - Git at Google, accessed November 6, 2025, https://gn.googlesource.com/gn/
33. PDFium - Google Git, accessed November 6, 2025, https://pdfium.googlesource.com/pdfium/+/401d4f235114d7857c9c284a70cbb53a3e49bca1/README.md
34. How to Build PDFium.dll with Gn and Ninja? (Preferably in one pdfium.dll) - Stack Overflow, accessed November 6, 2025, https://stackoverflow.com/questions/75723098/how-to-build-pdfium-dll-with-gn-and-ninja-preferably-in-one-pdfium-dll
35. What are the correct options to compile PDFium for Android? - Stack Overflow, accessed November 6, 2025, https://stackoverflow.com/questions/56548558/what-are-the-correct-options-to-compile-pdfium-for-android
36. Git at Google - PDFium, accessed November 6, 2025, https://pdfium.googlesource.com/pdfium.git
37. pdf/pdfium/pdfium_engine.h - chromium/src - Git at Google, accessed November 6, 2025, https://chromium.googlesource.com/chromium/src/+/lkgr/pdf/pdfium/pdfium_engine.h
38. pdfium uses private freetype API (pstables.h) [42271702] - Chromium - Monorail, accessed November 6, 2025, https://bugs.chromium.org/p/pdfium/issues/detail?id=733
39. Why does PDFium bundle Freetype instead of using the system library? - Google Groups, accessed November 6, 2025, https://groups.google.com/g/pdfium/c/ggQqfFU3Pcw
40. c++ - Creating a dll in pdfium - Stack Overflow, accessed November 6, 2025, https://stackoverflow.com/questions/30236148/creating-a-dll-in-pdfium
41. pypdfium2-team/pypdfium2: Python bindings to PDFium, reasonably cross-platform. - GitHub, accessed November 6, 2025, https://github.com/pypdfium2-team/pypdfium2
42. lifetime problems with self-referential struct · Issue #44 · ajrcarey/pdfium-render - GitHub, accessed November 6, 2025, https://github.com/ajrcarey/pdfium-render/issues/44
43. newinnovations/PDFium-rs: Modern Rust interface to PDFium, the PDF library from Google - GitHub, accessed November 6, 2025, https://github.com/newinnovations/pdfium-rs
44. public - pdfium - Git at Google, accessed November 6, 2025, https://pdfium.googlesource.com/pdfium/+/master/public/
45. public/fpdfview.h - pdfium - Git at Google, accessed November 6, 2025, https://pdfium.googlesource.com/pdfium/+/refs/heads/chromium/4016/public/fpdfview.h
46. Pdfium.Net SDK: The C# PDF Library, accessed November 6, 2025, https://pdfium.patagames.com/
47. pdfium package - github.com/pure-project/go-pdfium - Go Packages, accessed November 6, 2025, https://pkg.go.dev/github.com/pure-project/go-pdfium
48. klippa-app/go-pdfium: Easy to use PDF library using Go and PDFium - GitHub, accessed November 6, 2025, https://github.com/klippa-app/go-pdfium
49. bblanchon/pdfium-binaries: Binary distribution of PDFium - GitHub, accessed November 6, 2025, https://github.com/bblanchon/pdfium-binaries
50. Public pdfium API to assert contents of PDF files? - Google Groups, accessed November 6, 2025, https://groups.google.com/g/pdfium/c/LvYRAUprnE8/m/IXuOj6FEFwAJ
51. Get PDF images in an array using PDFIUM to edit them - Stack Overflow, accessed November 6, 2025, https://stackoverflow.com/questions/72224050/get-pdf-images-in-an-array-using-pdfium-to-edit-them
52. pdfium package - github.com/klippa-app/go-pdfium - Go Packages, accessed November 6, 2025, https://pkg.go.dev/github.com/klippa-app/go-pdfium
53. Pdfium.FPDF_LoadCustomDocument Method, accessed November 6, 2025, https://pdfium.patagames.com/help/html/M_Patagames_Pdf_Pdfium_FPDF_LoadCustomDocument.htm
54. Issue 669 in pdfium: Memory leak when rendering pages. - Google Groups, accessed November 6, 2025, https://groups.google.com/g/pdfium-bugs/c/KO4Id_s4w-c/m/wqE9u_EuDQAJ
55. Memory Leak in PDFDocument.Load when Pdfium.FPDF_LoadCustomDocument returns, accessed November 6, 2025, https://forum.patagames.com/posts/t805-Memory-Leak-in-PDFDocument-Load-when-Pdfium-FPDF-LoadCustomDocument-returns-an-IntPtr-Zero
56. ajrcarey/pdfium-render: A high-level idiomatic Rust wrapper around Pdfium, the C++ PDF library used by the Google Chromium project. - GitHub, accessed November 6, 2025, https://github.com/ajrcarey/pdfium-render
57. Pdfium.FPDF_RenderPage Method, accessed November 6, 2025, https://pdfium.patagames.com/help/html/M_Patagames_Pdf_Pdfium_FPDF_RenderPage.htm
58. Does anyone have an experience with PDFium to render/view PDFs? : r/androiddev - Reddit, accessed November 6, 2025, https://www.reddit.com/r/androiddev/comments/40v5w0/does_anyone_have_an_experience_with_pdfium_to/
59. Jaewoook/pdfium.js: A PDFium wrapper library for browser-side JavaScript - GitHub, accessed November 6, 2025, https://github.com/Jaewoook/pdfium.js/
60. pypdfium2 · PyPI, accessed November 6, 2025, https://pypi.org/project/pypdfium2/3.5.0/
61. Cannot load JPG image Pdfium - Stack Overflow, accessed November 6, 2025, https://stackoverflow.com/questions/71024937/cannot-load-jpg-image-pdfium
62. public/fpdf_dataavail.h - pdfium - Git at Google, accessed November 6, 2025, https://pdfium.googlesource.com/pdfium/+/main/public/fpdf_dataavail.h
63. public/fpdf_sysfontinfo.h - pdfium - Git at Google, accessed November 6, 2025, https://pdfium.googlesource.com/pdfium/+/refs/heads/main/public/fpdf_sysfontinfo.h
64. docs/getting-started.md - pdfium - Git at Google, accessed November 6, 2025, https://pdfium.googlesource.com/pdfium/+show/HEAD/docs/getting-started.md
65. How to load the custom font in pdfium.wasm · Issue #163 - GitHub, accessed November 6, 2025, https://github.com/bblanchon/pdfium-binaries/issues/163
66. core/fpdfapi/parser/cpdf_parser.cpp - pdfium - Git at Google, accessed November 6, 2025, https://pdfium.googlesource.com/pdfium/+/master/core/fpdfapi/parser/cpdf_parser.cpp
67. core/fpdfapi/parser/cpdf_object.cpp - platform/external/pdfium - Git at, accessed November 6, 2025, https://android.googlesource.com/platform/external/pdfium/+/1ed3da3f0/core/fpdfapi/parser/cpdf_object.cpp
68. core/fxge/cfx_glyphcache.h - pdfium - Git at Google, accessed November 6, 2025, https://pdfium.googlesource.com/pdfium/+/refs/heads/chromium/6803/core/fxge/cfx_glyphcache.h
69. core/fxcrt/retain_ptr.h - pdfium - Git at Google, accessed November 6, 2025, https://pdfium.googlesource.com/pdfium/+/HEAD/core/fxcrt/retain_ptr.h
70. Security: Pdfium: integer overflows in pattern shading [40089917, accessed November 6, 2025, https://issues.chromium.org/issues/40089917
71. Diff - bc260fd7e338f266d4e41e979c57c100ae9661b6^1..bc260fd7e338f266d4e41e979c57c100ae9661b6 - platform/external/pdfium - Git at Google - Android GoogleSource, accessed November 6, 2025, https://android.googlesource.com/platform/external/pdfium/+/bc260fd7e338f266d4e41e979c57c100ae9661b6%5E1..bc260fd7e338f266d4e41e979c57c100ae9661b6/
72. pdfium - Confused about ownership of font objects - Google Groups, accessed November 6, 2025, https://groups.google.com/g/pdfium/c/Ur0XHQeMnAo
73. Render PDF Page to Bitmap using Pdfium - Stack Overflow, accessed November 6, 2025, https://stackoverflow.com/questions/28448474/render-pdf-page-to-bitmap-using-pdfium
74. How to render the PDF page as EMF or meta file in PDFium - Stack Overflow, accessed November 6, 2025, https://stackoverflow.com/questions/49153715/how-to-render-the-pdf-page-as-emf-or-meta-file-in-pdfium
75. core/fpdfapi/page/cpdf_page.h - pdfium - Git at Google, accessed November 6, 2025, https://pdfium.googlesource.com/pdfium/+/refs/heads/main/core/fpdfapi/page/cpdf_page.h
76. accessed January 1, 1970, https://pdfium.googlesource.com/pdfium/+/main/core/fxge/cfx_renderdevice.h
77. core/fpdfapi/render/cpdf_rendercontext.cpp - pdfium - Git at Google, accessed November 6, 2025, https://pdfium.googlesource.com/pdfium/+/HEAD/core/fpdfapi/render/cpdf_rendercontext.cpp
78. core/fpdfapi/render/cpdf_progressiverenderer.h - platform/external/pdfium - Git at Google, accessed November 6, 2025, https://android.googlesource.com/platform/external/pdfium/+/1ed3da3f0/core/fpdfapi/render/cpdf_progressiverenderer.h
79. fpdfsdk/src/fpdfview.cpp - pdfium - Git at Google, accessed November 6, 2025, https://pdfium.googlesource.com/pdfium/+/3522876d5291922ddc62bf1b70d02743b0850673/fpdfsdk/src/fpdfview.cpp
80. Diff - e749a90be03a6f39751ce0825d9f9a3969aabbed^2..e749a90be03a6f39751ce0825d9f9a3969aabbed - platform/external/pdfium - Git at Google - Android GoogleSource, accessed November 6, 2025, https://android.googlesource.com/platform/external/pdfium/+/e749a90be03a6f39751ce0825d9f9a3969aabbed%5E2..e749a90be03a6f39751ce0825d9f9a3969aabbed/
81. core/fxge/fx_font.h - pdfium - Git at Google, accessed November 6, 2025, https://pdfium.googlesource.com/pdfium/+/163817/core/fxge/fx_font.h
82. public/fpdf_text.h - pdfium - Git at Google, accessed November 6, 2025, https://pdfium.googlesource.com/pdfium/+/main/public/fpdf_text.h
83. FPDFTextObj_GetText returns glyph ids instead of text - Google Groups, accessed November 6, 2025, https://groups.google.com/g/pdfium/c/tDoOI6srATQ
84. Security: PDFium Use-After-Free in v8::internal::ArrayBufferExtension::Mark [40057625], accessed November 6, 2025, https://issues.chromium.org/40057625
85. Pdfium Methods, accessed November 6, 2025, https://pdfium.patagames.com/help/html/Methods_T_Patagames_Pdf_Pdfium.htm
86. fpdfsdk/include/jsapi/fxjs_v8.h - pdfium - Git at Google, accessed November 6, 2025, https://pdfium.googlesource.com/pdfium/+/chromium/2694/fpdfsdk/include/jsapi/fxjs_v8.h
87. fxjs/cfxjs_engine.h - pdfium.git - Git at Google, accessed November 6, 2025, https://pdfium.googlesource.com/pdfium.git/+/refs/heads/chromium/7404/fxjs/cfxjs_engine.h
88. fxjs/xfa/cfxjse_engine.cpp - pdfium - Git at Google, accessed November 6, 2025, https://pdfium.googlesource.com/pdfium/+/refs/heads/chromium/4642/fxjs/xfa/cfxjse_engine.cpp
89. Wrapping a C++ Object to a v8 Object in a Node Addon - Stack Overflow, accessed November 6, 2025, https://stackoverflow.com/questions/16329491/wrapping-a-c-object-to-a-v8-object-in-a-node-addon
90. JavaScript-based PDF Viewers, Cross Site Scripting, and PDF files | Blog un po’ nerd, accessed November 6, 2025, https://gubello.me/blog/pdf-viewers-xss-and-pdf-files/
91. samples/simple_with_v8.cc - pdfium - Git at Google, accessed November 6, 2025, https://pdfium.googlesource.com/pdfium/+/master/samples/simple_with_v8.cc
92. Getting Started with PDFium, accessed November 6, 2025, https://pdfium.googlesource.com/pdfium.git/+/abefb79577b32d291d14d7e/docs/getting-started.md
93. Get access acroforms - Pdfium.Net SDK, accessed November 6, 2025, https://pdfium.patagames.com/help/html/WorkingSDK_AcroForms.htm
94. xfa - pdfium - Git at Google, accessed November 6, 2025, https://pdfium.googlesource.com/pdfium/+/xfa
95. public/fpdfview.h - pdfium - Git at Google, accessed November 6, 2025, https://pdfium.googlesource.com/pdfium/+/e8c1d4144/public/fpdfview.h
96. public/fpdfview.h - pdfium - Git at Google, accessed November 6, 2025, https://pdfium.googlesource.com/pdfium/+/old_master_before_xfa/public/fpdfview.h
97. fpdfsdk/fpdf_editpage.cpp - pdfium - Git at Google, accessed November 6, 2025, https://pdfium.googlesource.com/pdfium/+/refs/heads/main/fpdfsdk/fpdf_editpage.cpp