NextPDF FAQ

概览

本页回答你在评估 NextPDF 或开启一个新项目时最先冒出的问题。每个回答都简短，并链接到完整讲解它的页面。NextPDF 是一个 PHP 8.4 引擎，用于生成和检查 Portable Document Format（PDF）2.0 文档，即 ISO 32000-2 所定义的文件格式。

如果你是全新上手，先读开始上手，再回到这里看具体细节。

开始上手

我需要哪个版本：Core、Pro 还是 Enterprise？

从 Core 开始。开源核心（nextpdf/core）在 Apache-2.0 许可下并免费地生成 PDF 输出、把受支持的 HTML 渲染成 PDF，并检查 PDF。Core 已经产生 PDF 高级电子签名（PAdES）B-B 和 B-T 基线级别的 CMS SignedData 签名。当你需要高级的生成和文档操作、电子发票输出（Factur-X / ZUGFeRD），或诸如远程、云 KMS 和顺序签名等高级签名工作流时，选择 Pro。当你需要 PDF/A 归档创建工作流、带有文档安全存储（Document Security Store）和文档时间戳的 PAdES 长期级别（B-LT / B-LTA）、通过硬件安全模块（HSM）进行硬件支撑的签名，或合格电子签名时，选择 Enterprise。Pro 和 Enterprise 是 NextPDF Premium 付费产品线的两个授权版本；参见选择你的路径。

它真的是 Apache-2.0 吗？

是的，核心是。nextpdf/core 声明 "license": "Apache-2.0"，并在其 LICENSE 文件里随附完整的 Apache License 2.0 文本。你可以使用、修改、再分发并商业化核心，前提是遵守署名和 NOTICE 要求（Apache-2.0 §4）。NextPDF Pro 和 NextPDF Enterprise 是专有的商业版本，不在该许可的覆盖之内。NextPDF 的名称和标志是商标，与代码许可相互独立。参见产品许可。

最低 PHP 版本是多少？

PHP 8.4。包约束是 >=8.4 <9.0，因此 Composer 拒绝在 PHP 8.3 或更低、或在 PHP 9 上安装。NextPDF 面向一个现代运行时，并直接使用它的语言特性。参见安装 NextPDF。

它需要外部二进制或无头浏览器吗？

不，核心引擎不需要。原生引擎用 PHP 和标准 PHP 扩展实现，没有外部 PDF 二进制，也没有强制的无头浏览器：流式 API 和内置的 writeHtml() HTML 流水线在进程内运行，没有浏览器也没有网络调用。一个 Chrome 或 Chromium 二进制是可选的，只在 Artisan 渲染器（writeHtmlChrome()）需要，你把它作为 nextpdf/artisan 单独安装。Cloudflare 和 Gotenberg 桥也是可选的，并会调用出一个服务。参见选择你的路径。

它需要哪些 PHP 扩展？

核心的 composer.json 要求标准扩展 ext-mbstring、 ext-zlib、ext-intl、ext-gd、ext-curl 和 ext-openssl，它们是常见可用的 PHP 扩展；请确保它们在你的运行时里已安装并启用。ext-curl 支撑可选的网络往返 —— RFC 3161 时间戳和远程资产抓取 —— 所以离线的原生生成不会用到它，但 Composer 仍把它列为硬性要求。各集成会在启动时检查它们所需的那些，并在缺失任何一个时以一条清晰的消息停止。完整列表存放在包的 composer.json 里；参见安装 NextPDF。

我如何生成我的第一个 PDF？

安装核心，然后用流式 API 构建一个文档：

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;

$document = Document::createStandalone();
$document->addPage();
$document->setFont('helvetica', 'B', 24);
$document->cell(0, 15, 'Hello, NextPDF!', newLine: true);
$document->save(__DIR__ . '/first.pdf');

在你的第一个 PDF 里一步步走完它。

版本与许可

Core 有任何功能限制或水印吗？

没有。Core 是面向 Core 功能集的开源引擎，没有水印也没有提示弹窗。对于 Core 功能集 —— 生成、检查、加密、PDF/A 和 PDF/UA 输出原语，以及软件密钥的 B-B/B-T 签名（不含 Premium 的长期验证和密钥托管工作流）—— Core 是完整的。评估水印只适用于Premium 评估授权，在那里你在一个可移除的水印背后测试完整的 Pro 和 Enterprise 功能集；一份付费许可会移除它，无需更改应用代码。参见许可与激活。

升级到 Pro 或 Enterprise 需要改代码吗？

大多不需要。当你安装 nextpdf/premium 时，框架集成和服务器会自动检测到它并暴露额外能力。多数应用保持同样的高层集成点；某些 Premium 工作流可能需要配置或特定功能的调用。你每次部署激活一次已签名的许可信封。参见许可与激活。

我能在闭源商业产品里使用核心吗？

可以。Apache License 2.0 没有非商业限制。你可以在闭源、付费或内部商业产品里使用核心，前提是你履行署名和 NOTICE 义务，并且不把代码许可当作使用 NextPDF 品牌的许可。参见产品许可和商标与品牌使用。

