整合決策指南

Spec Spec: ISO/IEC/IEEE 26514:2022, §3.x162 ISO/IEC/IEEE 26514:2022 §3.x162 Spec Spec: ISO 24495-1:2023, §5 ISO 24495-1:2023 §5 Evidence ¶ Editorial Evidence: Editorial

一覽

NextPDF 生態系由一個小巧的核心引擎，加上一組各司其職的套件組成——框架橋接、兩個 HTML 轉譯器、一個邊緣轉譯器，以及一個執行伺服器。本頁會把真實使用情境對應到合適套件，依據是各套件實際提供的內容。選擇權仍留給你，讓你依據證據做決定，而不是由本文件替你下結論。

為何這很重要

選錯整合方式的代價很高，而且不會立刻顯現。若行程內引擎原本就能順利轉譯該文件，你卻選了遠端瀏覽器轉譯器，就等於替每一份 PDF 加上一次網路往返與一項可用性相依。若某份文件確實需要完整的瀏覽器版面引擎，你卻選了行程內引擎，產出的檔案就會出現細微錯誤。你採用的套件會形塑延遲、故障模式與維運面，因此這項決定值得明確攤開來談。

簡短版

• 從核心引擎開始。 其他一切都是額外加上的層。只要行程內引擎能正確轉譯你的文件，你就完全不需要任何轉譯器套件。
• 框架橋接取決於你的框架，而不是你的文件。 Laravel、Symfony 與 CodeIgniter 整合的存在，是為了讓你取得 facade 或 factory、PDF 回應、佇列化產生與自動探索——它們並不會改變引擎能轉譯的內容。
• 只有當 CSS 保真度需要瀏覽器時，才使用轉譯器。 Artisan（本機 Chrome）與 Cloudflare（邊緣瀏覽器）正是為此而存在；Gotenberg 則是為了把 Office 文件帶進來。
• 當呼叫端是服務或 AI 代理，而不是 PHP 呼叫時，使用 Connect。 它透過 MCP、REST 與 gRPC 將引擎對外公開，並為危險操作設有人工確認關卡。

NextPDF 的處理方式

這個生態系刻意分層，讓每個套件只負責一件事。核心引擎在行程內轉譯 PDF。框架橋接把該引擎調整為某個框架的慣用寫法。當行程內引擎不是合適工具時，轉譯器套件會把 HTML 或 Office 版面交付給外部引擎處理。Connect 把引擎變成一項網路服務。這些套件的職責彼此不重疊，這正是讓決策變得可處理的關鍵。你並不是在彼此競爭的工具之間做選擇，而是在組合彼此互補的工具。

這項決定最好針對使用情境來做。下表把每個情境對應到合適套件，並說明你會接受哪些取捨。

使用情境	合適的套件	它實際提供什麼	你接受的取捨
Laravel 應用程式中的 PDF	nextpdf/laravel	自動探索的 service provider、Pdf facade、PdfResponse（行內/下載/串流，含 OWASP 標頭）、一個帶有 tries/timeout/backoff 的佇列化 GeneratePdfJob，以及 Octane 安全的鎖定註冊表	一項 Laravel 12 相依；引擎能力維持不變
Symfony 應用程式中的 PDF	nextpdf/symfony	自動註冊的 bundle、可注入的 PdfFactory、PdfResponse，以及一個用於非同步產生的選用 Messenger handler	一項 Symfony 7.2 bundle 相依；能力維持不變
CodeIgniter 4 應用程式中的 PDF	nextpdf/codeigniter	service('pdf') / pdf() 輔助函式、一個包裝可丟棄式 Document 的 Pdf library、一個 PdfResponse，以及一個選用的佇列化 job	一項 CodeIgniter 4.6 相依；能力維持不變
文件需要完整的瀏覽器 CSS（flex/grid/網頁字型），且希望在接近行程內的環境中處理	nextpdf/artisan	透過 CDP 的無頭 Chrome，先行轉譯後再以 Form XObject 匯入回來，使文字維持可選取；外加一個瀏覽器集區	主機上的一個 Chrome 執行環境及其 memory/process 成本
Office 文件（.docx、.xlsx）轉成 PDF	nextpdf/gotenberg	一個通往 Gotenberg 微服務的 PSR-18 橋接，採用 SSRF 強化、IP 釘選的傳輸	一個外部的 Gotenberg 服務及一項網路相依
在邊緣執行 HTML→PDF/不需本機 Chrome	nextpdf/cloudflare	Cloudflare Browser Rendering，透過釘選傳輸，並可選用本機 Chrome 後備	一個 Cloudflare 帳號及一項網路相依；後備需要 Artisan
引擎由服務或 AI 代理取用	nextpdf/server（Connect）	單一引擎透過 MCP（stdio）、REST（OpenAPI 3.1）與 gRPC 對外公開；軟相依的工具探索；針對高風險工具的人工確認關卡	維運一個服務面；確定性執行的紀律

