Pro 版本

Optimizer

速覽

Optimizer 會分析一份 PDF 的重複物件與影像重新壓縮潛力，接著回報預估的大小縮減量。三個層級會在輸出保真度與檔案大小之間做取捨。

供應與授權

此功能隨附於 NextPDF Pro（nextpdf/pro），並以 Pro 層級的授權信封啟用。未持有該授權的部署不會載入此功能的類別。比較各版本並取得授權。

沒有獨立的逐功能授權旗標。最佳化層級（lossless、balanced、aggressive）是一個執行階段參數，而非授權開關。

安裝

composer require nextpdf/pro:^3

程式碼位於 NextPDF\Pro\Optimizer 命名空間下。

概念總覽

PdfOptimizer 會協調一個物件去重器與一個影像重新壓縮器。給定原始 PDF 位元組，它會找出重複的物件群組（當層級允許時）、分析影像，並以該層級的目標品質估計每張影像的壓縮量。它會將這些發現彙整為一個 OptimizationResult，回報原始大小、預估的最佳化後大小、移除的物件數，以及前後的影像數量。

OptimizationLevel 定義此取捨：lossless 會保留影像品質並略過去重以取得位元組穩定的輸出；balanced 會去重並以 75% 的影像品質為目標；aggressive 會去重、降採樣，並以 50% 的品質為目標。

為何如此設計

Optimizer 是分析而非改寫。analyze() 會估計潛在的節省量並回傳一個 OptimizationResult，而不會變動輸入。這讓此流程維持非破壞性，並讓你決定是否透過 Writer 套用它。層級這層抽象把取捨集中於一處：lossless 會讓 deduplicateStreams() 回傳 false，使輸出能維持位元組相同，而 balanced 與 aggressive 會以較低的品質目標重新壓縮影像串流。可達成的節省量取決於一份文件既有的串流與影像編碼方式，因此此模組會依據實際存在的物件回報一個估計值，而非固定的宣傳數字。設計背景：串流與篩選器。

行為合約

analyze($pdfData) 會回傳一個 OptimizationResult；它不會變動輸入。
lossless 層級會略過串流去重，使輸出可維持位元組穩定；balanced 與 aggressive 會啟用去重。
lossless、balanced 與 aggressive 的影像品質目標分別為 100、75 與 50%。
預估的最佳化後大小絕不會低於零，也絕不會超過原始大小。
withLevel($level) 會回傳一個位於所請求層級的新 optimizer；實例不會被變動。

程式碼範例——快速上手

以下反映已記載的公開 API。此模組的儲存庫並未隨附可執行範例。

use NextPDF\Pro\Optimizer\PdfOptimizer;

$result = (new PdfOptimizer())->analyze($pdfBytes);

程式碼範例——正式環境

use NextPDF\Pro\Optimizer\PdfOptimizer;
use NextPDF\Pro\Optimizer\OptimizationLevel;

$optimizer = new PdfOptimizer(OptimizationLevel::Aggressive);
$result = $optimizer->analyze($pdfBytes);

$savings = $result->originalSize > 0
    ? (1 - $result->optimizedSize / $result->originalSize) * 100
    : 0.0;

邊界案例與陷阱

analyze() 估計的是潛力；請搭配 Writer 模組以產生最佳化後的文件。
lossless 層級刻意只帶來很少的大小縮減，因為它會保留品質並略過去重。
「最佳化後影像數量」反映的是透過去重移除的影像，而非被捨棄的影像。

效能

分析與輸入大小成線性關係，再加上掃描物件與影像結構的成本。層級控制去重與重新壓縮估計的積極程度。沒有公布固定的大小縮減數字；結果完全取決於文件。請以具代表性的文件量測。

安全注意事項

請將輸入視為不受信任。分析維持唯讀，且不執行嵌入內容。此模組不記錄任何文件內容。

一致性

最佳化作業在 ISO 32000-2 所定義的 PDF 物件與影像模型上運作；來源會標註相關條款。撰寫時 RAG 語料庫無法使用，因此本頁不主張任何外部條款識別碼，並將一致性陳述限定於該模組測試所驗證的行為。

Enterprise 邊界註記

Enterprise 不會改變 Optimizer 的行為。Enterprise 加入的是另行記載的更高階合規與封存功能；分析最佳化潛力並不需要它們。

Core 回退/替代方案

若無 Pro，請使用 NextPDF Core 的基礎最佳化；物件去重與可調的影像重新壓縮分析是 Pro 新增的功能。

發布邊界

本頁僅記載外部可觀察的行為，以及所支援的公開 API 介面。內部命名空間路徑、輔助類別、機制對照表、runbook 檔名與工單前綴皆不在範圍內。