在 dompdf.js 中，任何 PDF 生成任务都从 new DomPDF() 开始。构造函数接收一个配置对象，负责设定整份文档的默认页面尺寸、页边距与渲染精度，这些默认值会作用于后续每一次 addPage 调用。许多开发者习惯直接 new DomPDF() 不带任何参数，遇到导出尺寸不对、边距不统一、文字发虚时才回头翻文档，白白浪费调试时间。本文深入讲解构造函数三个核心选项 format、margin、scale 的类型、取值范围与相互影响，说明它们与 addPage 每页参数之间的优先级关系，并给出发票、报表、证书等真实场景的最佳实践。读完你就能用最少的配置组合覆盖多页文档的复杂需求，从第一步就把参数配对，避免后期反复返工，也无需再为每次导出临时调整配置而头痛。同时给出可直接套用的默认配置参考与验证方法，让初始化不再靠猜。
new DomPDF(options) 接收一个可选的配置对象，返回一个代表整份 PDF 文档的实例。所有配置遵循同一个原则：构造阶段设定全局默认值，addPage 阶段可以按页覆盖。这意味着你只需在构造函数里写一次 format、margin、scale，后续所有页面都会自动继承，无需每页重复传参，代码更简洁，也避免了各页参数不一致导致的排版漂移。
如果完全不传参数，DomPDF 会使用内置默认配置。对绝大多数通用场景（普通 A4 文档、默认边距、标准缩放），默认值已经够用；但当你要输出印刷级内容或固定尺寸的票据时，就必须显式配置。建议在项目里维护一个统一的初始化函数，把常用配置收敛到一个地方，团队协作时一目了然，后续调整参数也只需改一处。
配置对象中的每一项都是可选的，可以只设置需要的字段。比如只设置 format 不设置 margin，页边距会回落到默认值；只设置 margin 不设置 format，页面尺寸沿用默认 A4。理解这种按字段独立生效的机制，配置起来才不会有遗漏，也不会被莫名其妙的输出尺寸困扰，排查问题能更快定位是哪一项没配。
还有一个值得注意的细节：构造函数可以随时被再次调用，不同的实例之间互不影响。如果你的页面同时存在多个导出入口，比如报表页与发票页，各自创建独立的 DomPDF 实例即可，配置互不干扰，导出结果也不会串数据。这种按场景隔离实例的做法，比维护一个全局单例更安全，也更容易排查问题。
format 指定 PDF 页面尺寸，最常见的是 A4，也支持 A3、A5、Letter、Legal 等常用规格。选择依据是文档用途：合同、发票、报表一般用 A4；海报、折页用 A3；小票、标签用 A5。尺寸选错会直接影响分页结果，务必在需求阶段就确认最终打印或阅读的载体，避免上线后才发现规格不对，返工成本很高。
除了标准规格，某些业务场景需要特殊尺寸，比如名片 90×54mm、证书的异形变体。这类需求可以通过模板内的 @page 规则配合固定宽度容器来实现：给页面容器设置与目标尺寸匹配的宽度（A4 在 96 DPI 下约 794px），让 dompdf.js 按内容实际宽度分页，输出效果与设计稿一致，版式还原度比纯坐标计算高得多。
还有一个容易忽略的点：format 决定的是页面逻辑尺寸，实际输出还会受到 scale 与 margin 的影响。三者共同决定内容区域的宽高，改动任何一个都可能让原本一页的内容溢到第二页。调试分页问题时，先固定 format 与 margin，再单独调 scale，能更快定位是哪一项引起的溢出，而不是三个参数一起改越改越乱。
另外建议把 format 与模板的容器宽度一起验证：先创建一个测试实例，用目标尺寸导出包含满宽表格的样例内容，检查内容是否溢出。这个验证只需要一次，却能提前暴露尺寸与模板不匹配的问题，避免上线后在真实数据上翻车，也方便团队成员复用同一套验证脚本。
import { DomPDF } from 'dompdf.js';
// 构造函数统一设定全局默认值
const pdf = new DomPDF({
format: 'A4', // 页面尺寸：A4
margin: '20mm', // 页边距：四边统一 20mm
scale: 2, // 渲染缩放：2 倍，文字更锐利
});
// 后续所有页面自动继承上述配置
pdf.addPage(invoiceHTML, { format: 'A4' });
pdf.addPage(attachmentHTML); // 未传参数时使用构造默认值
pdf.save('invoice-2026-08.pdf');margin 控制页面四周的空白区域，支持 '20mm'、'15mm' 这类带单位的字符串写法。页边距的意义不只是美观：内容区域等于页面尺寸减去四边边距，边距越大，单页能容纳的内容越少，分页点也会相应提前，长文档的总页数会明显增加，这一点在做报价单、合同时要提前评估。
设计时建议把边距当作版式的一部分：标题与正文的行宽、表格的列宽都应以内容区域为基准，而不是页面全宽。很多排版问题——表格溢出、文字被截断——根源都是内容宽度超过了实际内容区域。先在浏览器里量出内容区域宽度再写模板，能避免大多数布局事故，节省大量调试时间。
还要注意页眉页脚与边距的配合：开启页眉页脚后，它们通常绘制在边距区域，页边距过小会导致页眉与正文视觉上粘连，打印时甚至被裁剪。给页眉页脚预留足够的边距空间，文档会显得更专业。常见做法是上下边距略大于左右边距，比如上下 25mm、左右 20mm，观感更均衡，也更耐看。
还有一个容易被忽略的点：margin 的写法要统一。项目里混用 '20mm' 与 '2cm' 虽然数值等价，但可读性差，也容易在复制粘贴时写错单位。建议在团队规范里统一使用毫米单位，配置集中在常量里管理，代码审查时一眼就能发现异常值，沟通成本也随之下降。
scale 控制渲染缩放倍数，直接影响输出清晰度与渲染耗时。默认值在绝大多数场景已足够；当文档需要高精度打印或包含大量小字号文字时，适当提高 scale 能让文字边缘更锐利、曲线更平滑，印刷效果更接近设计稿，证书、海报这类对外展示的文档尤其值得调高。
但 scale 不是越大越好：倍数越高，WASM 渲染需要处理的数据量越大，耗时与内存占用同步上升。对长文档而言，过高的 scale 可能让导出时间成倍增加，用户体验明显变差。建议从默认值开始，用真实内容测试，只有在肉眼可感知的清晰度差异时才提高倍数，并同步验证导出耗时是否可接受。
scale 与 format、margin 共同决定内容区域，三者应作为一个整体调参。先固定 format 与 margin 保证版式稳定，再用 scale 微调清晰度；不要同时调整多个参数，否则出现分页异常时难以判断是哪一项引起的，定位问题会非常费时，调参过程也缺少可复现性。
在调试清晰度问题时，建议同时检查生成文件的体积：scale 提高后文件变大是正常的，但如果在清晰度没有明显变化时文件却膨胀了，说明模板里有超大图片或重复资源，优先优化它们，而不是继续提高 scale，效果更好、收益也更高。
dompdf.js 的参数体系分两层：构造函数设置全局默认值，addPage 接收每页专属配置。优先级遵循就近原则——addPage 传入的参数覆盖构造默认值，未传入的字段继续使用构造值。这种设计让多页文档可以混合使用不同页面配置，封面、正文、附件各自独立，互不干扰。
实践建议：把稳定不变的配置（全局边距、缩放）放在构造函数，把每页变化的配置（页面尺寸、特殊边距）放在 addPage。职责清晰之后，模板代码的可读性会明显提升，后续维护也只需改动对应层级，不需要通读整个导出逻辑，团队接手成本大幅下降。
最后提醒一点：构造函数配置一旦确定，整个实例生命周期内不会自动变化。如果业务上有多种文档规格（报价单 A4、名片 90×54mm），建议按规格创建独立实例，而不是在同一个实例上反复覆盖参数，避免状态混乱，也便于单独测试与复用，出问题时互不影响。
最后补充一个实践案例：一个典型的发票导出需求，构造函数配置 A4 与 20mm 边距，addPage 只传内容，save 时用发票编号拼文件名。整个导出逻辑不超过十行，却覆盖了模板、配置、命名三个层面，这正是参数分层设计的价值所在，也是可以复制到任何文档类型上的通用模式。
下面的按钮用 dompdf.js 在浏览器端实时生成 PDF，无需后端：
这是由 dompdf.js 渲染的示例 PDF 内容。