性能

TCPDF-Next 的设计目标是高吞吐量的文件生成。本页涵盖内置的优化机制与实务上的性能调优建议。

延迟子引擎初始化

Document 类持有超过 20 个子引擎（Graphics、Typography、Barcode、Forms、Layers 等）的引用，但大多数都是延迟初始化的 — 只在首次访问时才会创建。

一份仅含文字的简单 PDF 永远不会实例化 SVG 解析器、条码引擎或表单字段管理器。这让内存用量与你实际使用的功能成正比。

字体子集化

TCPDF-Next 默认仅嵌入文件中实际使用的字形。FontSubsetter 会分析所有文字内容，在嵌入前从 TrueType/OpenType 字体中剔除未使用的字形。

对于使用少量字符集的文件，字体数据可从数 MB 降至数 KB。

use Yeeefang\TcpdfNext\Core\Document;

// 字体子集化默认开启 — 无需额外配置
$pdf = Document::create()
    ->addPage()
    ->setFont('DejaVuSans', '', 12)
    ->cell(0, 10, '仅嵌入此处使用的字形。');

FlateDecode 压缩

所有内容流皆使用 zlib（FlateDecode）压缩。此功能默认启用，需要 ext-zlib PHP 扩展。压缩通常可将 PDF 文件大小减少 60-80%。

流式输出（PdfWriterChunked）

对于超大型文件，分段写入器会在页面数据定稿后逐步清出，而非将整份 PDF 保留在内存中。这对调用端完全透明 — 相同的 save() 与 output() 方法不受文件大小影响。

use Yeeefang\TcpdfNext\Core\Document;

// 大型文件的流式输出
$pdf = Document::create();
$pdf->addPage()->setFont('Helvetica', '', 10);

for ($i = 0; $i < 5000; $i++) {
    $pdf->cell(0, 5, "Row {$i}: data content here", newLine: true);
}

$pdf->save('large-document.pdf');
// 字体子集化与 FlateDecode 压缩自动执行

交叉引用流

TCPDF-Next 使用交叉引用流（PDF 1.5+）取代传统的 xref 表格。交叉引用流本身也经过压缩，能产生更小的文件 — 尤其是对象数量众多的文件。

线性化（快速 Web 查看）

线性化会重新排列 PDF 对象，让第一页能在整份文件下载完成前就开始显示。对任何通过 HTTP 提供的 PDF 都建议启用：

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->setLinearization(true)
    ->addPage()
    ->cell(0, 10, '浏览器中渐进式渲染')
    ->save('web-optimized.pdf');

Linearizer 会插入提示流，告知查看器如何按需获取各页面。

MAX_PAGES 常量

Document::MAX_PAGES 默认值为 10,000 页。这是一道防护机制，避免生成过程中出现无穷循环。若你的使用场景需要更多页数，可通过继承类来覆盖此常量。

最佳实践

跨页面重复使用字体

设置一次字体后让它在各页面间沿用。除非字体确实需要变更，否则避免在每一页都调用 setFont()：

$pdf = Document::create()
    ->setFont('Helvetica', '', 10);

for ($i = 0; $i < 100; $i++) {
    $pdf->addPage()
        ->cell(0, 5, "Page {$i} content");
}

使用模板（XObjects）处理重复内容

若每页都有相同的页首、页尾或水印，可将其创建为模板并盖印到各页面上。这会将内容存储为单一 PDF 对象并多次引用，而非逐页重复。

维持压缩启用

压缩默认开启。除非需要查看原始 PDF 流以进行调试，否则不要停用它。

大型文件使用流式输出

对于超过数百页的文件，流式输出可让内存用量不随页数增长而保持稳定。

维持字体子集化

字体子集化默认开启。请确保在正式环境中不要停用 — 完整字体嵌入可能会增加数 MB 的文件大小。

缩小事务范围

事务会存储完整的文件快照。保持事务的生命周期尽可能短，以避免内存用量倍增。详见事务。

总览

功能	默认	影响
字体子集化	开启	更小的字体数据（KB vs MB）
FlateDecode 压缩	开启	流大小减少 60-80%
交叉引用流	开启	更小的 xref 数据
延迟初始化	开启	内存用量与功能使用成正比
流式输出	自动	大型文件维持稳定内存用量
线性化	关闭	建议对 Web 传递的 PDF 启用