能力

它能读取和解析 PDF，还是只能写 PDF？

两者都行，但有个注意点。NextPDF 写 PDF，也读 PDF：Inspect 模块把一个现有文件读入一个结构化的 InspectResult，带有复杂度、字体、图像和风险数据，而且你可以合并和拆分现有文档。Inspect 被标记为实验性，因此它的结果形状可能在次版本之间变化 —— 把它用于诊断和把关，而不是作为一个长期契约。参见 Inspect 模块。

它产生可选中、可搜索的文本吗？

是的。流式 API 和内置的 writeHtml() 流水线都写出真正的文本内容，而非栅格化图像，因此输出可选中、可搜索。Artisan 渲染器的 writeHtmlChrome() 也保持文本可选中。参见你的第一个 PDF。

HTML 和 CSS 渲染如何工作？

核心引擎包含一个纯 PHP 的 HTML 流水线。writeHtml() 用一个受支持的 CSS 子集把一个 HTML 片段直接渲染进页面，没有浏览器也没有网络调用。当某个布局需要完整的浏览器保真度时 —— 例如 flexbox、grid 或 web 字体 —— 安装 Artisan 渲染器并调用 writeHtmlChrome()。在你依赖某个属性之前，先查 CSS 支持矩阵。

字体如何工作？

诸如 Helvetica 这样的内置标准字体别名对于简单的 WinAnsi 文本无需设置即可工作，所以你的第一个文档不需要字体文件。内置的拉丁标准字体适合基础 WinAnsi 文本；Symbol 和 ZapfDingbats 使用它们自己的编码；要渲染其他文种，你需要注册并嵌入一个其字符映射和整形路径支持该文种的字体。参见字体支持矩阵和 Font 模块。

它支持 PDF/A 和无障碍（PDF/UA）吗？

是的，但有一条清晰的边界：支持一个 profile 不等于合规。核心随附合规性判别器和标签原语 —— enableTaggedPdf() 启用用于 PDF/UA 工作流的标签 PDF 结构输出，而 enablePdfA() 在 Core 里选择一个 PDF/A 输出 profile；Premium 版本在其之上添加更高层的归档创作工作流和工具（校验、策略和生产运维）。NextPDF 生成一个 profile 所要求的结构性产物；一个独立的校验器如 veraPDF 来裁定一个给定文件是否真的合规。参见合规性和 Accessibility 模块。

我如何给 PDF 签名？

核心可以产生 Cryptographic Message Syntax（CMS）SignedData 签名，并可以施加 RFC 3161 时间戳（B-T 级别），通过配置的签名提供方使用受支持的软件密钥算法。你的代码依赖 SignerInterface 契约，因此同样的调用在各版本间都能工作。PAdES B-LT 和 B-LTA 长期级别、HSM 和 PKCS#11 密钥托管，以及合格签名都是 Enterprise 能力；云和 KMS 支撑的签名工作流则由 Pro 提供。Core 产生 B-B 和 B-T 基线结构。参见 Signing 模块。

生产

它对 worker 安全、对线程安全吗？

一个 Document 是一次性的：一旦你写完一个，就为下一个文档创建一个全新实例，而不是复用它。这让它天然契合 PHP-FPM、队列 worker 和框架所用的按请求、按作业模型 —— 每个工作单元构建它自己的文档。当你解析或组合不受信任的输入时，在一个受约束的 worker 里运行那项工作，并把资源守护（maxFiles、maxTotalBytes、maxBytes）收紧。参见 Document 模块和引擎威胁模型。

输出是确定性的吗？

它在结构上是确定的，但默认并非逐字节相同。对同一输入的两次运行产生结构相等的 PDF，但每个都携带一个全新的 trailer 和文档 /ID，因此字节不同。签名和时间戳按设计添加进一步的每次运行差异。围绕结构相等来规划比较，或归一化易变字段，而不是期待跨运行的字节相同。

我如何部署它？

提交 composer.lock，让每个部署的 worker 解析到相同的引擎版本，然后像部署任何 PHP 库那样部署它 —— 原生生成不需要守护进程、浏览器或网络；时间戳（B-T）、远程资产，或可选的浏览器桥需要配置好的网络访问。如果非 PHP 服务需要这个引擎，运行 NextPDF Server，它通过 Model Context Protocol （MCP）、REST 和 gRPC 暴露它。对于 Premium，把已签名的许可信封放到部署加载它的位置，并运行一次性的激活步骤；缓存的许可状态意味着正常处理不需要许可服务，因此气隙部署也受支持。参见安装 NextPDF 和许可与激活。

出问题时我把失败带到哪里？

NextPDF 按 PHP 异常类报告错误，而不是按字符串错误码，并且上下文感知的异常携带结构化诊断字段。排查知识库把常见的签名、PDF/A、PDF/UA、字体、标签和加密失败映射到它们的成因和解决办法。