安裝 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 執行引擎。