HTML2PDF.js 在 iOS 设备上生成空白 PDF 的解决方案

html2pdf.js 在 ios 设备上常输出空白 pdf，根本原因是其将整个 html 渲染到单个 canvas 上，而 ios 对 canvas 尺寸有严格限制；推荐改用 html3pdf（html2pdf 的增强分支），它按页分 canvas 渲染，彻底规避该限制。

在使用 html2pdf.js 进行前端 PDF 导出时，开发者常遇到一个棘手问题：在 iOS Safari 或 Webview 中调用 .save() 后生成的 PDF 内容为空白页，而在 macOS、Windows 或 Android 设备上却能正常显示。这并非代码逻辑错误，而是底层渲染机制与平台限制共同导致的已知缺陷。

问题根源：Canvas 尺寸限制

html2pdf.js（v2.x）采用“整页渲染至单个 ”的策略：先将目标 DOM 元素通过 html2canvas 截图，再将该 canvas 传入 jsPDF 生成 PDF。然而，iOS 系统对单个 Canvas 的最大尺寸有硬性限制（通常约 4096×4096 像素，具体因 iOS 版本和设备内存而异）。当页面内容过长（如 A3 纵向 + 大量表格/图表）时，渲染所需 Canvas 超出上限，html2canvas 返回空画布 → 最终 PDF 为空白。

✅ 验证方式：在 iOS Safari 中打开控制台（需 macOS + Safari 开发者工具连接真机），检查 html2canvas 返回的 canvas 元素宽高是否为 0 或明显异常。

推荐解决方案：迁移到 html3pdf

html3pdf 是 html2pdf.js 的活跃维护分支，核心改进包括：

• ✅ 分页独立 Canvas 渲染：每页内容单独创建 canvas，彻底绕过单 Canvas 尺寸限制；
• ✅ 完全兼容 html2pdf.js API，迁移成本极低；
• ✅ 修复了 iOS 下字体回退、CSS 变量支持、pagebreak 触发时机等数十个平台相关 bug。

迁移步骤（仅需两步）

1. 安装依赖

   npm uninstall html2pdf.js
   npm install html3pdf

2. 更新调用代码（几乎无需修改）

   import html3pdf from 'html3pdf'; // 或通过 script 标签引入 dist/html3pdf.min.js
   
   function downloadPDF() {
     apply_print_style();
   
     const element = document.getElementById('LIMS_ROI_calculator');
     const opt = {
       margin: 0.2,
       filename: 'LIMS_ROI_calculator.pdf',
       pagebreak: { 
         mode: ['avoid-all', 'css', 'legacy'], 
         before: '#pa
   ge_02' 
       },
       jsPDF: { 
         unit: 'in', 
         format: 'a3', 
         orientation: 'portrait' 
       }
     };
   
     // ✅ 仅需将 html2pdf() 替换为 html3pdf()
     html3pdf().set(opt).from(element).save();
   }

补充建议与注意事项

• 性能权衡：html3pdf 因逐页渲染，在超长文档（如 50+ 页）中可能比 html2pdf.js 略慢，但稳定性显著提升；
• 打印样式优化：确保 apply_print_style() 正确隐藏非打印元素（如按钮、导航栏），并设置 @media print 规则，避免 iOS 下因样式未生效导致布局错乱；
• 降级兜底：可检测用户代理，对 iOS 设备强制启用 html3pdf，其他平台保留原方案；
• 替代方案参考：若项目对体积敏感，也可考虑服务端 PDF 生成（如 Puppeteer），但会增加后端依赖与网络延迟。

通过切换至 html3pdf，你不仅能解决 iOS 空白 PDF 问题，还能获得更可靠的跨平台导出体验——这是当前社区验证最高效、侵入性最小的实践方案。