Human-factors note: Human-factors note

這是兩項各自獨立的決定，但人們常把它們混為一談。所謂的 框架橋接 取決於你早已使用的框架——它並不會擴張或限制引擎所能轉譯的內容。所謂的 轉譯器 則取決於文件。決定的關鍵問題在於：行程內 CSS 引擎是否已經足夠，或者該文件確實需要一個瀏覽器版面引擎。你可能需要框架橋接而不需要轉譯器、需要轉譯器而不需要橋接、兩者都需要， 也可能兩者都不需要。把它們當成同一個問題來決定，是最常見的整合錯誤，這正是本頁將兩者分開處理的原因。

證據怎麼說

本頁屬於 編輯性質——也就是一項路由決策——但這項路由是以各套件的 manifest 與主要類別實際所含內容為依據。

Evidence ¶ Editorial Evidence: Editorial

這些橋接都確實存在，且彼此並行。每個橋接都在其 composer.json 中宣告其框架相依與自動註冊（extra.laravel.providers、extra.symfony.bundles、CodeIgniter 的 Registrar）。每個橋接也都隨附一個 PdfResponse、一個可丟棄式文件綁定，以及一個選用的佇列化 job。它們沒有任何一個會增添轉譯能力——它們只是調整同一個引擎的使用方式。這些轉譯器也都確實存在，且彼此不同。Artisan 相依於 chrome-php/chrome，並把 Chrome 產生的 PDF 以 Form XObject 匯入回來，以維持文字可選取。Gotenberg 與 Cloudflare 都是 PSR-18 HTTP 橋接，採用明確 SSRF 強化、IP 釘選的傳輸。當 Worker 無法連線時，Cloudflare 可後備至 Artisan。Connect 的 composer.json 宣告了三種傳輸，以及一套軟相依模型——工具會隨著對應套件安裝而出現，並由一個四級風險模型與一道人工確認關卡所管理。

本頁為你路由的方式在形式上是 有標準支撐的： Spec Spec: ISO 24495-1:2023, §5 ISO 24495-1:2023 §5 指出讀者應能快速判斷內容是否符合其目的（chunk），而 Spec Spec: ISO/IEC/IEEE 26514:2022, §3.x222 ISO/IEC/IEEE 26514:2022 §3.x222 要求連結與參照標明其指向的目的地 ——這正是為何表格直接點名具體套件與取捨，而不是含糊地提到「某個整合」。

實務範例

這項決定是一連串坦誠的提問，而不是功能比較。以下內容釐清常見情況。

1. Does the in-process engine render the document correctly?
   YES → you need NO renderer package. Stop here for rendering.
   NO  → continue.

2. Is the source an Office file (.docx/.xlsx)?
   YES → nextpdf/gotenberg (external Gotenberg service).
   NO  → continue (it is HTML/CSS fidelity you need).

3. Can you run a local Chrome on the host?
   YES → nextpdf/artisan (local CDP renderer).
   NO  → nextpdf/cloudflare (edge; optional Artisan fallback).

Independently of 1–3, choose how the engine is CALLED:
   In a PHP web app?        → the matching framework bridge.
   By a service / AI agent? → nextpdf/server (Connect).
   Neither?                 → use the core engine directly.

