NextPDF 常見問題集（FAQ）

概覽

本頁解答你在評估 NextPDF 或開始一個新專案時最先冒出的問題。每則解答都簡短，並連結到完整涵蓋它的頁面。NextPDF 是一個 PHP 8.4 引擎，產生並檢視 Portable Document Format（PDF）2.0 文件，也就是 ISO 32000-2 所定義的檔案格式。

如果你是全新使用者，請先閱讀開始上手，再回到這裡了解細節。

開始上手

我需要哪個版本：Core、Pro 還是 Enterprise？

先從 Core 開始。開源核心（nextpdf/core）在 Apache-2.0 授權下且免費地產生 PDF 輸出、把支援的 HTML 算繪成 PDF，並檢視 PDF。Core 已可為 PDF 進階電子簽章（PAdES）B-B 與 B-T 基準層級產出 CMS SignedData 簽章。當你需要進階的產生與文件操作、電子發票輸出（Factur-X / ZUGFeRD），或諸如遠端、雲端 KMS 與循序簽署等進階簽署工作流程時，選擇 Pro。當你需要 PDF/A 封存編寫工作流程、具備 Document Security Store 與文件時間戳記的 PAdES 長效層級（B-LT / B-LTA）、透過硬體安全模組（HSM）的硬體支援簽署，或合格電子簽章時，選擇 Enterprise。Pro 與 Enterprise 是 NextPDF Premium（付費產品線）的兩種授權版本；請見選擇你的路徑。

它真的是 Apache-2.0 嗎？

是的，對核心而言。nextpdf/core 宣告 "license": "Apache-2.0"，並在其 LICENSE 檔中隨附完整的 Apache License 2.0 文字。你可以使用、修改、再散布並商業化核心，但須遵守歸屬與 NOTICE 要求（Apache-2.0 §4）。NextPDF Pro 與 NextPDF Enterprise 是專有的商業版本，不在該授權的涵蓋範圍內。NextPDF 名稱與標誌是商標，與程式碼授權各自獨立。請見產品授權。

最低 PHP 版本是多少？

PHP 8.4。套件限制是 >=8.4 <9.0，因此 Composer 拒絕在 PHP 8.3 或以下、或在 PHP 9 上安裝。NextPDF 鎖定單一現代執行環境，並直接運用其語言功能。請見安裝 NextPDF。

它需要外部二進位檔或無頭瀏覽器嗎？

不，對核心引擎而言不需要。原生引擎以 PHP 與標準 PHP 擴充實作，沒有外部 PDF 二進位檔，也沒有強制的無頭瀏覽器：流暢 API 與內建的 writeHtml() HTML 管線都在處理程序內執行，沒有瀏覽器，也沒有網路呼叫。一個 Chrome 或 Chromium 二進位檔是選用的，而且只在 Artisan 算繪器（writeHtmlChrome()）才需要，你可另行以 nextpdf/artisan 安裝它。Cloudflare 與 Gotenberg 橋接也是選用的，並會呼出到某個服務。請見選擇你的路徑。

它需要哪些 PHP 擴充？

核心的 composer.json 需要標準擴充 ext-mbstring、 ext-zlib、ext-intl、ext-gd、ext-curl 與 ext-openssl，這些都是常見可用的 PHP 擴充；請確保它們在你的執行環境中已安裝且已啟用。ext-curl 支撐選用的網路往返——RFC 3161 時間戳記與遠端資產擷取——因此離線的原生產生不會運用到它，但 Composer 仍把它列為硬性需求。各整合會在啟動時檢查它們所需的擴充，並在缺少任何擴充時以清楚訊息停止。完整清單存放於套件的 composer.json 中；請見安裝 NextPDF。

我要如何產生我的第一個 PDF？

安裝核心，然後以流暢 API 建立一份文件：

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;

$document = Document::createStandalone();
$document->addPage();
$document->setFont('helvetica', 'B', 24);
$document->cell(0, 15, 'Hello, NextPDF!', newLine: true);
$document->save(__DIR__ . '/first.pdf');

請在你的第一個 PDF 中逐步走過它。

版本與授權

Core 有任何功能限制或浮水印嗎？

沒有。Core 是針對 Core 功能集的開源引擎，沒有浮水印，也沒有提示畫面。對 Core 功能集而言——產生、檢視、加密、PDF/A 與 PDF/UA 輸出原語，以及軟體金鑰 B-B/B-T 簽署（不含 Premium 的長效驗證與金鑰保管工作流程）——Core 是完整的。評估浮水印只套用於 Premium 評估授權，在其中你以可移除的標記在背後測試完整的 Pro 與 Enterprise 功能集；一份付費授權會在不變更應用程式碼的情況下移除它。請見授權與啟用。

升級到 Pro 或 Enterprise 需要變更程式碼嗎？

大多不需要。當你安裝 nextpdf/premium 時，框架整合與伺服器會自動偵測它並揭露額外功能。多數應用程式維持相同的高階整合點；某些 Premium 工作流程可能需要設定或特定功能的呼叫。你每個部署啟用一份已簽署的授權封套一次。請見授權與啟用。

我可以在封閉原始碼的商業產品中使用核心嗎？

