浏览器打印（Ctrl+P）是导出HTML仪表盘为PDF最快、最可靠、样式还原度最高的方式，前提是页面完全加载且可控；自动化场景需用wkhtmltopdf或puppeteer，但各有渲染时机、字体、跨域和分页限制。
直接用浏览器打印（Ctrl+P）导出 HTML 仪表盘为 PDF，是最快、最可靠、样式还原度最高的方式——前提是页面已完全加载、且你控制得了用户操作场景；若需自动化、批量、或服务端触发，则必须换方案，比如 wkhtmltopdf 或 puppeteer，但它们各自有渲染时机、字体、跨域和分页等硬性限制。
为什么浏览器打印是最优起点
绝大多数 HTML 仪表盘（尤其是 ECharts、Ant Design Charts、Vue/React 渲染的动态看板）在 Chrome/Firefox/Safari 中按 Ctrl+P → 选“保存为 PDF”就能生成结构完整、分页合理、带背景色和边框的 PDF。关键不是“能不能”，而是“要不要绕开它”。
- 必须等所有异步图表渲染完成后再触发打印，否则导出为空白或缺图——可在页面加一个“导出就绪”状态提示，或监听
chartInstance.isFinished()类似钩子 - 务必在 CSS 中添加
@media print规则：隐藏按钮、侧边栏、加载动画等非内容元素；对position: fixed或transform元素慎用display: none，易导致布局错位 - 勾选
Background graphics，否则background-color和border全部丢失；Margin 设为None，避免表格/图表被截断
wkhtmltopdf 导出动态仪表盘的关键参数
wkhtmltopdf 是服务端自动化导出的主力工具，但它不会等 JS 执行完就收工——仪表盘里 ECharts 的 canvas、Ajax 加载的数据表格，都得靠显式延迟来兜底。
- 必须加
--javascript-delay 3000（单位毫秒），数值要大于图表初始化+数据加载总耗时；太短导出空白，太长拖慢流水线 - 禁用智能分页：
--no-stop-slow-scripts --enable-javascript，否则复杂图表可能被中断渲染 - 中文支持依赖系统字体：Linux 需提前安装
fonts-wqy-zenhei或挂载中文字体文件，并通过--outline-depth 4 --page-size A4控制基础排版 - 不支持跨域 iframe 内容——如果仪表盘嵌了第三方监控面板（如 Grafana iframe），这部分会留白，得提前替换成同源代理或截图后合成
puppeteer 渲染仪表盘 PDF 的避坑点
当 wkhtmltopdf 遇到 WebKit 不兼容的 CSS（如某些 clip-path 或 backdrop-filter），或需要精确控制打印时机时，puppeteer 是更贴近真实浏览器的行为模拟器，但它不是“一键调用就完事”。
立即学习“前端免费学习笔记（深入）”；
- 不能直接用
page.pdf()调用——必须先await page.waitForFunction('window.chartInstances && window.chartInstances.length > 0')等待全局图表实例就绪 - 默认启用
headless: true，但部分 ECharts 版本在无头模式下 canvas 渲染异常；可临时改用headless: "new"或加--disable-gpu --no-sandbox启动参数 - 导出前建议执行
await page.emulateMediaType('screen')，避免某些库（如 Chart.js）因检测到 print 媒体而跳过渲染 - PDF 文件体积容易偏大：含 5 张高清 ECharts 的 A4 报告可达 8–12 MB，需在
page.pdf()中传入{ printBackground: true, format: 'A4' }并关闭不必要的margin
html2canvas + jsPDF 方案只适合简单快照
这套前端组合本质是“截图→贴图→存 PDF”，文字不可选、搜索、复制，且对现代布局支持极差——它不该出现在仪表盘导出主路径里，仅作为兜底或调试手段。
-
html2canvas捕获不到iframe、video、canvas（除非已绘制完成且未跨域）、position: fixed元素常错位 - 中文必须手动注入字体：用
jsPDF.setFont()前，得先addFont()加载 .ttf 文件，否则全是方块 - 长仪表盘会被强行压缩进单页：没有自动分页逻辑，需按高度切 DOM、循环
addPage()，代码量陡增且易出错 - scale 设为
2是底线，否则 PDF 文字模糊；但 scale 过高又会触发内存溢出，Chrome 下超 3000px 高度大概率崩溃
真正卡住人的从来不是“怎么导出”，而是“导出那一刻，页面到底有没有准备好”——ECharts 实例是否挂载、异步数据是否 resolve、第三方脚本是否执行完毕。这些状态无法靠工具自动感知，必须在导出前做显式判断，否则所有参数和配置都是空中楼阁。
