NextPDF Laravel 套件設定

概覽

config/nextpdf.php 透過 php artisan vendor:publish --tag=nextpdf-config 發布。每個鍵都有環境變數備援值與硬編碼預設值。本頁會逐一記錄每個鍵，並與套件中 config/nextpdf.php 的呈現完全一致。

安裝

php artisan vendor:publish --tag=nextpdf-config

provider 也會在 register() 期間，將套件預設值合併到 nextpdf 組態鍵之下。因此即使尚未發布組態，未設定的鍵也會回退到下列數值。

概念總覽

多數環境變數可使用 NEXTPDF_* 名稱，也可使用舊版 TCPDF_* 名稱。舊版前綴會在 UPGRADE.md 所記載的過渡期間內受支援；新部署應使用 NEXTPDF_* 形式。組態檔會依此順序 resolve（解析）數值：環境變數 → 已發布檔案值 → 套件預設值。

API 介面 — 組態鍵

文件版面

鍵	環境變數（主要）	預設值	作用
page_format	NEXTPDF_PAGE_FORMAT	A4	預設頁面格式（A4、A3、A5、Letter、Legal、Tabloid）
orientation	NEXTPDF_ORIENTATION	P	直向（P）或橫向（L）
unit	NEXTPDF_UNIT	mm	度量單位（pt、mm、cm、in）
defaults.creator	NEXTPDF_CREATOR	NextPDF	文件建立者中繼資料；套用於 PdfDocumentInterface 繫結
defaults.author	NEXTPDF_AUTHOR	（空）	作者中繼資料；僅在值不是空值時套用
defaults.language	NEXTPDF_LANG	en	文件語言；套用於文件繫結
defaults.margin_top / _right / _bottom / _left	—	10	預設邊界
defaults.font_family	—	dejavusans	預設字型家族
defaults.font_size	—	12	預設字型大小
defaults.trim_box	—	null	以點為單位的 TrimBox [left, bottom, right, top]，或 null
defaults.bleed_box	—	null	以點為單位的 BleedBox [left, bottom, right, top]，或 null

provider 會將 defaults.creator、defaults.language，以及（已設定時）defaults.author 套用到每份新解析出的文件上。當 defaults.author 的值為空時，會略過該分支。

封存與色彩

鍵	環境變數（主要）	預設值	作用
pdfa	NEXTPDF_PDFA	null	PDF/A 封存等級（null、4、4e、4f）。非 null 會在文件繫結上啟用 PDF/A，且需要 nextpdf/premium
fonts_path	NEXTPDF_FONTS_PATH	resource_path('fonts')	額外 TrueType 字型的存放目錄；作為字型登錄的搜尋路徑
cache_path	NEXTPDF_CACHE_PATH	storage_path('framework/cache/tcpdf')	已剖析字型與暫存檔的快取目錄
icc_profile.rgb	NEXTPDF_ICC_PROFILE_RGB	null	RGB ICC 設定檔路徑；啟用 PDF/A 時為必要
icc_profile.cmyk	NEXTPDF_ICC_PROFILE_CMYK	null	用於印刷工作流程的選用 CMYK ICC 設定檔
font_cache_locking	NEXTPDF_FONT_CACHE_LOCKING	true	對字型快取使用 flock，防止並行 queue worker 寫入時造成損毀

將 pdfa 設為非 null 值需要 Premium 方案。若未安裝 nextpdf/premium，在已設定 pdfa 的情況下解析文件繫結時， 會因 PDF/A 版本型別而擲出 class-not-found 錯誤。本頁不說明 Premium 封存行為；請參閱 Premium 文件。

Worker 記憶體（長生命週期執行環境）

鍵	環境變數（主要）	預設值	作用
preload_fonts	—	[]	worker 開機時剖析的絕對字型檔路徑清單。字型登錄會在暖機後鎖定
image_cache_mb	NEXTPDF_IMAGE_CACHE_MB	50	以 MB 為單位的 LRU 影像快取預算。0 會停用快取。provider 層級不強制任何上限

影像快取預算沒有 provider 強制上限。請套用容器記憶體限制或 php.inimemory_limit 加以限制。組態檔建議以 256 MB 作為實務上的最大值。

數位簽章（Premium）

鍵	環境變數（主要）	預設值	作用
signature.enabled	NEXTPDF_SIGN_ENABLED	false	值為 false（或憑證為空）時，SignerInterface 會解析為 null
signature.certificate	NEXTPDF_SIGN_CERT	null	簽署憑證路徑
signature.private_key	NEXTPDF_SIGN_KEY	null	私密金鑰路徑
signature.password	NEXTPDF_SIGN_PASSWORD	（空）	金鑰密語
signature.extra_certs	—	[]	中介 CA 憑證路徑
signature.level	NEXTPDF_SIGN_LEVEL	B-B	傳入簽署器的 PAdES baseline 等級

本頁記載的 Core 套件不隨附簽署器實作；SignerInterface 繫結會解析為 null，直到 nextpdf/premium 提供簽署器為止。若安裝 Premium，level: B-B 會產生 PAdES B-B baseline 簽章。更高的 PAdES baseline 取決於已設定的時間戳記憑證機構與 Premium 能力；本頁不記載這些等級。

時間戳記憑證機構

