安裝 NextPDF

概覽

每一個 NextPDF 發行版都只需要一行套件管理器指令即可安裝。PHP 發行版使用 Composer；Python SDK 則使用 pip。選擇符合需求的分頁，執行該指令，再用本頁底部的驗證步驟確認結果。

同一個引擎，多道入口

核心引擎是 nextpdf/core。 Framework（框架）整合、HTML renderer（渲染器）、 伺服器與 Python 用戶端都會在其上再加裝一個套件。它們都不會取代核心引擎，而且全都會替你一併引入。

系統需求

NextPDF 只鎖定單一現代執行環境。下列限制條件直接來自各套件本身的 composer.json 檔案。

NextPDF 執行階段需求，讀取自各套件本身的 composer.json 檔案

需求項目	限制條件	狀態	備註
PHP	>=8.4 <9.0	必要	Composer 會拒絕安裝於 PHP 8.3（含）以下或 PHP 9 的環境。
Composer	2.x	必要	解析相依性與產生自動載入器時所需。
ext-mbstring	—	必要	用於文字排版的多位元組字串處理。
ext-zlib	—	必要	用於 Portable Document Format (PDF) 物件的串流壓縮。
ext-intl	—	必要	International Components for Unicode (ICU) 服務：雙向文字、斷行，以及依地區設定的格式化。
ext-gd	—	必要	用於內嵌影像的點陣圖解碼與處理。
ext-curl	—	必要	網路往返：RFC 3161 時間戳記與遠端資產擷取。離線產生不會用到它，但 Composer 仍然需要它。
ext-openssl	—	必要	用於數位簽章、CMS 結構與加密的密碼編譯。
Chrome or Chromium	—	選用	僅供 Artisan 轉譯器 (writeHtmlChrome()) 使用。
Gotenberg service	—	選用	僅供透過 Gotenberg 進行辦公文件與 HTML 轉換使用。
Python	3.10+	選用	僅供 Python software development kit (SDK) 使用。

ext-mbstring 與 ext-zlib 在大多數 PHP 組建中都預設啟用；ext-intl、ext-gd、ext-curl 與 ext-openssl 則因發行版而異，因此請在安裝前以 php -m 確認這六個擴充功能是否都已啟用。整合套件會在啟動時檢查各自所需的擴充功能；若缺少任何一個，就會以清楚的訊息停止。

安裝核心

如果你只需要用 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 適合你的應用程式。

購買與授權透過我們的登錄商家購買 Pro 或 Enterprise 授權，接著安裝並啟用。

整合套件完整的擴充對應表與選擇指南。

Connect（伺服器）以網路服務形式，透過 MCP、REST 與 gRPC 執行引擎。