集成决策指南

Spec Spec: ISO/IEC/IEEE 26514:2022, §3.x162 ISO/IEC/IEEE 26514:2022 §3.x162 Spec Spec: ISO 24495-1:2023, §5 ISO 24495-1:2023 §5 Evidence ¶ Editorial Evidence: Editorial

一览

NextPDF 生态系统由一个精简的核心引擎和一组职责明确的包构成——框架桥接、两个 HTML 渲染器、一个边缘渲染器，以及一个执行服务器。本页会根据各包实际包含的能力，把真实使用情境对应到合适的包。选择权仍由你基于证据来行使，而不是由本文档替你暗示。

为何这很重要

选错集成方式的代价很高，而且不会立刻显现。如果进程内引擎本可以顺利渲染某份文件，你却选择了远程浏览器渲染器，就等于给每一份 PDF 增加一次网络往返和一个可用性依赖。如果某份文件确实需要完整浏览器布局引擎，你却选择了进程内引擎，得到的文件就会出现细微错误。你采用的包会影响延迟、故障模式和运维面，因此这项决定值得明确摊开来讨论。

简短版

• 从核心引擎开始。 其他所有包都是附加项。只要进程内引擎能正确渲染你的文件，就完全不需要任何渲染器包。
• 框架桥接跟随你的框架，而不是你的文件。 Laravel、Symfony 与 CodeIgniter 集成的存在，是为了让你获得 facade 或 factory、PDF 响应、队列化生成与自动发现；它们不会改变引擎能够渲染的内容。
• 只有当 CSS 保真度需要浏览器时才使用渲染器。 Artisan（本地 Chrome）与 Cloudflare（边缘浏览器）正是为此而存在；Gotenberg 则用于引入 Office 文件。
• 当调用方是服务或 AI 代理，而不是 PHP 调用时，使用 Connect。 它通过 MCP、REST 与 gRPC 对外公开引擎，并为危险操作设置人工批准关卡。

NextPDF 的处理方式

这个生态系统刻意采用分层设计，让每个包只负责一件事。核心引擎在进程内渲染 PDF。框架桥接把该引擎适配为某个框架的惯用写法。当进程内引擎不是合适工具时，渲染器包会把 HTML 或 Office 布局交给外部引擎处理。Connect 把引擎变成一项网络服务。这些包的职责彼此不重叠，这正是让决策可控的关键。你不是在相互竞争的工具之间做选择，而是在组合彼此互补的工具。

这项决定最好围绕使用情境来做。下表把每个情境对应到合适的包，并说明你需要接受的取舍。

使用情境	合适的包	它实际提供什么	你接受的取舍
Laravel 应用程序中的 PDF	nextpdf/laravel	自动发现的 service provider、Pdf facade、PdfResponse（内联/下载/流式，含 OWASP 标头）、一个带有 tries/timeout/backoff 的队列化 GeneratePdfJob，以及 Octane 安全的锁定注册表	一项 Laravel 12 依赖；引擎能力保持不变
Symfony 应用程序中的 PDF	nextpdf/symfony	自动注册的 bundle、可注入的 PdfFactory、PdfResponse，以及一个用于异步生成的可选 Messenger handler	一项 Symfony 7.2 bundle 依赖；能力保持不变
CodeIgniter 4 应用程序中的 PDF	nextpdf/codeigniter	service('pdf') / pdf() 辅助函数、一个包装可丢弃的 Document 的 Pdf library、一个 PdfResponse，以及一个可选的队列化 job	一项 CodeIgniter 4.6 依赖；能力保持不变
文件需要完整浏览器 CSS（flex/grid/Web 字体），且希望在接近进程内的环境中处理	nextpdf/artisan	通过 CDP 驱动无头 Chrome，先渲染，再以 Form XObject 汇入，保持文字可选取；并提供一个浏览器池	主机上需要一个 Chrome 运行环境及其 memory/process 成本
将 Office 文件（.docx、.xlsx）转成 PDF	nextpdf/gotenberg	通往 Gotenberg 微服务的 PSR-18 桥接，采用 SSRF 加固且 IP 固定的传输	一个外部 Gotenberg 服务和一项网络依赖
在边缘执行 HTML→PDF/不需要本地 Chrome	nextpdf/cloudflare	通过固定传输使用 Cloudflare Browser Rendering，并可选用本地 Chrome 回退	一个 Cloudflare 账号和一项网络依赖；回退需要 Artisan
引擎由服务或 AI 代理调用	nextpdf/server（Connect）	通过 MCP（stdio）、REST（OpenAPI 3.1）与 gRPC 对外公开单一引擎；软依赖式工具探索；针对高风险工具的人工确认关卡	运维一个服务面；遵守确定性执行纪律

Human-factors note: Human-factors note

这是两项相互独立的决定，但人们常把它们混为一谈。所谓 框架桥接 由你已经使用的框架决定——它不会扩展或限制引擎可渲染的内容。所谓 渲染器 则由文件决定。关键问题在于：进程内 CSS 引擎是否已经足够，或者这份文件是否确实需要浏览器布局引擎。你可能需要框架桥接而不需要渲染器、需要渲染器而不需要桥接、两者都需要， 或两者都不需要。把它们当成同一个问题来决定，是最常见的集成错误，这也是本页将两者分开处理的原因。

证据怎么说

本页属于 编辑性质——它是一项路由决策——但这项路由以各包的 manifest 与主要类实际包含的内容为依据。

Evidence ¶ Editorial Evidence: Editorial