可以。Apache License 2.0 沒有非商業限制。你可以在封閉原始碼、付費或內部的商業產品中使用核心，前提是你履行歸屬與 NOTICE 義務，且不把程式碼授權視為使用 NextPDF 品牌的許可。請見產品授權與商標與品牌使用。

功能

它能讀取並剖析 PDF，還是只能寫入它們？

兩者皆可，但有一個附帶條件。NextPDF 寫入 PDF，也讀取它們：Inspect 模組把既有檔案讀入一個帶有複雜度、字型、影像與風險資料的結構化 InspectResult，而且你可以合併與分割既有文件。Inspect 被標記為實驗性，因此其結果形狀可能在小版本之間改變——請把它用於診斷與閘控，而非作為長存的合約。請見 Inspect 模組。

它產出可選取、可搜尋的文字嗎？

是的。流暢 API 與內建的 writeHtml() 管線都發出真正的文字內容，而非點陣化的影像，因此輸出可選取且可搜尋。Artisan 算繪器的 writeHtmlChrome() 也會保持文字可選取。請見你的第一個 PDF。

HTML 與 CSS 算繪如何運作？

核心引擎包含一個純 PHP 的 HTML 管線。writeHtml() 以支援的 CSS 子集把一個 HTML 片段直接算繪到頁面上，沒有瀏覽器，也沒有網路呼叫。當某個版面需要完整的瀏覽器保真度——例如 flexbox、grid 或 web 字型——請安裝 Artisan 算繪器並呼叫 writeHtmlChrome()。在你依賴某個屬性之前，請查閱 CSS 支援矩陣。

字型如何運作？

諸如 Helvetica 的內建標準字型別名對簡單的 WinAnsi 文字無須任何設定即可運作，因此你的第一份文件不需要字型檔。內建的拉丁標準字型適合基本的 WinAnsi 文字；Symbol 與 ZapfDingbats 使用它們自己的編碼；若要算繪其他文字系統，你要註冊並嵌入一個其字元映射與字形塑形路徑支援該文字系統的字型。請見字型支援矩陣與 Font 模組。

它支援 PDF/A 與無障礙（PDF/UA）嗎？

支援，但有一個明確的界線：支援某個 profile 不等於符合它。核心隨附規範鑑別器與標記原語——enableTaggedPdf() 啟用 PDF/UA 工作流程所使用的 tagged-PDF 結構輸出，而 enablePdfA() 在 Core 中選定一個 PDF/A 輸出 profile；Premium 版本在其之上加入更高階的封存編寫工作流程與工具（驗證、政策與生產作業）。NextPDF 發出某個 profile 所要求的結構性成品；像 veraPDF 這樣的獨立驗證器才決定某個給定檔案是否實際符合。請見規範性與 Accessibility 模組。

我要如何簽署一個 PDF？

核心可以透過所設定的簽署提供者，使用支援的軟體金鑰演算法，產出密碼學訊息語法（CMS）SignedData 簽章，並可套用 RFC 3161 時間戳記（B-T 層級）。你的程式碼依賴 SignerInterface 合約，因此相同的呼叫在各版本間都適用。PAdES B-LT 與 B-LTA 長效層級、HSM 與 PKCS#11 金鑰保管，以及合格簽章，都是 Enterprise 功能；雲端與 KMS 支援的簽署工作流程則隨 Pro 提供。Core 產出 B-B 與 B-T 基準結構。請見 Signing 模組。

正式環境

它是 worker-safe 且 thread-safe 的嗎？

一個 Document 是一次性使用的：一旦你寫出了一份，就為下一份文件建立一個全新實例，而非重用它。這讓它自然契合 PHP-FPM、佇列 worker 與框架所使用的每請求、每任務模型——每個工作單元建立它自己的文件。當你剖析或組成不受信任的輸入時，請在一個受約束的 worker 中執行那項工作，並把資源防護（maxFiles、maxTotalBytes、maxBytes）保持緊湊。請見 Document 模組與引擎威脅模型。

輸出是決定性的嗎？

它在結構上是決定性的，但預設並非逐位元組相同。同一輸入跑兩次會產出結構相等的 PDF，但每份都攜帶一個全新的 trailer 與文件 /ID，因此位元組有所不同。簽署與時間戳記在設計上會增添更多每次執行的變異。請圍繞結構相等規劃比對，或正規化那些易變欄位，而非預期跨執行間的位元組相同。

我要如何部署它？

提交 composer.lock，讓每個已部署的 worker 解析到相同的引擎版本，然後像部署任何 PHP 函式庫一樣部署——原生產生不需要 daemon、瀏覽器或網路；時間戳記（B-T）、遠端資產，或選用的瀏覽器橋接，則需要已設定的網路存取。如果非 PHP 服務需要這個引擎，請執行 NextPDF Server，它透過模型情境協定（MCP）、REST 與 gRPC 揭露它。對 Premium 而言，請把已簽署的授權封套放在部署載入它之處，並執行一次性的啟用步驟；經快取的授權狀態意味著正常處理不需要授權服務，因此支援氣隙部署。請見安裝 NextPDF 與授權與啟用。

出問題時我要去哪裡處理失敗？

NextPDF 以 PHP 例外類別回報錯誤，而非以字串錯誤碼，且情境感知的例外攜帶結構化的診斷欄位。疑難排解把常見的簽章、PDF/A、PDF/UA、字型、標記與加密失敗對應到它們的成因與解法。