指南
這些指南說明如何將 NextPDF 整合到程式碼實際執行的環境中。本頁先從生產環境維運檢查清單開始，接著依導入順序涵蓋五大領域：框架與 renderer（渲染器）整合、NextPDF Connect 伺服器、Python SDK、引擎擴充套件開發，以及疑難排解。以下每個章節都會先列出對應的中樞頁，再列出最常用的頁面。
若你需要可直接複製、依任務整理的 recipe（範例），請參閱 Cookbook（範例指南）。若你需要已驗證的 API 與支援矩陣，請參閱 參考資料。
八個套件會將核心引擎連接至框架、瀏覽器 renderer（渲染器）、邊緣服務、建構工具，以及舊系統移轉路徑。每個套件章節都採用相同的手冊結構——概觀、安裝、快速上手、組態、API、開發者指南、生產環境使用、安全性，以及疑難排解——因此只要熟悉其中一個，就能掌握其餘章節的閱讀方式。
| 頁面 | 用途 |
|---|---|
| 整合 | 擴充套件地圖與選用指南。請先閱讀本頁，再挑選套件。 |
| 整合 API 索引 | 說明各框架、renderer（渲染器）、傳輸與建構工具介面分別對應到哪一個擴充套件 API 頁面。 |
| Laravel 整合 | Laravel 框架轉接器。 |
| Symfony 整合 | 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 總覽 | 套件邊界與三種傳輸方式。 |
| Connect 快速入門 | 第一個可執行的 MCP 握手，以及對應的 REST 渲染請求。 |
| Connect 設定 | MCP YAML 檔案與 NEXTPDF_* 環境變數。 |
| Connect API 參考 | 每一個已註冊工具、gRPC 符號、錯誤模型條目與速率限制。 |
| Connect 部署 | RoadRunner worker 設定檔、Docker，以及以 Redis 為後端的儲存層。 |
| Connect 的安全性與維運 | 驗證、傳輸安全性，以及威脅模型。 |
每一種傳輸方式也都有各自的參考頁面。
| 頁面 | 用途 |
|---|---|
| MCP 傳輸 | 透過標準輸入與標準輸出的 JSON-RPC 2.0 封裝。 |
| REST 傳輸 | OpenAPI 3.1 契約、bearer 驗證，以及依層級管控的路由。 |
| gRPC 傳輸 | nextpdf.connect.v1 服務、伺服器串流，以及 metadata 驗證。 |
Python SDK
標題為「Python SDK」的區段提供 PDF 擷取功能，可由 Python 應用程式、代理與命令列呼叫，並由 NextPDF Connect endpoint 作為後端支援。
| 頁面 | 用途 |
|---|---|
| Python SDK 套件 | nextpdf Python 套件的章節中樞頁。 |
| Python SDK 總覽 | SDK 的功能，以及其與 Connect 的關係。 |
| Python SDK 快速上手 | 以 pip install nextpdf 安裝，再讓用戶端指向你的伺服器。 |
| Python SDK API 參考資料 | 用戶端類別、方法與具型別結果。 |
| Python CLI 命令列工具 | 用於擷取工作流程的命令列介面。 |
| Python MCP 伺服器 | 讓使用 MCP 的代理存取 SDK。 |
擴充引擎
標題為「擴充引擎」的區段公開的服務提供者介面（SPI）讓你無須 fork 即可新增能力：它提供字型、版面引擎、事件監聽器與簽章後端的契約，每一項都附有明確的穩定性承諾。
| 頁面 | 用途 |
|---|---|
| 擴充功能開發 | 可擴充的項目，以及背後的穩定性承諾。 |
| SPI 穩定性規則 | 擴充套件可依賴的向後相容契約。 |
| 自訂字型：FontRegistry 擴充契約 | 註冊並隨附自有字型。 |
| 自訂版面引擎與文字攔截 | 替換或攔截版面行為。 |
| 動作觸發器與事件監聽器 | 觀察文件生命週期並做出回應。 |
| KMS 提供者契約 | 從你自己的金鑰管理服務（KMS）提供金鑰。 |
疑難排解
標題為「疑難排解」的區段根據引擎本身的例外分類，提供以症狀為導向的解法條目。請從觀察到的現象開始，而不是先從類別名稱切入。
| 頁面 | 用途 |
|---|---|
| 疑難排解 | 知識庫中樞：條目的組織方式，以及應該從哪裡開始。 |
| 疑難排解：字型與標記 | 字型嵌入與結構標記失敗。 |
| 疑難排解：加密與權限 | 加密、密碼與權限失敗。 |
| 疑難排解：記憶體與效能 | 記憶體上限與吞吐量問題。 |
| 疑難排解：PDF/A 與 PDF/UA 驗證 | 封存與無障礙驗證失敗。 |
| 疑難排解：簽章與時間戳記 | 簽章與時間戳記驗證失敗。 |
另請參閱
標題為「另請參閱」的區段- Cookbook（範例指南） — 針對 PHP、Connect 與各項整合的任務導向範例。
- 參考資料 — 已驗證的 API、支援矩陣，以及錯誤參考。
- 遷移至 NextPDF — 位於「開始使用」頁面，協助你從其他 PDF 函式庫移轉。
- 深入理解 NextPDF — Insider_ 系列文章，說明引擎行為背後的原因。