鍵	環境變數（主要）	預設值	作用
tsa.url	NEXTPDF_TSA_URL	null	TSA endpoint。為空時，TsaClient 會解析為 null
tsa.username / tsa.password	NEXTPDF_TSA_USERNAME / _PASSWORD	（空）	TSA HTTP 認證用憑證
tsa.cert / tsa.key	NEXTPDF_TSA_CERT / _KEY	null	對 TSA 進行 mTLS 的用戶端憑證/金鑰
tsa.timeout	NEXTPDF_TSA_TIMEOUT	30	PSR-18 用戶端的 HTTP 逾時秒數
tsa.pinned_public_keys	—	[]	Base64 SHA-256 SPKI pin（RFC 7469）。留空會停用 pinning
tsa.warn_on_key_rotation	NEXTPDF_TSA_WARN_ROTATION	true	當 TSA 出示未 pin 的 SPKI 時發出警告
tsa.allow_insecure_http	NEXTPDF_TSA_ALLOW_INSECURE_HTTP	false	允許對 TSA 使用明文 HTTP。生產環境請維持 false

OCSP 回應快取

鍵	環境變數（主要）	預設值	作用
ocsp_cache.enabled	NEXTPDF_OCSP_CACHE_ENABLED	true	在驗證期間快取 OCSP 回應
ocsp_cache.ttl	NEXTPDF_OCSP_CACHE_TTL	86400	以秒為單位的快取 TTL
ocsp_cache.directory	NEXTPDF_OCSP_CACHE_DIR	null	快取目錄；null 會讓快取僅保留在記憶體中

佇列

鍵	環境變數（主要）	預設值	作用
queue.connection	NEXTPDF_QUEUE_CONNECTION	null	佇列連線；null 會使用預設連線
queue.queue	NEXTPDF_QUEUE_NAME	pdf	佇列名稱，GeneratePdfJob 會推送到這個佇列
queue.timeout	NEXTPDF_QUEUE_TIMEOUT	120	以秒為單位的每項工作逾時

Chrome CDP renderer（渲染器）（Artisan 擴充）

鍵	環境變數（主要）	預設值	作用
artisan.chrome_binary	NEXTPDF_ARTISAN_CHROME_BINARY	環境變數值或未設定	Chrome/Chromium 執行檔的路徑
artisan.render_timeout	NEXTPDF_ARTISAN_RENDER_TIMEOUT	30	以秒為單位的渲染逾時
artisan.default_css	NEXTPDF_ARTISAN_DEFAULT_CSS	（空）	注入已繪製 HTML 的預設 CSS
artisan.no_sandbox	NEXTPDF_ARTISAN_NO_SANDBOX	false	停用 Chrome sandbox
artisan.max_html_size	NEXTPDF_ARTISAN_MAX_HTML_SIZE	5000000	以位元組為單位的 HTML 輸入大小上限

只有在 Chrome browser-factory 類別存在時（即 nextpdf/artisan 擴充），artisan 區段才會套用到文件繫結上。若不存在，則會略過此區段。

程式碼範例 — 生產環境

resource: config/nextpdf.php (subset, verified against the published file)

<?php

declare(strict_types=1);

return [
    'page_format'     => env('NEXTPDF_PAGE_FORMAT', 'A4'),
    'orientation'     => env('NEXTPDF_ORIENTATION', 'P'),
    'unit'            => env('NEXTPDF_UNIT', 'mm'),
    'pdfa'            => env('NEXTPDF_PDFA', null),
    'fonts_path'      => env('NEXTPDF_FONTS_PATH', resource_path('fonts')),
    'preload_fonts'   => [],
    'image_cache_mb'  => env('NEXTPDF_IMAGE_CACHE_MB', 50),
    'queue' => [
        'connection' => env('NEXTPDF_QUEUE_CONNECTION', null),
        'queue'      => env('NEXTPDF_QUEUE_NAME', 'pdf'),
        'timeout'    => env('NEXTPDF_QUEUE_TIMEOUT', 120),
    ],
];

邊界情況與陷阱

• signature.enabled = true 搭配空的 signature.certificate 仍會把 SignerInterface 解析為 null；兩者都必須設定。
• tsa.url = null 會強制 TsaClient 為 null，即使其他 tsa.* 鍵已填入也一樣。
• signature.level = null 會讓簽署器回退到 PAdES B-B。
• image_cache_mb 若設為 null（而非 0），會回退到 50 MB 預設值；0 則會明確停用快取。
• 舊版 TCPDF_* 環境變數仍可讀取，但已棄用；請遷移到 NEXTPDF_*。

效能

讀取組態是 O(1) 陣列存取。preload_fonts 會在 worker 開機時進行一次性 O(f) 剖析，以換取較低的首次請求延遲。較大的 image_cache_mb 能減少重複的影像解碼，但代價是行程常駐記憶體增加。

安全性注意事項

tsa.allow_insecure_http 會削弱時間戳記的信任度，生產環境必須保持 false。TSA URL 只應來自受信任的組態；若透過管理介面對外暴露，請套用 egress 防火牆或 DNS 政策，以緩解請求偽造。請參閱 /integrations/laravel/security-and-operations/.

符合性

沒有任何規範性標準規範組態檔的形狀；所有鍵都會對照套件在所記載修訂版的 config/nextpdf.php 進行驗證。 簽章等級語意由 Premium 管理，不在本 Core 頁面的範圍內。

商業脈絡

安裝 nextpdf/premium 後，signature 與 tsa 區段會驅動 Premium 簽署。這是選用的 Enterprise 能力；此處記載的 Core 套件無需任何程式碼變更即可採用。請參閱 https://nextpdf.dev/get-license/?intent=laravel-signing。

另請參閱

• /integrations/laravel/install/ — 發布組態檔
• /integrations/laravel/production-usage/ — 在實際控制器中套用組態
• /integrations/laravel/security-and-operations/ — 強化 TSA 與佇列設定
• /integrations/laravel/boot-and-discovery/ — 每個鍵會驅動哪個繫結