dompdf.js 图片格式支持详解：PNG、JPG、SVG、WebP 怎么选

把网页转成 PDF，图片是渲染成败的关键一环：格式选错，要么体积爆炸、要么细节丢失、要么出现不兼容的乱码。dompdf.js 的 Rust+WASM 内核在浏览器里直接解析图片并写入矢量 PDF，原生支持 PNG、JPG、SVG 与 WebP 四种主流格式，覆盖透明背景、照片压缩、矢量图形与现代压缩格式等全部常见场景。不过每种格式都有各自的适用边界：PNG 适合截图与图标、JPG 适合照片、SVG 适合可缩放图形、WebP 在体积上优势明显。本文逐一拆解四种格式在 PDF 渲染中的优缺点、体积与质量对比以及代码接入方式，并给出按场景选择的决策清单，让开发者一次搞懂图片格式选型，生成又快又清晰的 PDF。

四种格式在 PDF 渲染中的角色

PDF 是矢量文档，但其中的图片可以以多种方式存在：无损位图、有损位图、矢量图形。dompdf.js 在渲染时会按图片自身的编码格式解码并嵌入输出，因此源图格式直接决定 PDF 里该区域的质量、体积与可缩放性。选对格式，文件又小又清晰；选错格式，要么模糊、要么臃肿，还可能在兼容性上埋雷。

理解格式差异之前，先记住一条主线：照片看压缩率，界面元素看清晰度与透明，图形看矢量性。JPG 用有损压缩换体积，适合照片；PNG 无损且带透明通道，适合截图、图标与 Logo；SVG 是矢量描述，缩放不失真；WebP 是 Google 推出的现代格式，同等质量下体积通常最小。

dompdf.js 对这四种格式的支持都是开箱即用的，模板里放 img 标签或 CSS background-image 即可，不需要额外配置或转换。唯一需要注意的是：不同格式的源文件质量参差不齐，先在浏览器里确认图片能正常显示，再交给 PDF 生成，避免把错误一路带到导出环节。

需要提醒的是，格式支持并不等于格式质量：同一个 PNG 文件，导出的清晰度取决于源图本身的分辨率与压缩参数，渲染管线只是忠实地还原。保证源图质量、统一图片处理规范，比纠结格式差异更能稳定提升 PDF 的最终观感，格式只是载体，内容质量才是根本。

PNG：无损与透明背景的正确用法

PNG 采用无损压缩，适合保存需要像素级还原的内容：UI 截图、图表、图标、带透明背景的 Logo。在 PDF 里，PNG 的透明通道会被正确保留，白色页面上的透明区域不会被错误填充，这是 JPG 做不到的。设计稿里的切图大多以 PNG 交付，直接使用即可，无需额外转换。

PNG 的代价是体积：照片级的 PNG 可能比 JPG 大一个数量级。另外 PNG 有 8 位与 24 位之分，调色板 PNG 更小但颜色受限，导出截图时优先选择 24 位以保真，同时避免把照片存成 PNG，那是最典型的体积浪费，会让 PDF 文件无谓膨胀。

下面的示例把一个带透明背景的 PNG 图标放进模板，通过 addPage 交给 dompdf.js，生成的 PDF 中图标保持透明、边缘干净。图标资源用相对路径即可，模板与页面同源时不存在跨域问题，渲染结果与浏览器显示完全一致，代码简洁直观。

import { DomPDF } from 'dompdf.js';

const html = `
  <style>
    body { font-family: 'Source Han Sans SC', sans-serif; }
    .logo { width: 120px; height: 40px; }
  </style>
  <h2>订单确认单</h2>
  <img class="logo" src="images/logo.png" alt="公司 Logo">
  <p>本文件由 dompdf.js 在浏览器中生成。</p>`;

const pdf = new DomPDF({ format: 'A4', margin: '20mm', scale: 2 });
pdf.addPage(html, { format: 'A4' });
pdf.save('order-png-demo.pdf');

JPG：照片与有损压缩的取舍

JPG 用有损压缩换取小体积，是照片、扫描件、渐变背景的首选。同等视觉质量下 JPG 通常比 PNG 小 5 到 10 倍，对包含大量图片的 PDF 而言，体积差异直接决定文件大小与生成耗时。dompdf.js 直接解码 JPG 嵌入，压缩参数由源图决定，导出前可用 canvas 重新压缩控制体积。

JPG 的软肋是没有透明通道，压缩还会产生可见伪影。文字、线条、截图这类边缘锐利的内容用 JPG 会明显发糊，放大后伪影更明显。因此规则很简单：照片用 JPG，界面元素用 PNG；若必须用 JPG 承载文字区域，提高导出 scale 或降低压缩比可缓解，但本质上仍是换体积换质量。