這段結構本身就是重點：轉譯與呼叫是兩個分開的維度。把它們一起回答，正是團隊最後導入一個其實不需要的遠端轉譯器，或一個無法解決保真度問題的橋接的原因。

常見的誤解

最常見的誤解是 「我需要一個轉譯器套件才能產生 PDF。」 你並不需要。核心引擎在行程內產生 PDF。轉譯器套件存在的唯一理由，是處理需要瀏覽器等級版面引擎，或來源為 Office 文件的特定情況。當行程內引擎已經能產生正確檔案時，慣性採用轉譯器只會徒增一項執行期相依與一種故障模式，毫無好處。

相對地，另一個誤解是 「框架橋接會解鎖能力。」 它並不會。橋接改變的是你 如何呼叫 引擎——facade、factory、回應、佇列化 job——而非它能 產生 什麼。簽章、PDF/A 與結構化發票都屬於版本層級與引擎的範疇，無論你是透過橋接還是直接呼叫，皆完全相同。

限制與邊界

• 本頁負責路由；它不做基準測試，也不排名。 它陳述的是各套件提供什麼，以及取捨為何。在它們之間做選擇，是你依據自身限制條件所做的決定。
• 各套件的能力是在某一時間點，從其 manifest 與主要類別讀取而來。 請將各套件自己的文件視為其目前 API 的權威依據。本指南是地圖，而非規格。
• 本頁不提供、也不暗示任何競品比較。 唯一的主題就是 NextPDF 生態系，以及它各部分如何彼此契合。
• 框架橋接與轉譯器是各自獨立的選擇。 橋接不會擴張引擎能力；轉譯器也不相依於框架。
• 外部轉譯器會新增一項可用性相依。 Gotenberg 與 Cloudflare 引入一次網路呼叫與一項需要維運的服務；那是已接受的取捨，而非隱藏成本。
• 受版本層級閘控的能力與整合是正交的。 商業功能由版本層級解鎖，而不是由任何橋接或轉譯器解鎖；參見下方的邊界。

Ecosystem packages and tiering — edition availability

Edition	Availability
Core	○ 每個整合套件（橋接、Artisan、Gotenberg、Cloudflare、 Connect）都針對 Core 運作，並採用 Apache-2.0 授權。它們調整或公開該引擎；它們並不對功能設閘。
Pro	○ 商業能力（PAdES baseline 簽署、PDF/A、進階條碼）由版本層級解鎖，隨後即可 透過 任何整合取用，而不是靠切換整合來取得。
Enterprise	○ 結構化發票、驗證政策，以及針對高風險工具的 Connect 人工確認關卡，都屬於版本層級的能力， 同樣與整合無關。

相關文件

• HTML 管線——行程內 CSS 引擎涵蓋哪些範圍，讓你知道何時才真正需要瀏覽器轉譯器。
• 何時不該使用 NextPDF——坦率劃出哪些文件問題並不適合交給引擎處理。
• PHP 8.4 基礎——每個套件共享的執行期底線，以及 backport 路徑所保留的內容。

詞彙表

• 核心引擎——nextpdf/core，其他每個套件都建構於其上的行程內 PDF 2.0 引擎。
• 框架橋接——一個整合套件（Laravel/Symfony/CodeIgniter），在不改變引擎能力的前提下，把引擎調整為某個框架的慣用寫法。
• 轉譯器套件——當行程內引擎不是合適工具時，把 HTML 或 Office 版面交付給外部引擎（Artisan/Cloudflare/Gotenberg）處理的套件。
• Form XObject——一段可重複使用的 PDF 內容片段；Artisan 把瀏覽器轉譯的頁面匯入成這樣的片段，使其文字維持可選取。
• NextPDF Connect——nextpdf/server，以確定性執行面，透過 MCP、REST 與 gRPC 公開引擎的套件。
• 軟相依——Connect 的模型，工具會隨著選用的 NextPDF 套件安裝而自動出現，無須變更程式碼。