跳轉到

線性化（快速網頁瀏覽）

線性化 PDF（Linearized PDF），又稱「快速網頁瀏覽」（Fast Web View），是一種特殊的 PDF 組織方式，讓瀏覽器在 PDF 尚未完全下載前就能顯示第一頁。對於超過 10 頁或 1 MB 的文件，線性化可顯著改善使用者的感知等待時間。

啟用線性化

use NextPDF\Writer\WriterOptions;
use NextPDF\Writer\LinearizationMode;

$pdfBytes = $document->finalize(
    writerOptions: WriterOptions::create(
        linearization: LinearizationMode::Enabled,
    ),
);

線性化的物件重排

線性化 PDF 將物件依照最佳的存取順序重排：

線性化 PDF 物件順序：
1. 線性化字典（Linearization Dictionary）— 包含文件總體資訊
2. 第一頁所需的所有物件（頁面字典、字型、影像）
3. 第一頁的交叉參考資料（First Page XRef）
4. 文件目錄（Catalog）與 Info 字典
5. 其餘頁面的物件（按頁序排列）
6. 完整交叉參考串流（放在末尾，供本地完整解析使用）

Hint Tables

線性化 PDF 包含提示表（Hint Tables），讓 HTTP 伺服器根據使用者導航到特定頁面時，精確發起 HTTP Range Request 只取所需位元組：

Head Hint Table（在文件前端）：
- Page Offset Hint Table：各頁面在檔案中的位元組偏移與長度
- Shared Object Hint Table：多頁共享的資源（字型、色彩空間）

Overflow Hint Table（在文件末端）：
- 第一頁後的頁面偏移修正值

伺服器配置建議

# Nginx：啟用 Range Request 支援
server {
    location ~ \.pdf$ {
        add_header Accept-Ranges bytes;
        # 可選：禁用 sendfile 以允許動態 Range 計算
    }
}

線性化後的修改

對線性化 PDF 的任何修改（增量更新）會使線性化失效。若需修改線性化 PDF：

// 策略 1：修改後重新線性化
$modifiedPdf = modifyPdf($linearizedPdf);
$relinearizedPdf = $linearizer->linearize($modifiedPdf);

// 策略 2：僅對最終版本進行線性化（推薦）
// 在 document->finalize() 時啟用，確保最終輸出是線性化的

線性化驗證

use NextPDF\Writer\LinearizationChecker;

$checker = LinearizationChecker::create();
$result = $checker->check(pdf: $pdfBytes);

echo "Linearized: " . ($result->isLinearized() ? 'Yes' : 'No') . PHP_EOL;
echo "First Page Size: " . $result->getFirstPageBytes() . " bytes" . PHP_EOL;
echo "Hint Table Valid: " . ($result->hasValidHintTable() ? 'Yes' : 'No') . PHP_EOL;

參見