NextPDF Gotenberg 總覽

快速概覽

NextPDF Gotenberg 是 NextPDF 與外部 Gotenberg 服務之間的輕量橋接器。它會接收 NextPDF 無法原生轉譯的 Office 文件，透過 HTTP 將該文件傳送至 Gotenberg 實例，接收回傳的 PDF，再把 PDF 交給你的應用程式。之後，NextPDF 的其餘功能會接手後續處理。

這個套件小巧且職責明確。它不內嵌轉譯器、不啟動 LibreOffice，也不執行瀏覽器。每次轉換都是對某個 Gotenberg 端點發出的單一 multipart HTTP 請求。該端點由你自行營運，並透過設定讓橋接器指向它。

當你有 .docx、.xlsx、.pptx、.odt、.ods 或 .odp 來源檔案，並希望在 NextPDF 流程中將它們轉成 PDF 時，請使用這個橋接器。PDF 產生之後的一切——簽署、PDF/A 轉換、加上浮水印、合併——都透過 NextPDF 本身或 nextpdf/premium 套件執行。

橋接器所依賴的項目

橋接器有一項不是 PHP 套件的執行階段相依：一個執行中的 Gotenberg 服務，且橋接器必須能透過 HTTPS 連線到它。

橋接器不會安裝、管理或監督 Gotenberg。Gotenberg 由你自行部署（上游專案會發布容器映像檔），且其可用性、容量與網路曝露都由你負責。
橋接器會與 Gotenberg 的 LibreOffice 轉換路由溝通。請求 URL 的組成形式為 <apiUrl>/forms/libreoffice/convert，其中 <apiUrl> 是你設定的基底 URL。這個路由決定橋接器所支援的格式集。
健康檢查探測會對 <apiUrl>/health 發出 HTTP HEAD 請求，並將任何低於 500 的狀態碼視為可用。

轉換是在你自行營運的服務中進行，因此橋接器的行為取決於你執行的 Gotenberg 版本。橋接器會送出固定的 multipart 請求結構；路由路徑（/forms/libreoffice/convert）與健康檢查路徑（/health）是它對 Gotenberg 端唯一假定的契約。部署基準請參閱 /integrations/gotenberg/install/，服務強化方法請參閱 /integrations/gotenberg/security-and-operations/。

支援的文件格式

橋接器只會轉換其 OfficeFormat 型別中列舉的格式。每種格式都依副檔名偵測（不分大小寫，且容許開頭的點號）。接著，每種格式會以固定的 MIME 類型傳送至 Gotenberg：

格式	副檔名	傳送至 Gotenberg 的 MIME 類型
Word（OOXML）	`docx`	`application/vnd.openxmlformats-officedocument.wordprocessingml.document`
Excel（OOXML）	`xlsx`	`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`
PowerPoint（OOXML）	`pptx`	`application/vnd.openxmlformats-officedocument.presentationml.presentation`
OpenDocument Text	`odt`	`application/vnd.oasis.opendocument.text`
OpenDocument Spreadsheet	`ods`	`application/vnd.oasis.opendocument.spreadsheet`
OpenDocument Presentation	`odp`	`application/vnd.oasis.opendocument.presentation`

這份清單就是完整清單。不在此集合內的副檔名會在發出任何網路請求之前先引發 ValueError，因此橋接器絕不會嘗試它無法描述的轉換。橋接器並未宣稱支援「任何 Office 檔案」或「所有文件格式」。它支援上述六種格式，因為那正是程式碼辨識的六種，也是測試套件驗證的六種。

舊版二進位格式（.doc、.xls、.ppt）、RTF 格式（.rtf）、純文字、CSV 以及影像格式，並不屬於橋接器辨識的集合。Gotenberg 自身的 LibreOffice 路由可能接受更廣泛的輸入範圍。橋接器刻意把自身限制在列舉的集合內，讓格式偵測、MIME 類型與結果中繼資料能始終保持一致且可驗證。

一次轉換的流程

一次轉換是單一、線性的流程。在任何位元組離開處理程序之前，每個步驟都會先進行驗證：

檢查設定。空白的 API URL 會以轉換例外立即失敗。
驗證 API URL：必須使用 HTTPS，且主機會被解析並篩查，確保它無法指向私有或保留位址。已解析的位址集合會被擷取下來，供稍後釘選之用。
讀取輸入（對於檔案轉換，會先將路徑正規化以阻擋路徑穿越），並將副檔名對映到一個 OfficeFormat。
依設定的上限檢查位元組長度，並篩查檔名是否含有路徑穿越序列、斜線、空位元組與控制字元。
發出請求前，會立即重新檢查位址集合，以消除驗證與連線之間的時間落差。
建立一個 multipart/form-data 主體並以 POST 送至 LibreOffice 路由；若有設定 bearer token，則一併附上。
解析回應：狀態碼必須是 200，Content-Type 必須包含 application/pdf，且主體必須以 %PDF 簽章開頭。唯有如此才會回傳結果。

步驟 1–7 中的任何失敗都會引發具型別的例外，而不會回傳部分或未經檢查的結果。確切的例外及其觸發條件列於 /integrations/gotenberg/troubleshooting/.

你會取回什麼

成功的轉換會回傳一個結果物件。該物件包含原始 PDF 位元組、已轉換的來源格式，以及一個選用的轉譯時間量測值；並提供一項有效性檢查（一個以 %PDF 開頭的非空主體）以及一個位元組大小存取器。這些位元組是一般 PDF 串流，因此你可以將它們寫入磁碟、串流給用戶端，或送入一個 NextPDF 文件做進一步處理。

橋接器止步之處

橋接器負責轉換與驗證。它不會：

對輸出進行簽署、加密、線性化或 PDF/A 轉換。這些屬於後續處理範疇，由 NextPDF 核心或 nextpdf/premium 處理。
重試失敗的請求、排入佇列或快取結果。這些是應用程式層級的考量。/integrations/gotenberg/production-usage/ 說明應在橋接器周圍的哪些位置加入這些機制。
管理 Gotenberg 服務的生命週期。部署與營運內容涵蓋於 /integrations/gotenberg/security-and-operations/.

版本與後續處理

OSS 核心可以直接寫出轉換後的 PDF。若你需要簽署轉換後的文件、產生 PDF/A 封存設定檔或套用浮水印，nextpdf/premium 套件會在此基礎上加入這些功能。橋接器本身與版本無關：它只負責產生 PDF。你對那份 PDF 所做的事，決定了你是否需要商業版本。

Pro 版本中可用的 PAdES 基準只有 B-B。長期驗證設定檔（B-T、B-LT、B-LTA）並不屬於 Pro 版本，且本橋接器也未提供它們。請勿因本套件存在而推斷其具備時間戳記或 LTV 能力。

另請參閱

/integrations/gotenberg/install/ — 安裝套件並建立一個 Gotenberg 基準環境。
/integrations/gotenberg/configuration/ — 每個設定選項、其型別、預設值與用途。
/integrations/gotenberg/quickstart/ — 一個可執行的首次轉換。
/integrations/gotenberg/production-usage/ — 將橋接器接入真實應用程式。
/integrations/gotenberg/troubleshooting/ — 例外目錄以及各項含義。
/integrations/gotenberg/security-and-operations/ — 安全模型，以及如何安全營運所依賴的服務。
/integrations/gotenberg/boot-and-discovery/ — 宿主框架如何探索橋接器並完成接線。
/integrations/gotenberg/integration/ — 透過該服務驅動 NextPDF 轉譯。