PDF 图片嵌入指南：dompdf.js 图文混排完整教程

一份正式的 PDF 几乎离不开图片：公司 Logo、电子签章、二维码、产品实拍图、网页截图。图片嵌得好不好，直接决定文档的专业程度与文件大小。很多方案把整页截成位图，图片清晰了文字却糊了，整份文档沦为一张大图；dompdf.js 采用矢量渲染，图片按原始分辨率嵌入、文字保持矢量，图文混排既清晰又小巧。本文讲解在 dompdf.js 中嵌入图片的多种方式——网络地址、相对路径、base64 Data URL、Blob URL——以及质量优化技巧与常见问题排查，帮你一次搞定图文并茂的 PDF，不再为图片不显示、文件过大而反复调试。

图片在 PDF 中的典型场景

商务文档离不开图片：报价单要放产品图，合同要放电子签章，宣传册要放实拍照片，发票要放税务二维码，简历要放头像。图片让文档可信、专业、有辨识度，也是品牌形象在纸面媒介上的延伸，缺失图片的文档往往显得单薄。

图片的使用方式分两类：一类是装饰性的（Logo、背景纹理），一类是信息性的（二维码、签章、截图）。信息性图片必须清晰可扫、可辨，对渲染质量的要求更高，容不得半点模糊，因为模糊的二维码无法识别、模糊的签章影响法律效力。

dompdf.js 对两类图片都支持良好：图片按原始分辨率嵌入 PDF，不会二次压缩；同时文字保持矢量，整页缩放或打印时图片和文字都不会糊，也不会出现错位或失真的情况，图文混排的效果稳定可靠。

还有一个常见误区：把 Logo 放大到超出原始分辨率。位图图片放大必然发虚，这是数学规律；设计资源不足时宁可用小图居中放置，也不要拉伸到模糊，否则整份文档的质感都会下降，专业度大打折扣。

dompdf.js 支持哪些图片来源

最直接的方式是使用 <img> 标签，src 可以是网络地址、相对路径、base64 Data URL 或 Blob URL。网络图片注意跨域与加载时序，base64 则天然内联、不依赖网络，离线场景也能稳定渲染，是最保险的图片传递方式。

代码中动态生成的图片（Canvas 截图、二维码、图表库输出）可以先转成 base64 或 Blob，再拼进 HTML 字符串或赋给 DOM 节点的 img.src，dompdf.js 会在渲染时自动读取并嵌入，流程闭环无需额外处理。

CSS 背景图同样支持，适合装饰性图片；但信息性图片建议用 <img> 标签，语义清晰、尺寸可控，方便控制对齐与留白，也便于在表格和 flex 布局中稳定排布，避免背景图在不同页面尺寸下漂移。

图片加载时序也值得注意：如果 addPage 时图片还没加载完，渲染结果可能缺图。稳妥做法是先用 Promise 等待所有图片完成加载，比如调用 Image 对象的 decode 方法，再触发导出，避免偶发缺图问题。

如果你的页面结构复杂，也可以不拼字符串，直接把真实 DOM 节点传给 addPage：把图片元素挂在页面上、确保加载完成，再传入节点即可，dompdf.js 会读取节点内的所有图片资源，两种方式效果一致。

代码示例：Logo + 二维码 + 商品图

import { DomPDF } from 'dompdf.js';

// 二维码可以由 qrcode 库生成 base64 字符串
const qrDataUrl = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...';

const catalogHTML = `
  <div style="text-align:center">
    <img src="/logo.png" width="120" alt="公司 Logo">
    <h2>2026 秋季产品目录</h2>
  </div>
  <table style="width:100%;border-collapse:collapse">
    <tr>
      <td style="border:1px solid #ccc;padding:12px;text-align:center">
        <img src="https://example.com/product-a.jpg" width="160">
        <p>无线降噪耳机</p>
      </td>
      <td style="border:1px solid #ccc;padding:12px;text-align:center">
        <img src="${qrDataUrl}" width="120">
        <p>扫码查看详情</p>
      </td>
    </tr>
  </table>`;

