html2pdf.js 在 ios 设备上常因 canvas 尺寸限制导致导出 pdf 为空白，根本原因是其将整个 html 渲染到单个 canvas 中，而 ios 的 canvas 最大尺寸（通常约 4096×4096 像素）易被长页面突破。
在使用 html2pdf.js 进行前端 PDF 导出时，开发者常遇到一个典型兼容性问题：在 iOS Safari 或 WKWebView（如 iOS 微信、钉钉内嵌浏览器）中调用 .save() 后生成的 PDF 文件内容全为空白，但相同代码在 macOS Safari、Chrome 或 Android 设备上运行正常。这并非代码逻辑错误，而是底层渲染机制与平台限制共同作用的结果。
问题根源：Canvas 尺寸硬限制
html2pdf.js（基于 jsPDF + html2canvas）采用“整页渲染 → 转 canvas → 分页转 PDF”的流程。关键在于：它默认将整个目标 DOM 元素一次性绘制到单个 <canvas> 上。而 iOS 系统对单个 canvas 的宽高乘积（即像素总数）有严格限制（实测通常 ≤ 16,777,216 像素，如 4096×4096），一旦页面内容过高（例如 A3 纵向 + 大量表格/图表），canvas 创建失败或绘制区域被截断，最终 PDF 无内容。
你提供的配置中：
jsPDF: { unit: 'in', format: 'a3', orientation: 'portrait' }A3 纵向（11.69 × 16.54 in）按默认 96 DPI 计算，canvas 高度已超 1580px；若内容实际高度达数万像素（常见于 ROI 计算器类长表单），极易触发该限制。
立即学习“前端免费学习笔记（深入）”；
解决方案：迁移到 html3pdf
推荐使用 html3pdf —— 它是 html2pdf.js 的积极维护分支，核心改进正是分页独立渲染：
✅ 每一页单独创建 canvas，彻底规避单 canvas 尺寸上限；
✅ 兼容 iOS 13+ 所有主流 WebView；
✅ 保留原 html2pdf 的 API 接口，迁移成本极低。
迁移示例（仅需替换库与导入）：
# 卸载旧版，安装新版 npm uninstall html2pdf.js npm install html3pdf
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: '#page_02'
},
jsPDF: {
unit: 'in',
format: 'a3',
orientation: 'portrait'
}
};
// API 完全兼容，直接替换即可
html3pdf().set(opt).from(element).save();
}补充建议与注意事项
- 性能权衡：html3pdf 因逐页渲染，长文档导出速度略慢于 html2pdf.js，但稳定性显著提升，iOS 场景下应优先保障可用性；
- CSS 兼容性：确保 @media print 或打印专用样式（如 apply_print_style()）在 iOS 中生效，避免 display: none 或 transform 等属性干扰渲染；
- 调试技巧：在 iOS Safari 开发者工具中检查 html2canvas 是否报错（如 Failed to execute 'toDataURL' on 'HTMLCanvasElement'），可快速确认是否为 canvas 限制问题；
- 兜底方案：对超长动态内容，可考虑服务端 PDF 生成（如 Puppeteer），但会增加后端依赖和延迟。
综上，面对 iOS 空白 PDF 问题，无需复杂 hack（如手动分段、缩放降质），升级至 html3pdf 是当前最简洁、可靠且向后兼容的工程化解法。
