安装 NextPDF

概览

每个 NextPDF 发行版都可以通过一行包管理器命令安装。PHP 发行版使用 Composer；Python SDK 使用 pip。选择符合你需求的选项卡，运行对应命令，再用本页底部的验证步骤确认结果。

同一个引擎，多道入口

核心引擎是 nextpdf/core。 Framework（框架）集成、HTML renderer（渲染器）、 服务器与 Python 客户端都在它之上额外添加一个包。它们都不会取代核心引擎，并且都会自动把它一并引入。

系统需求

NextPDF 只锁定一个现代运行时环境。以下约束条件直接来自各个包自身的 composer.json 文件。

需求项	约束条件	说明
PHP	>=8.4 <9.0	在 PHP 8.3 以下或 PHP 9 上，Composer 会拒绝安装。
Composer（包管理器）	2.7 或更新版本	依赖包的 resolve（解析）器和 autoloader 生成器。
ext-mbstring	必需	用于文本排版的多字节字符串处理。
ext-zlib	必需	用于 PDF 对象的流压缩。
Chrome 或 Chromium	可选	仅供 Artisan renderer（渲染器）（writeHtmlChrome()）使用。
Gotenberg 服务	可选	仅供通过 Gotenberg 进行 Office 与 HTML 转换时使用。
Python（编程语言）	3.10 或更新版本	仅供 Python SDK 使用。

ext-mbstring 与 ext-zlib 在每个受支持的 PHP 构建中都默认启用。集成包会在启动时检查它们；如果缺少任意一个，就会以清晰的消息停止运行。

安装核心

如果只需要用 PHP 生成和查看 PDF，核心引擎就是你唯一需要安装的包。

composer require nextpdf/core

请提交 composer.lock，确保每个已部署的 worker 都解析到相同的引擎版本。安装完成后，请继续阅读 你的第一份 PDF。

安装框架集成

安装一个 framework 适配器，即可获得容器绑定、响应辅助方法和队列任务。每个适配器都会声明 nextpdf/core，并为你解析该依赖。

Laravel

composer require nextpdf/laravel

自动发现会注册服务提供者和 Pdf facade。接着发布配置文件：

php artisan vendor:publish --tag=nextpdf-config

请参阅 Laravel 安装指南 和 Laravel 快速入门。

Symfony

composer require nextpdf/symfony

在 Symfony Flex 应用程序中，bundle 会自动注册。在非 Flex 应用程序中，你需要自行将 NextPDF\Symfony\NextPdfBundle 添加到 config/bundles.php。请参阅 Symfony 安装指南。

CodeIgniter

composer require nextpdf/codeigniter

CodeIgniter 4 会自动发现 Services 类和 pdf() 辅助函数，因此不需要手动注册。请参阅 CodeIgniter 安装指南。

安装 renderer（渲染器）或服务

NextPDF 提供三种将 HTML 渲染为 PDF 的方式。请根据希望执行渲染的位置安装对应选项。这些都不会取代 writeHtml()，也就是核心引擎内置的纯 PHP HTML 管线。

Artisan（Chrome）

composer require nextpdf/artisan

通过 Chrome DevTools Protocol（CDP）增加 headless Chrome 渲染能力。你还需要在主机上提供一个可访问的 Chrome 或 Chromium 可执行文件。安装完成后，在文档对象上调用 writeHtmlChrome()。请参阅 Artisan 快速入门。

Cloudflare

composer require nextpdf/cloudflare guzzlehttp/guzzle

在边缘端通过 Cloudflare Browser Rendering 渲染。这个桥接器只依赖 PSR-18 和 PSR-17 接口，因此需要你提供 HTTP 客户端（这里演示的是 Guzzle）。请参阅 Cloudflare 安装指南。

Gotenberg

composer require nextpdf/gotenberg guzzlehttp/guzzle

通过 Gotenberg 服务转换 Office 文档和 HTML。你需要提供一个 PSR-18 客户端，以及一个可访问的 Gotenberg 实例。请参阅 Gotenberg 安装指南。

renderer 会触及 PHP 之外

Artisan 会启动浏览器进程，Cloudflare 与 Gotenberg 则会调用网络服务。请将 HTML 视为不受信任的内容，并在渲染用户可影响的输入之前， 先阅读各个包的 security-and-operations 页面。

安装服务器

NextPDF Server（也称为 Connect）是一个独立服务。它通过 MCP、REST 和 gRPC 对外公开引擎功能。

composer require nextpdf/server

这个包会在 vendor/bin/ 中加入控制台入口点，包括 vendor/bin/nextpdf-mcp（MCP stdio 服务器）和 vendor/bin/nextpdf-server（REST 服务器）。REST 和 gRPC 传输还需要 RoadRunner 可执行文件：

./vendor/bin/rr get-binary

请参阅 Connect 安装指南 和 Connect 快速入门。

安装 Python SDK

Python SDK 是一个类型化客户端，用于对接正在运行的 NextPDF Server。请从 PyPI 安装它：

pip install nextpdf

这个 SDK 需要 Python 3.10 或更新版本，以及一个可访问的 NextPDF Server endpoint。请参阅 Python SDK 快速入门。

验证安装

开始写代码之前，先确认每个发行版都已正确解析。

核心 / PHP

composer show nextpdf/core

如果出现版本信息行，就表示引擎已安装并接入 autoloader。

Laravel

php artisan package:discover --ansi

输出会在已发现的包中列出 nextpdf/laravel。

Symfony

php bin/console debug:container nextpdf

容器会报告 nextpdf.document 别名和 PdfFactory 服务。

服务器

./vendor/bin/generate-skills --dry-run --list-tools

这会启动注册表，并打印此安装公开的工具，而不会实际启动服务器。

Python

nextpdf version

如果出现版本字符串，就表示 SDK 已能正常导入。

另请参阅

你的第一份 PDF 用 PHP 生成 PDF，并把 HTML 渲染成 PDF。

选择你的路线 决定哪一个发行版与 HTML renderer 适合你的应用程序。

集成 完整的扩展对照表与选择指南。

Connect（服务器） 以网络服务形式，通过 MCP、REST 与 gRPC 运行引擎。