把 JPG 交给 PDF 之前建议做一次预处理：通过 canvas 的 toDataURL('image/jpeg', 0.85) 统一压缩比，既控制体积又避免浏览器与 PDF 端解码差异。压缩比 0.8 到 0.9 之间视觉损失极小，适合大多数场景，压缩后的图片再放入模板，生成更快、文件更小。

SVG：矢量图形与代码示例

SVG 是矢量格式，由路径、形状与文本描述图形，任何尺寸下都清晰锐利，是图表、地图、Logo 的理想选择。dompdf.js 支持直接渲染 SVG，模板中既可以引用 svg 文件，也可以把 SVG 字符串转为 data URL 内联使用，后者让模板完全自包含，不依赖外部资源加载，离线也能稳定生成。

SVG 在 PDF 中的优势是缩放无损：同一份图表既能用于小尺寸预览，也能用于大幅面打印，不会出现位图的马赛克。代价是复杂 SVG 的解析与渲染开销高于位图，几百个节点的图表没问题，上万个节点的大型 SVG 建议拆分为多个小图，避免拖慢布局阶段。

引用 SVG 时注意两件事：一是确认 SVG 内部没有引用外部图片或字体，否则解析时可能失败；二是复杂的滤镜、混合模式等高级特性在 PDF 管线中可能被简化，交付前用真实文档验证一遍渲染效果，再决定是否直接用原图，避免成品与预期不符。

import { DomPDF } from 'dompdf.js';

const chartSvg = `
  <svg xmlns="http://www.w3.org/2000/svg" width="480" height="240" viewBox="0 0 480 240">
    <rect x="0" y="0" width="480" height="240" fill="#f5f7fa"/>
    <rect x="40" y="120" width="80" height="90" fill="#4c6ef5"/>
    <rect x="140" y="80" width="80" height="130" fill="#4c6ef5"/>
    <rect x="240" y="60" width="80" height="150" fill="#4c6ef5"/>
    <rect x="340" y="100" width="80" height="110" fill="#4c6ef5"/>
  </svg>`;

const html = `
  <style>body { font-family: 'Source Han Sans SC', sans-serif; }</style>
  <h2>季度销售对比</h2>
  <img src="data:image/svg+xml;base64,${btoa(chartSvg)}" style='width:100%'>`;

const pdf = new DomPDF({ format: 'A4', margin: '20mm' });
pdf.addPage(html, { format: 'A4' });
pdf.save('chart-svg-demo.pdf');

WebP：现代格式的体积优势

WebP 同时支持有损与无损压缩，还支持透明通道，同等画质下体积通常比 JPG 小 25% 到 35%、比 PNG 小一半以上，是图片体积优化的第一选择。dompdf.js 原生支持 WebP 解码，模板中直接引用 webp 文件即可，无需转换，生成结果与浏览器渲染一致，视觉质量不打折扣。

使用 WebP 的注意点是兼容性：绝大多数现代浏览器都支持，但个别老旧环境与工具链可能无法解码，如果目标用户或下游处理系统较旧，建议提供 PNG 或 JPG 回退。最稳妥的做法是用 picture 标签按支持情况切换源，PDF 渲染时按实际可用资源取用，兼容与体积兼得。

体积优化的收益在批量场景最明显：几十张图片的文档，全部换用 WebP 后文件可能缩小近半，上传、下载、打印都更快。团队可以建立统一的图片管线，上传时自动转 WebP 并保留原图，PDF 生成直接消费 WebP，一条链路同时优化网页与导出两个场景，成本低、收益长期有效。

WebP 的解码性能也值得肯定：同等像素量下，它的解码速度与 JPG 相当，不会因为压缩率更高而拖慢 PDF 生成；实测批量文档换用 WebP 后，生成耗时与文件体积同步下降，收益可以直接量化。把 WebP 纳入图片管线升级目标，是最具性价比的体积优化动作之一，值得优先落地。

格式选择决策清单与最佳实践

综合以上对比，可以归纳出一张决策清单：照片与扫描件选 JPG；截图、图标、Logo 与透明素材选 PNG；图表、地图、徽章等需要缩放的内容选 SVG；追求最小体积且环境支持时选 WebP。按这张清单选型，绝大多数文档都能在体积与质量之间拿到最优解，不用每次纠结。

最佳实践还包含几条通用规则：所有图片在进入模板前先做尺寸归一化，超过目标显示尺寸两倍以上的图先降采样；统一图片托管路径并开启缓存，避免重复下载；生成前用字体就绪与图片解码完成信号做双重门控，确保资源就绪后再渲染，输出稳定可复现。

最后，用真实数据说话：在正式接入前跑一轮基准，记录不同格式组合下的 PDF 体积与生成耗时，选择最符合业务场景的组合。dompdf.js 的 API 稳定，格式切换只改模板不改代码，优化成本低、收益长期有效，值得每个项目认真做一次，从此告别图片格式选择的反复试错。