使用 NextPDF Connect 嵌入影像

概覽

透過 NextPDF Connect 將影像嵌入 PDF。來源可以是伺服器可讀取的檔案路徑，也可以是內嵌的 base64 data URI。使用的工具為 create_pdf、add_image 與 output_pdf，三者皆屬 Core。影像會繪製為 image XObject，並由 Do 運算子描繪（ISO 32000-2 §8.9）。

安裝

composer require nextpdf/server

綁定傳輸層。支援的點陣影像格式為 PNG、JPEG 與 GIF。

概念總覽

add_image 接受 source，並依固定順序解析：

Data URI — 以 data: 開頭的字串。NextPDF 會解析 MIME 類型，將 base64 內容解碼成暫存檔案，嵌入該檔案後再移除暫存檔案。
原始 base64 — 較長的 base64 字串會被解碼並視為 PNG 處理。
檔案路徑 — 其餘任何內容都會被視為檔案系統路徑，且 伺服器程序 必須具備讀取權限。

影像位置以 x/y 指定，單位為使用者單位（預設為公釐）。只傳入 width 時，高度會自動計算，以維持長寬比。同時傳入 width 與 height 時，影像會縮放至這些精確尺寸。嵌入的物件是描繪至頁面內容中的外部物件（ISO 32000-2 §8.8）。

API 介面

工具	角色	風險層級
`create_pdf`	開啟工作階段	安全
`add_image`	從路徑或 data URI 嵌入影像	謹慎
`output_pdf`	算繪並回傳 PDF	需核准/審查（base64）

工具目錄是正式工具清單的依據。你可使用的工具取決於已安裝的版本層級。

程式碼範例 — 快速上手

create_pdf（A4 直向、標題）→ document_id。
add_image，將 source 設為絕對路徑，並指定 x、y、width。
add_image，將 source 設為 data:image/png;base64,... URI，並明確指定 width 與 height。
output_pdf → base64。

程式碼範例 — 正式環境

對於由主機在記憶體中產生的影像（例如圖表算繪或螢幕擷圖），請使用 data URI。對於已存在於伺服器上的資源，請使用檔案路徑。請一律使用絕對路徑。相對路徑會相對於 伺服器的 工作目錄解析，而該目錄通常不是主機的工作目錄。繼續之前，請確認 add_image 回應已回報影像位於預期頁面。

邊界情況與陷阱

找不到路徑。 不存在的檔案路徑會回傳找不到影像的錯誤。
不支援的格式。 SVG、BMP 與 WebP 會被拒絕。請先轉換影像格式。
格式錯誤的 base64/data URI。 內容有誤，或缺少逗號分隔符號的 data URI，都會回傳解碼錯誤。
影像過大。 大於頁面的影像會在邊緣被裁切，而非被拒絕。請依扣除頁邊距後的頁面尺寸計算 width/height（A4 直向為 210×297 mm）。

效能

輸出大小會隨影像內容而異。兩張小型影像通常為 10–50 KB。影像嵌入的預算比純文字更寬鬆。此設定檔為 structural。

安全注意事項

檔案路徑模式會以伺服器程序的權限，從伺服器檔案系統讀取資料。請限制主機可傳入的路徑。請勿讓不受信任的呼叫端將 source 指向伺服器上的任意檔案。Base64 模式會以內嵌方式攜帶位元組，因此可避免暴露伺服器路徑。

符合性

陳述	規範	條款	reference_id
影像是由 `Do` 描繪的 image XObject。	ISO 32000-2	§8.9
影像是描繪至頁面內容中的外部物件。	ISO 32000-2	§8.8

商業情境

不適用 — 所有工具皆為 Core。

傳輸層可用性

傳輸層	可用	備註
MCP (stdio)	是	大型 base64 內容會讓 stdio 框架膨脹。
REST	是	對於大型資源，建議優先使用 multipart 或伺服器路徑。
gRPC	是	單向（unary）；訊息大小限制適用於內嵌 base64。

HITL 風險層級

create_pdf 為安全，add_image 為謹慎，而 output_pdf 為需核准 — 在 base64 模式下降級為審查。路徑模式的讀取發生在伺服器端，並未個別設下管控閘門，因此請在政策層加以限制（HITL 風險層級）。

確認閘門 JSON 封套

以下為 Base64 輸出：

{ "allowed": true }