企业官网建设流程全解析

dompdf.js 是一款纯前端的浏览器生成PDF工具：在浏览器里直接读取已排版好的 HTML 内容，生成文字可选中、可搜索的矢量PDF，无需后端服务器、不依赖 jsPDF 或截图方案。典型测试中它约 2 秒即可导出 500 页文档，极限规模可扩展到上万页。本教程面向新手，带你用npm 和 CDN 两种方式完成安装，并用不到 3 行代码生成第一份 PDF。

为什么选择 dompdf.js 做前端PDF生成？

很多项目导出 PDF 依赖后端服务或"截图拼图"方案，而 dompdf.js 走的是另一条路线，核心优势如下：

它的能力清单相当完整（详见 README_CN.md）：

• 📄 支持 A/B/C 系列、Letter、Legal、Tabloid 等纸张，也可自定义尺寸
• 🧮 页眉页脚、页码占位符、逐页配置
• 🔒 文字水印、图片水印、PDF 加密与权限控制
• 🈶 中文字体嵌入（TTF 子集化），解决中文空白问题
• 📋 表单导出、超链接注释、DEFLATE 压缩

安装 dompdf.js：npm 与 CDN 双方式

方式一：npm 安装（适合工程化项目）

在终端执行一条命令即可，包要求 Node.js 18+：

npm install dompdf.js

安装完成后，导入方式如下（入口定义见 src/index.ts）：

import dompdf from 'dompdf.js'; import { downloadPDF } from 'dompdf.js';

方式二：CDN 引入（适合快速上手）

在 HTML 中加一行<script>，API 会自动挂载到全局dompdf变量上：

<script src="https://cdn.jsdelivr.net/npm/dompdf.js@latest/dist/dompdf.min.js"></script>

💡 两种方式功能完全一致，CDN 方式连构建步骤都省了，非常适合做 Demo 或原型验证。

3 行代码下载 PDF：npm 版快速开始

假设页面上有一个#capture元素，用 downloadPDF 导出并触发浏览器下载，核心代码只有 3 行：

import { downloadPDF } from 'dompdf.js'; const element = document.querySelector<HTMLElement>('#capture'); await downloadPDF(element, { format: 'a4', pagination: true, compress: true }, 'report.pdf');

三个选项各司其职：

• format: 'a4'：指定 A4 纸张（完整尺寸表见 page_sizes.md）
• pagination: true：启用多页分页，否则输出的是单页长画布
• compress: true：启用 DEFLATE 压缩，减小 PDF 体积

想自己控制预览？用 Blob 方式

默认导出函数返回Promise<Blob>，可以先在浏览器里预览再下载：

import dompdf from 'dompdf.js'; const blob = await dompdf(element, { format: 'a4', pagination: true, backgroundColor: '#ffffff', }); const url = URL.createObjectURL(blob); window.open(url, '_blank'); setTimeout(() => URL.revokeObjectURL(url), 30_000); // 预览后再释放

此外还有 renderToBytes（返回Uint8Array原始字节，方便上传接口）和 inspect（诊断节点数、图片数、页数），完整类型定义位于 src/snapshot.ts。

CDN 版实践：做一个"一键导出"按钮

不搭构建环境也能跑。下面是一个完整可用的 HTML 片段，点击按钮即导出#capture区域：

<button id="export">导出 PDF</button> <section id="capture">需要导出的内容</section> <script src="https://cdn.jsdelivr.net/npm/dompdf.js@latest/dist/dompdf.min.js"></script> <script> document.querySelector('#export').addEventListener('click', async () => { await dompdf.downloadPDF( document.querySelector('#capture'), { format: 'a4', pagination: true }, 'example.pdf' ); }); </script>

仓库内也提供了浏览器示例页面，例如 examples-main/demo.html，本地执行npm run serve（静态服务端口 8080）后即可打开体验。

常用导出选项速查

以下是最常用的几个选项（完整表格见 README.md 的 Export Options 一节）：

加分项：页脚页码 + 水印 + 压缩

await dompdf(element, { pagination: true, compress: true, pageConfig: { footer: { content: '第 ${currentPage} 页 / 共 ${totalPages} 页', height: 40, contentPosition: 'center', }, }, watermark: { text: '内部资料', angle: -35, color: 'rgba(0, 0, 0, 0.12)', }, });

分页时想让某块内容强制从新页开始，加一个pageBreak属性即可；想让某块尽量不被拆开，用divisionDisable。

它是怎么工作的？（30 秒看懂原理）

dompdf.js 并不重新实现浏览器排版，而是"借"浏览器的计算结果：

1. 主线程遍历目标元素，读取浏览器已算好的布局、样式、文本、图片与表单状态
2. TypeScript 把结果编码成紧凑的二进制快照
3. 快照传给 Web Worker，由 Rust/WASM 完成分页、字体子集化、绘制与 PDF 对象生成
4. 主线程拿到 PDF 字节，返回Blob/Uint8Array或直接下载

这条流水线正是它"主线程不卡 + 文本仍是矢量"的关键，Worker 逻辑见 src/worker.ts，WASM 引擎见 wasm/src/paginate.rs。

新手常见问题 FAQ

Q：中文导出后是空白或方块？浏览器字体不会自动嵌入 PDF。需通过fontConfig.fontBytes注册包含所需字符的 TTF 字体，并确保元素 CSS 的font-family与注册的fontFamily一致。

Q：分页效果和浏览器里看到的不一样？导出容器的 CSS 宽度应尽量贴近目标页面内容宽度（A4 约 794px @ 96 DPI，再减去边距），并等待字体、图片加载完成后再导出。

Q：跨域图片缺失？设置useCORS: true，同时图片服务器必须返回Access-Control-Allow-Origin响应头——前端选项无法绕过服务器策略。

Q：从 html2canvas + jsPDF 迁移过来兼容吗？旧版选项（如allowTaint、proxy、scale）只保留签名、不再提供原有行为。完整迁移路径见 docs/migration-compat.zh-CN.md。

Q：能在 Node.js 里直接调用吗？不能。导出 API 依赖 DOM，SSR 项目（Next.js、Nuxt）请在客户端调用。

小结

dompdf.js 用 TypeScript + Rust/WASM 的组合，把"浏览器生成PDF"这件事做到了零后端、零运行时依赖，而导出 API 简单到只需 3 行代码。现在就挑一个页面试试，把"导出 PDF"按钮加进你的项目吧！