const pdf = new DomPDF();
pdf.addPage(catalogHTML, { format: 'A4' });
pdf.save('catalog.pdf');

图片质量与文件体积优化

矢量渲染意味着图片按原始像素嵌入，过大的图片会让 PDF 文件膨胀。建议图片宽度不超过 2000px，导出的 PNG/JPG 控制在几百 KB 以内，既能保证 A4 打印清晰度，又不拖累文件体积与渲染速度，是图文文档的基本素养。

照片类图片推荐 JPG 或 WebP，Logo、图标、二维码这类边缘锐利的图形用 PNG 更合适；透明背景 PNG 用于签章和 Logo 可避免白底穿帮，在彩色背景上也能自然融合，观感明显更专业。

同一张图片在多页重复使用（比如每页都有 Logo）时，建议只引用同一 URL，dompdf.js 会复用资源，避免重复编码造成文件体积随页数翻倍，这是批量文档最容易忽略的优化点，值得养成习惯。

导出前的最后一道检查是预览：在浏览器里打开生成的 PDF 放大到 200%，逐一核对二维码是否可扫、Logo 边缘是否锐利、照片色彩是否正常。预览比任何配置都更能发现实际问题，建议纳入上线流程。

批量场景还有一个隐性收益：图片资源统一托管后，PDF 体积和渲染时间都更容易预测，线上问题排查也更简单。建议在导出前做一次资源清单核对，缺图、超限都能提前发现，而不是等用户反馈。

常见问题：图片不显示怎么办

Q: 网络图片加载不出来？A: 检查跨域（CORS）配置与图片服务器可用性，最稳妥的做法是把图片转成 base64 内联后再传给 dompdf.js，渲染不再依赖网络，稳定性大幅提升。

Q: base64 图片太大导致页面卡顿？A: 先在 Canvas 上按目标尺寸缩放再导出 base64，能显著降低字符串长度与渲染耗时，同时保留足够清晰度，兼顾性能与观感。

Q: 图片在浏览器里正常但 PDF 里错位？A: 检查图片父容器的宽度约束，给 <img> 显式设置 width 或 max-width，避免依赖浏览器默认的自动布局导致排版漂移，固定尺寸最可靠。

Q: 动图（GIF）只显示第一帧？A: 这是 PDF 格式本身的限制，PDF 不支持动画，请提前把动图替换为静态帧图片，避免交付后才发现内容缺失，影响文档完整性。

Q: 图片颜色在 PDF 里偏色？A: 多为色彩配置文件差异，导出前把图片统一转为 sRGB 并内嵌色彩配置，大部分偏色问题都能消除，色差敏感的场景尤其要检查。

与位图方案对比

html2pdf.js 把整页截成一张位图，页面里的图片也被一并栅格化，放大后图片与文字一起发虚，文件体积还随页面尺寸急剧膨胀，图片本身的清晰度优势荡然无存，损失是双重的。

jsPDF 手动方案虽然可以 addImage 嵌入图片，但布局坐标全靠手写，图文混排、文字环绕都要自己计算，开发成本极高，后期调整版式更是灾难，维护成本长期居高不下。

dompdf.js 直接解析 DOM 渲染，图片与文字分层处理：图片保持原分辨率、文字保持矢量，既清晰又小巧，图文混排的复杂度由引擎接管，开发者只需写好 HTML，其余交给库来处理，投入产出比最高。

如果项目已经在用位图方案且短期内无法切换，折中做法是把页面里的关键信息性图片单独以高分辨率嵌入，至少保证二维码、签章这类核心元素清晰可用，把损失降到最低。

另外建议在导出入口做一次图片健康检查：统计页面里引用的图片数量、加载状态与总体积，超限时给出提示，让用户主动优化素材，而不是导出后才发现文件过大或图片缺失，体验会好很多。

团队协作时建议在组件库里沉淀一份图片规范：什么场景用 PNG、什么场景用 JPG、最大尺寸是多少、透明背景如何处理。规范落地后，图片相关的返工率会明显下降，PDF 输出质量也更稳定，值得投入时间整理。