这些桥接都是真实存在且彼此并行的。每个桥接都在其 composer.json 中声明框架依赖与自动注册（extra.laravel.providers、extra.symfony.bundles、CodeIgniter 的 Registrar）。每个桥接也都随附一个 PdfResponse、一个可丢弃的文件绑定，以及一个可选的队列化 job。它们没有任何一个会增加渲染能力——它们只是调整同一个引擎。这些渲染器都是真实存在且各不相同的。Artisan 依赖于 chrome-php/chrome，并将 Chrome 生成的 PDF 以 Form XObject 汇入，以保持文字可选取。Gotenberg 与 Cloudflare 都是 PSR-18 HTTP 桥接，采用明确的 SSRF 加固、IP 固定传输。当 Worker 无法连接时，Cloudflare 可回退至 Artisan。Connect 的 composer.json 声明了三种传输，以及一套软依赖模型——工具会随着其包安装而出现，并由一个四级风险模型与一道人工确认关卡管理。

本页为你路由的方式在形式上有 标准支撑： Spec Spec: ISO 24495-1:2023, §5 ISO 24495-1:2023 §5 指出，读者应能快速判断内容是否符合其目的（chunk ），而 Spec Spec: ISO/IEC/IEEE 26514:2022, §3.x222 ISO/IEC/IEEE 26514:2022 §3.x222 要求链接与引用标明其指向的目的地 ——这正是表格直接点名具体包与取舍，而不是含糊地提到「某个集成」的原因。

实用示例

这项决定是一连串诚实的问题，而不是功能比较。以下内容澄清了常见情况。

1. Does the in-process engine render the document correctly?
   YES → you need NO renderer package. Stop here for rendering.
   NO  → continue.

2. Is the source an Office file (.docx/.xlsx)?
   YES → nextpdf/gotenberg (external Gotenberg service).
   NO  → continue (it is HTML/CSS fidelity you need).

3. Can you run a local Chrome on the host?
   YES → nextpdf/artisan (local CDP renderer).
   NO  → nextpdf/cloudflare (edge; optional Artisan fallback).

Independently of 1–3, choose how the engine is CALLED:
   In a PHP web app?        → the matching framework bridge.
   By a service / AI agent? → nextpdf/server (Connect).
   Neither?                 → use the core engine directly.

这个结构本身就是重点：渲染与调用是两个分开的维度。把它们合并回答，正是团队最终采用一个实际用不上的远程渲染器，或采用一个无法解决保真度问题的桥接的原因。

常见的误解

最主要的误解是 「我需要一个渲染器包才能生成 PDF。」 你并不需要。核心引擎会在进程内生成 PDF。渲染器包存在的唯一理由，是处理需要浏览器级布局引擎，或来源为 Office 文件的特定情况。当进程内引擎已经能生成正确文件时，反射式地采用渲染器只会增加一项运行时依赖和一种故障模式，没有任何好处。

另一个相对的误解是 「框架桥接会解锁能力。」 它不会。桥接改变的是你 如何调用 引擎——facade、factory、响应、队列化 job——而不是它能 生成 什么。签名、PDF/A 与结构化发票都属于版本层级与引擎范畴；无论你通过桥接还是直接调用，结果完全相同。

限制与边界

• 本页负责路由；它不做基准测试，也不排名。 它陈述各包提供什么，以及取舍是什么。在它们之间做选择，是你根据自身限制条件做出的决定。
• 各包的能力是在某一时间点，从其 manifest 与主要类读取而来。 请将各包自身文档视为其当前 API 的权威依据。本指南是地图，而非规格。
• 本页不提供、也不暗示任何竞品比较。 唯一主题是 NextPDF 生态系统，以及它各部分如何彼此契合。
• 框架桥接与渲染器是彼此独立的选择。 桥接不会扩展引擎能力；渲染器也不依赖于框架。
• 外部渲染器会增添一项可用性依赖。 Gotenberg 与 Cloudflare 会引入一次网络调用和一项需要运维的服务；这是已接受的取舍，而非隐藏成本。
• 受版本层级门控的能力与集成是正交的。 商业功能由版本层级解锁，而不是由任何桥接或渲染器解锁；参见下方的边界。

Ecosystem packages and tiering — edition availability

Edition	Availability
Core	○ 每个集成包（桥接、Artisan、Gotenberg、Cloudflare、 Connect）都面向 Core 运行，并采用 Apache-2.0 许可。它们调整或公开该引擎；它们并不对功能设门。
Pro	○ 商业能力（PAdES baseline 签名、PDF/A、高级条码）由版本层级解锁，随后即可 通过 任何集成调用，而不是靠切换集成来取得。
Enterprise	○ 结构化发票、验证策略，以及针对高风险工具的 Connect 人工确认关卡，都属于版本层级能力， 同样与集成无关。

相关文件

• HTML 管线——进程内 CSS 引擎覆盖的范围，帮助你判断何时才真正需要浏览器渲染器。
• 何时不该使用 NextPDF——诚实划出那些文件问题的边界：在这些情况下，引擎并不是合适工具。
• PHP 8.4 基础——每个包共享的运行时底线，以及 backport 路径保留的内容。

术语表

• 核心引擎——nextpdf/core，其他每个包都构建在它之上的进程内 PDF 2.0 引擎。
• 框架桥接——一个集成包（Laravel/Symfony/CodeIgniter），在不改变引擎能力的前提下，把引擎适配为某个框架的惯用写法。
• 渲染器包——当进程内引擎不是合适工具时，将 HTML 或 Office 布局交给外部引擎（Artisan/Cloudflare/Gotenberg）处理的包。
• Form XObject——一段可重复使用的 PDF 内容片段；Artisan 会把浏览器渲染的页面汇入为这种片段，使其中的文字保持可选取。
• NextPDF Connect——nextpdf/server，以确定性执行面通过 MCP、REST 与 gRPC 公开引擎的包。
• 软依赖——Connect 的模型：工具会随着可选 NextPDF 包的安装而自动出现，无须变更代码。