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

html2pdf.js 在 ios 设备上常输出空白 pdf，根本原因是其将整个 html 内容渲染到单个 canvas 元素中，而 ios 对 canvas 尺寸有严格限制（通常约 4096×4096 像素），超出即失效。

问题根源：canvas 尺寸限制

html2pdf.js（基于 jsPDF + html2canvas）采用“全页一次性渲染”策略：先将目标 dom 元素完整绘制到一个 上，再将其转为 PDF 页面。然而，iOS webkit（safari 及所有 webview）对单个 Canvas 的最大尺寸施加了硬性限制——宽度或高度超过 4096 像素时，Canvas 渲染会静默失败，导致后续 toDataURL() 返回空图像，最终 PDF 内容为空白。

你的代码中使用了 format: ‘a3’（约 11.7×16.5 英寸 ≈ 297×420 mm），若内容较长或含高分辨率图表/表格，实际渲染像素极易突破限制（尤其在 scale: 2 默认高清屏适配下）。该问题虽在 android 和桌面端也可能出现，但在 iOS 上最为普遍且难以规避。

✅ 推荐方案：迁移到 html3pdf

html3pdf 是 html2pdf.js 的积极维护分支，核心改进之一正是分页独立渲染：每一页都创建独立 Canvas，绕过单 Canvas 尺寸上限，彻底解决长文档空白问题。

迁移步骤（简洁版）

1. 安装依赖

   立即学习“前端免费学习笔记（深入）”；

   npm install html3pdf

2. 替换调用逻辑（保持 API 高度兼容）

   import { html3pdf } from 'html3pdf';  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: '#page_02'      },     jsPDF: {        unit: 'in',        format: 'a3',        orientation: 'portrait'      }   };    // ✅ 替换为 html3pdf —— 无需修改配置结构   html3pdf().set(opt).from(element).save(); }

? 提示：html3pdf 完全兼容 html2pdf.js 的选项语法和链式调用风格，迁移成本极低，且已修复包括 iOS Canvas 限制、CSS Grid 渲染异常、字体嵌入失败等数十个关键 issue。

⚠️ 补充建议与注意事项

• 避免强制放大内容：检查 apply_print_style() 中是否设置了 transform: scale(1.5) 或过大 font-size，这些会显著增加渲染像素；
• 启用分页控制：在长内容中显式插入

  ，辅助 html3pdf 更精准分页；

• 性能权衡：因每页单独渲染，html3pdf 生成超长 PDF（如 50+ 页）时耗时略高，但稳定性远优于 html2pdf.js；
• Polyfill 兼容性：确保项目已引入 core-js 或类似 polyfill，以支持 iOS 12–13 的 promise 和 fetch。

总结

iOS 下 html2pdf.js 输出空白 PDF 并非代码错误，而是底层 Canvas 机制与平台限制冲突所致。与其尝试降尺度、裁剪内容或 hack Canvas，不如直接升级至更健壮的替代方案——html3pdf。它不仅解决了核心限制问题，还持续跟进现代 CSS 特性与移动端兼容性，是面向生产环境的推荐选择。