NextPDF Cloudflare 邊緣轉譯橋接器：總覽

概覽

nextpdf/cloudflare 是一個邊緣轉譯橋接器。你的 PHP 應用程式持有 HTML，而 Cloudflare Worker 持有無頭瀏覽器。橋接器透過 HTTPS 將 HTML 傳送給 Worker，並接收回傳的已轉譯 PDF 位元組。無頭瀏覽器不會在你的 PHP 行程內執行，橋接器負責的路徑上也不需要任何本機 Chromium 二進位檔。

這個套件屬於 NextPDF 生態系，並相依於 nextpdf/core^3.0。它是線路協定層的程式碼：建構 JSON 請求、驗證輸入與目的地、透過 PSR-18 用戶端送出請求，並將回應解析為具型別的結果物件。Worker 實作本身並非此套件的一部分；這個橋接器會與你自行部署的 Worker 溝通。

信任邊界

這個橋接器的決定性特徵在於：HTML 會跨越網路邊界，抵達一個你無法直接控制的瀏覽器引擎。套件中的每一項安全控管，都是因為這道邊界而存在。

HTML 會在離開 PHP 行程之前接受驗證（CloudflareSecurityPolicy::validate()）。
目的地 URL 會在送出請求之前接受驗證（CloudflareSecurityPolicy::validateWorkerUrl()），並在請求時再次驗證，以封閉 time-of-check/time-of-use 空窗（assertPinsStillValid()）。
此傳輸層可釘選解析後的 IP 集合，以及伺服器憑證的公開金鑰（Transport\PinnedCurlTransport）。

如果你正在評估是否將此橋接器用於正式環境，請先閱讀 /integrations/cloudflare/security-and-operations/，再閱讀 /integrations/cloudflare/quickstart/。這套安全模型不是附加元件，而是此套件採取這種形態的原因。

它的功能

能力	支援來源
透過 Cloudflare Worker 將 HTML 轉譯為 PDF	`CloudflareHtmlRenderer::render()`
可達性探測（HTTP `HEAD`）	`CloudflareHtmlRenderer::isAvailable()`
不鎖定特定廠商的傳輸層	注入 PSR-18 `ClientInterface`
輸入強化（大小、base64 炸彈、meta-refresh）	`CloudflareSecurityPolicy::validate()`
SSRF / DNS-rebinding 防禦	`CloudflareSecurityPolicy::validateWorkerUrl()` + `assertPinsStillValid()`
TLS 公開金鑰釘選，並於 cURL 層釘選 DNS	`Transport\PinnedCurlTransport`
Worker 無法連線時改用本機 Chrome	`Contract\LocalRendererFactoryInterface`
二進位與 JSON（base64）回應解析	`CloudflareResponseParser`
邊緣遙測（轉譯時間、邊緣節點位置、內容高度）	`CloudflareRenderResult`
來自 R2 儲存桶的自訂字型	`CloudflareRenderPayload`（`r2FontBucket`、`fontFiles`）
API 保護層（金鑰驗證、酬載大小、速率限制）	`ApiProtection`
透過相容 S3 的 API 將 PDF 封存至 R2	`R2ArchiveManager`

每一列都對應到 NextPDF\Cloudflare 命名空間中的一個類別。每一列都是根據該類別的行為與測試進行驗證，而非依據某份規格文件。

它不做的事

它不會執行瀏覽器。執行瀏覽器的是 Worker。
它不會替你部署或設定 Worker。那個產物由你自行負責。
它不會對 PDF 進行簽署。簽署屬於 nextpdf/core 或商業版本的職責。當你需要簽署時，請先進行轉譯，再以引擎對回傳的位元組進行簽署。NextPDF Pro 提供 PAdES B-B 簽署。長期驗證（long-term-validation）設定檔則是 Enterprise 版的能力。
它不會對任何 Cloudflare 平台的容量或限制做出聲明。本文件所敘述的大小與時間限制，僅限於此套件在自身設定中所實施的限制（請參閱 /integrations/cloudflare/configuration/）。

兩套安全政策

這個橋接器承載兩套彼此獨立、互補的政策；把兩者混為一談，是審查時最常見的錯誤。以下逐一說明。

HTML 安全政策（HtmlSecurityPolicyInterface，預設為 NextPDF\Html\DefaultHtmlSecurityPolicy，由 nextpdf/core 提供）：剖析層的內容過濾會在內容抵達 Worker 之前套用。可透過 getHtmlSecurityPolicy() 取得它。
Cloudflare 安全政策（CloudflareSecurityPolicy，靜態）：傳輸層的考量：輸入大小、base64 解壓縮炸彈偵測、封鎖 meta-refresh、強制 HTTPS，以及對 Worker URL 的 SSRF / DNS-rebinding 防禦。

轉譯器本身的文件區塊已敘明這項區分。本頁之所以重述，是因為正式環境的審查人員需要在同一畫面上看到這兩個名稱。

邊緣轉譯模型

單次 render() 呼叫會依照以下可觀察順序執行。這個順序是直接從 CloudflareHtmlRenderer::render() 讀取而來。

檢查設定完整性（workerUrl 與 apiToken 皆非空）。若失敗，橋接器會改用本機轉譯器，或拋出 CloudflareNotAvailableException。
依據已設定的最大大小、base64 URI 上限與 meta-refresh 禁令，對 HTML 進行驗證。
驗證 Worker URL，解析主機並回傳經過審核的 IP 集合。
建構酬載（CloudflareRenderPayload）。
使用時再次檢查，確認主機的 DNS 回應自步驟 3 以來並未變更。
送出 HTTP POST：當存在 IP 集合或 SPKI 釘選集合，且已提供 PSR-17 ResponseFactory 時，會透過已釘選的 cURL 傳輸層送出；否則會透過注入的 PSR-18 用戶端送出。
將回應解析為 CloudflareRenderResult。

除 CloudflareRenderException 以外的任何可拋出例外，都會觸發備援路徑。CloudflareRenderException（來自 Worker 的 HTTP 錯誤或格式錯誤的回應）會原封不動地重新拋出。這代表 Worker 端失敗，而不是可達性失敗，因此不會啟用備援。

另請參閱

/integrations/cloudflare/install/ — 安裝此套件及一個 PSR-18 用戶端。
/integrations/cloudflare/configuration/ — 每個設定欄位，以及經原始碼驗證的預設值。
/integrations/cloudflare/quickstart/ — 一個可執行的初次轉譯。
/integrations/cloudflare/production-usage/ — 備援、遙測、R2 封存、API 保護。
/integrations/cloudflare/security-and-operations/ — 從營運細節說明信任邊界。
/integrations/cloudflare/troubleshooting/ — 對應到例外的失敗模式。
/integrations/cloudflare/boot-and-discovery/ — 橋接器如何接入主機框架。
/integrations/cloudflare/integration/ — 透過 Cloudflare 服務驅動 NextPDF。