通过 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 }