选择合适的集成方式
选择合适的集成方式
标题为“选择合适的集成方式”的章节本页将使用场景对应到适合处理它的集成方式。每一项建议都只来自软件包的 composer.json 描述及其声明用途，两者都直接读自源代码仓库。当两种集成方式有所重叠时，本页会指出区分两者的关键因素，并把最终决定权交给你。
找到与你情况相符的那一行，然后从那里开始。
从这里开始：你手上有什么？
标题为“从这里开始：你手上有什么？”的章节| 你手上有…… | 使用 | 原因（已验证的用途） |
|---|---|---|
| 一个 Laravel 12 应用程序 | nextpdf/laravel | Laravel 框架集成：service provider、facade、PDF 响应辅助方法。 |
| 一个 Symfony 7 应用程序 | nextpdf/symfony | Symfony bundle：DI 服务与 PDF 响应辅助方法。 |
| 一个 CodeIgniter 4 应用程序 | nextpdf/codeigniter | CodeIgniter 4 服务、library 封装层，以及 PDF 响应辅助方法。 |
| 一个不依赖框架的 PHP 应用程序 | nextpdf/core（直接使用） | 不需要任何框架集成；这套引擎本身就是一个单纯的 library。 |
| 需要浏览器 CSS 引擎的 HTML，而且你能运行 Chrome | nextpdf/artisan | Chrome CDP renderer（渲染器），用于需要浏览器级 CSS 布局的 HTML。 |
| 一份要转换的 Office 文档，例如 DOCX、XLSX 或 ODT | nextpdf/gotenberg | 通过 Gotenberg 微服务进行 Office 转 PDF。 |
| 需要在没有可操作浏览器进程的情况下进行渲染 | nextpdf/cloudflare | 在边缘侧通过 Cloudflare Browser Rendering API 进行 serverless（无服务器）渲染。 |
| 针对某个旧版 PDF library 编写的代码 | nextpdf/compat-legacy | 旧版 PDF library 兼容层；无需改写调用点就能调用 NextPDF。 |
| 卡在 PHP 8.1 / 7.4 上的运行环境 | nextpdf/backport-builder | Rector 降级流水线，会为引擎构建出一份 8.1 / 7.4 的目标版本。 |
| 远程调用方、另一种编程语言，或一套 AI 系统 | nextpdf/server | NextPDF Connect：供远程执行使用的 REST、gRPC 与 Model Context Protocol 接口。 |
当两种集成方式都可能适用时
标题为“当两种集成方式都可能适用时”的章节把 HTML 渲染成 PDF：Artisan、Gotenberg、Cloudflare 与核心的取舍
标题为“把 HTML 渲染成 PDF：Artisan、Gotenberg、Cloudflare 与核心的取舍”的章节这三座 renderer 桥接都会把 markup（标记语言）转成 PDF。它们的差别在于运行方式，而不是质量，因此运行层面的差异才是决策依据。
nextpdf/artisan通过 Chrome DevTools Protocol 驱动 headless Chrome（无头 Chrome）。它需要一个应用程序可以连接到的 Chrome 进程。当你能操作这个进程，而且文档需要浏览器 CSS 引擎时，就选它。nextpdf/gotenberg通过 HTTP 调用一个跨进程的 Gotenberg 微服务。当渲染必须隔离在自己的服务中，或输入是一份 Office 文档时，就选它。在这三者之中，只有 Gotenberg 的声明用途包含 Office 转 PDF。nextpdf/cloudflare调用 Cloudflare Browser Rendering API。当你需要 edge/serverless 渲染，又不想运行或修补任何浏览器进程时，就选它。- 进程内的 NextPDF 核心 HTML 流水线 完全不需要上述任何一项。只有当进程内流水线无法达到文档所需的版面保真度或进程隔离要求时，才使用 renderer 桥接。使用桥接意味着刻意把这一步交接出去，而不是默认路径。
这两座 HTTP 桥接（nextpdf/gotenberg、nextpdf/cloudflare）都需要一个由宿主端提供的 PSR-18 HTTP client。它们的 recipe（范例）会把传输失败与非成功的 HTTP 状态视为两种不同结果。
转换一份 Office 文档
标题为“转换一份 Office 文档”的章节nextpdf/gotenberg 就是经过验证的 composer.json 描述中明确点名 Office 转 PDF 的集成方式。其他几座 renderer 桥接描述的是 HTML 渲染，而不是 Office 输入。如果来源是 DOCX/XLSX/ODT，这就是与你相配的选择。
从旧版 PDF library 迁移出来
标题为“从旧版 PDF library 迁移出来”的章节就其声明用途而言，nextpdf/compat-legacy 是供那些针对旧版 PDF library 编写的代码使用的兼容层。它让既有调用点在尚未改写之前，就能连接到 NextPDF。应把它视为有计划移除时间表的迁移过渡辅助，而不是长期运行期依赖。新的代码则直接调用 nextpdf/core（或对应的框架集成）。
在 PHP 8.1 或 7.4 上运行
标题为“在 PHP 8.1 或 7.4 上运行”的章节每个生态系统软件包都声明 PHP >=8.4 <9.0。nextpdf/backport-builder 的存在正是为了应对这个限制：它声明的用途是一条 Rector 降级流水线，会构建出一份 PHP 8.1+（以及一份 7.4 目标）的产物。它是构建工具，而不是你应用程序的运行期依赖。先运行这个构建器生成降级后的引擎，然后再部署那份引擎。
非 PHP 调用方或 AI Agent（代理）
标题为“非 PHP 调用方或 AI Agent（代理）”的章节nextpdf/server（NextPDF Connect）通过 REST API、gRPC 服务与 Model Context Protocol 将引擎对外开放。当调用方位于远程、使用另一种编程语言，或是一套消费工具 endpoint 而非 PHP library 的 AI 系统时，就选它。同一进程内的 PHP 应用程序则应改用 nextpdf/core 或框架集成，以免付出一次网络往返的代价。
同时使用多种集成方式
标题为“同时使用多种集成方式”的章节框架集成与 renderer 桥接运行在不同层级，所以你可以同时安装两者。框架集成负责容器接线与 HTTP 响应；renderer 桥接负责渲染 backend（后端）。当你要 resolve（解析）一组合并后的依赖集合时，请检查每个软件包各自接受哪些 nextpdf/core 版本。关于这一点，集成 Cookbook 索引 中的核心版本约束参考才是事实来源。各种组合的 recipe 位于对应仓库中，并从该索引链出。
另请参阅
标题为“另请参阅”的章节- 集成 Cookbook — 软件包与核心版本约束参考，以及 recipe 链接索引。
- Recipe 约定 — 每个可运行 recipe 都遵循的契约。