指南
指南帮助你将 NextPDF 接入代码实际运行的环境。本栏目先介绍 生产运维检查清单，然后按采用顺序涵盖五个方面：framework（框架）与 renderer（渲染器）集成、NextPDF Connect 服务器、Python SDK、引擎扩展开发，以及故障排查。下面每节先给出章节入口，再列出最常用的页面。
如果需要可直接复制、面向具体任务的 recipe（示例），请使用 Cookbook（示例指南）。如果需要已验证的应用程序编程接口（API）和支持矩阵，请查阅 参考资料。
八个包将核心引擎连接到各类框架、浏览器 renderer（渲染器）、边缘服务、构建工具，以及旧系统迁移路径。每个包的章节都遵循相同的手册结构：概述、安装、快速上手、配置、API、开发者指南、生产环境使用、安全性，以及故障排查。因此，只要熟悉其中一个，就能快速理解其余章节的结构。
| 页面 | 适用场景 |
|---|---|
| 集成 | 扩展范围与选型指南。请先阅读本页，以选择合适的包。 |
| 集成 API 索引 | 说明每个 framework（框架）、renderer（渲染器）、transport（传输）和构建工具接口所对应的扩展 API 页面。 |
| 适用于 Laravel 的 NextPDF | Laravel 框架适配器。 |
| 适用于 Symfony 的 NextPDF | Symfony 框架适配器。 |
| 适用于 CodeIgniter 的 NextPDF | CodeIgniter 框架适配器。 |
| NextPDF Artisan | 面向浏览器级 HTML 渲染的 Chrome renderer（渲染器）桥接器。 |
| NextPDF Cloudflare | Cloudflare 上的边缘部署路径。 |
| NextPDF Gotenberg | Gotenberg renderer（渲染器）桥接器。 |
| TCPDF 兼容性 | 供从 TCPDF 迁移出来的代码库使用的兼容 shim（兼容层）。 |
| NextPDF Backport Builder | 面向较旧 PHP 运行时的构建工具。 |
NextPDF Connect
标题为“NextPDF Connect”的章节nextpdf/server 包会将引擎作为长期运行的服务启动：它提供一个确定性的工具注册表，通过 Model Context Protocol（MCP）、表述性状态转移（REST）和 gRPC 对外提供服务，并为高风险工具设置人工介入（human-in-the-loop）确认 gate。
| 页面 | 适用场景 |
|---|---|
| NextPDF Connect | 本章入口：服务器概念、配置和运维。 |
| Connect 概览 | 包边界与三种 transport（传输）。 |
| Connect 快速入门 | 一个可运行的首次 MCP 握手流程，以及对应的 REST 渲染请求。 |
| NextPDF Connect 配置 | MCP YAML 文件与 NEXTPDF_* 环境变量。 |
| NextPDF Connect API 参考文档 | 每个已注册的工具、gRPC 符号、错误模型条目和速率限制。 |
| NextPDF Connect 部署 | RoadRunner worker 配置文件、Docker，以及以 Redis 为后端的存储。 |
| Connect 安全与运维 | 身份认证、传输安全与威胁模型。 |
每种 transport（传输）都有单独的参考页面。
| 页面 | 适用场景 |
|---|---|
| MCP 传输 | 基于标准输入和标准输出的 JSON-RPC 2.0 分帧。 |
| REST 传输 | OpenAPI 3.1 契约、Bearer 身份认证，以及按层级设置限制的路由。 |
| gRPC 传输 | nextpdf.connect.v1 服务、服务器流式传输与元数据身份认证。 |
Python SDK
标题为“Python SDK”的章节为 Python 应用程序、代理和命令行提供可调用的 PDF 提取功能，并由 NextPDF Connect endpoint 作为后端提供支持。
| 页面 | 适用场景 |
|---|---|
| Python SDK | nextpdf Python 包的章节入口。 |
| Python SDK 概览 | SDK 的能力，以及它与 Connect 的关系。 |
| Python SDK 快速入门 | 使用 pip install nextpdf 安装，并将客户端指向你的服务器。 |
| Python SDK API 参考 | 客户端类、方法和带类型的结果。 |
| Python CLI 工具 | 用于提取工作流的命令行界面。 |
| Python MCP 服务器 | 将 SDK 暴露给使用 MCP 的 Agent（代理）。 |
扩展引擎
标题为“扩展引擎”的章节公开的服务提供者接口（SPI）让你无需 fork 即可添加能力：它为字体、布局引擎、事件监听器和签名后端提供契约，并为每项契约给出明确的稳定性承诺。
| 页面 | 适用场景 |
|---|---|
| 扩展开发 | 你可以扩展哪些内容，以及对应的稳定性承诺。 |
| SPI 稳定性规则 | 你的扩展可以依赖的向后兼容契约。 |
| 自定义字体：FontRegistry 契约 | 注册并分发自己的字体。 |
| 自定义布局引擎与文本拦截 | 替换或拦截布局行为。 |
| 动作触发器与事件监听器 | 观测文档生命周期，并对其作出响应。 |
| KMS 提供方契约 | 使用你自己的密钥管理服务（KMS）提供密钥。 |
故障排查
标题为“故障排查”的章节这些条目按引擎自身的异常分类组织，帮助你从症状定位解法。请从观察到的现象出发，而不是从某个类名出发。
| 页面 | 适用场景 |
|---|---|
| 故障排查 | 知识库入口：了解条目的组织方式，以及从哪里开始排查。 |
| 故障排查：字体与标记 | 字体嵌入和结构标记失败。 |
| 故障排查：加密与权限 | 加密、密码与权限失败。 |
| 故障排查：内存与性能 | 内存上限和吞吐量问题。 |
| 故障排查：PDF/A 与 PDF/UA 验证 | 归档和无障碍验证失败。 |
| 故障排查：签章与时间戳 | 签名与时间戳验证失败。 |
另请参阅
标题为“另请参阅”的章节- Cookbook（示例指南） — 面向 PHP、Connect 和各项集成的任务导向 recipe（示例）。
- 参考文档 — 已验证的 API、支持矩阵和错误参考。
- 迁移到 NextPDF — 从另一个 PDF 库迁移；位于“开始使用”栏目中。
- 深入理解 NextPDF — Insider_ 系列文章，介绍引擎为何如此运作。