企业官网建设流程全解析

如果你还在用html2canvas + jsPDF给网页截图生成 PDF，dompdf.js是一个值得立刻了解的替代方案：它是一个纯前端的HTML 转 PDF 引擎，一行代码即可导出可选、可搜索的矢量 PDF，零后端、零运行时依赖，官方基准中 500 页文档约 2 秒完成，长文档可扩到上万像素页。更省心的是，它内置了一套 Legacy API 兼容层——本文带你对照官方 docs/migration-compat.md（中文版本：docs/migration-compat.zh-CN.md），把旧代码"三步无感升级"到新引擎。

为什么值得迁移：告别"截图式 PDF"

先花 30 秒了解新旧两套方案的核心区别，你会明白这次升级为什么值得：

一句话总结：旧方案"把网页拍照"，新方案"把网页重排"。对需要中文嵌入、页眉页脚、水印、表单加密这类需求的场景，dompdf.js 在功能面上也是全面超集（见 README.md 的 Features 一节）。

Legacy API 兼容清单：升级前先看这张表

dompdf.js 的架构已从html2canvas + jsPDF迁移到DOM 快照 + Worker + WASM。为了让旧项目"换引擎不换代码"，官方把公开 API 分成三个等级，这是你升级时的核心参照：

✅ 第一档：已对齐，行为可用，直接用

以下 API 在当前分支已经具备真实行为，旧代码可以原样运行：

• dompdf(root, options) -> Promise<Blob>主入口
• fontConfig/iconFont/langFontConfig字体体系
• encryption加密、pagination分页、compress压缩
• pageConfig对象形式与pageConfig(pageNum, totalPages)函数形式
• excludePage/excludePages、pageBreak、divisionDisable属性
• backgroundColor、putOnlyUsedFonts、onProgress

⚠️ 第二档：兼容签名，调用不报错但会输出 warning

这些参数仍会被接受（保证旧代码升级时不直接抛错），但新引擎暂不提供旧版等价行为，运行时会打印 warning：

onJspdfReady、onJspdfFinish、foreignObjectRendering、allowTaint、proxy、imageTimeout、logging、cache、windowWidth/windowHeight/scrollX/scrollY、x/y/width/height/scale、canvas、removeContainer、onclone、pdfFileName、floatPrecision、orientation

💡 实用技巧：升级后打开控制台，凡是出现 warning 的选项，就是下一轮要清理的清单。

🔧 第三档：必须显式迁移的用法

以下几类用法与旧架构耦合较深，官方建议显式改造：

• 在onJspdfReady里直接操作 livejsPDF实例
• 在onJspdfFinish里做最终 PDF 修改
• 依赖 html2canvasclone 阶段钩子（如onclone）的自定义逻辑
• 依赖旧版栅格化流程的proxy/canvas定制链路

官方推荐升级路径：5 步平滑切换

官方给出的升级路线（docs/migration-compat.zh-CN.md "建议升级路径"一节）是典型的"先上车后补票"策略：

1. 先升级版本，保留所有旧参数——因为第二档选项只 warning 不报错，业务不中断；
2. 观察运行时 warning，圈出哪些参数目前只是"兼容签名"；
3. 替换 jsPDF 定制逻辑：把对 jsPDF 实例的二次加工，迁移到对导出的Blob/Uint8Array做前后处理（新引擎只给你结果字节流，不再暴露活实例）；
4. 进度反馈统一切到onProgress，可拿到 DOM 采集、总页数、当前渲染页等阶段信息；
5. 字体与页眉页脚：多语言文本优先用fontConfig/langFontConfig，常见页眉页脚用对象形式pageConfig。

改造示例 1：废弃 jsPDF 钩子，改为 Blob 后处理

// 旧代码（新引擎中 onJspdfReady 只是兼容签名，不再生效） const pdf = await dompdf(element, { onJspdfReady: (jsPdf) => { /* 直接操作 jsPDF 实例 */ }, }); // 新写法：拿到 Blob / 字节流后自行后处理 const blob = await dompdf(element, { format: 'a4', pagination: true }); // 需要二次加工时，用 renderToBytes 拿 Uint8Array

改造示例 2：进度条换到 onProgress

onProgress是新的正式导出回调，按阶段上报collecting→countingPages→rendering→done：

await dompdf(element, { pagination: true, onProgress(p) { // p.stage: 'collecting' | 'countingPages' | 'rendering' | 'done' console.log(p.stage, p.currentPage, p.totalPages); }, });

零踩坑清单：这些"看起来能跑"的坑要主动排

• orientation不会自动换横竖版：它目前只是兼容签名。要横向 A4，请显式传[842.25, 595.5]或用pageWidthPt/pageHeightPt覆盖页面尺寸。
• 中文变方框/空白：新引擎不会自动嵌入浏览器字体。请自行加载 TTF 字节，通过fontConfig.fontBytes注册，并保证 CSSfont-family与fontFamily一致；多语言混排可用langFontConfig按 Unicode 区间回退。
• 跨域图片丢失：html2canvas 时代的proxy、allowTaint、imageTimeout在新引擎中不提供原版行为。正确做法是useCORS: true+ 图片服务器返回 CORS 响应头，前端参数无法绕过服务端策略。
• 导出前等一等：先await document.fonts.ready，并等所有<img>加载完成再调用导出，避免内容残缺。
• 文件太大：开启compress: true（DEFLATE 压缩），控制图片分辨率与jpegQuality，字体只注册文档真正用到的字重。

关键资料导航

升级只需一行依赖替换加一轮 warning 清理——对照本文的三档兼容清单，你的 html2canvas + jsPDF 老项目今天就能无痛切到 dompdf.js 的矢量 PDF 新流水线。