Pro 版本

优化器

速览

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% 质量为目标。

为何采用这种设计

优化器进行分析，而非改写。analyze() 估算潜在的节省量并返回一个 OptimizationResult，不会改动输入。这使得这一遍处理保持非破坏性，并让你自行决定是否通过 Writer 应用它。级别这一抽象把权衡集中在一处：lossless 从 deduplicateStreams() 返回 false，因此输出可保持字节一致，而 balanced 与 aggressive 会以更低的质量目标重新压缩图像流。可实现的节省取决于一份文档已经如何编码其流与图像，因此本模块基于实际存在的对象报告一个估算值，而非一个固定的招牌数字。设计背景：流与过滤器。

行为契约

analyze($pdfData) 返回一个 OptimizationResult；它不会改动输入。
lossless 级别跳过流去重，以使输出能保持字节稳定；balanced 与 aggressive 启用去重。
图像质量目标对于 lossless、balanced 与 aggressive 分别为 100%、75% 与 50%。
预估优化后大小绝不会低于零，也绝不会超过原始大小。
withLevel($level) 返回一个处于所请求级别的新优化器；实例不会被改动。

代码示例 —— 快速上手

以下反映已记录的公共 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 级别有意只带来很小的体积缩减，因为它保留质量并跳过去重。
image-count-after 反映的是通过去重移除的图像，而非被丢弃的图像。

性能

分析与输入大小呈线性关系，外加扫描对象与图像结构的成本。级别控制去重与再压缩估算的激进程度。没有公布固定的体积缩减数字；结果完全取决于文档。请用有代表性的文档来度量。

安全说明

将输入视为不可信。分析保持只读，且不会执行内嵌内容。本模块不记录任何文档内容。

一致性

优化作用于 ISO 32000-2 定义的 PDF 对象与图像模型；来源标注了相关条款。撰写时 RAG 语料库不可用，因此本页面不断言任何外部条款标识符，并将一致性陈述限定在由该模块测试验证的行为之内。

Enterprise 边界说明

Enterprise 不改变 Optimizer 的行为。Enterprise 增加的是另行记录的更高层级合规与归档功能；它们对分析优化潜力并非必需。

Core 回退/替代方案

没有 Pro 时，请使用 NextPDF Core 的基础优化；对象去重与可调的图像再压缩分析是 Pro 新增能力。

发布边界

本页面仅记录可从外部观察到的行为以及受支持的公共 API 接口面。内部命名空间路径、辅助类、机制表、runbook 文件名以及工单前缀均不在范围之内。