html2pdf.js 中 thead 不自动续页因其依赖 html2canvas 截图而非原生打印，需手动配置分页；flex 容器不支持分页属性，应临时改为 block；svg/canvas 需显式设置尺寸并等待绘制完成；动态节点须确保渲染后再导出。
为什么 thead 在 PDF 里不自动续页？
不是所有浏览器渲染引擎都把 thead 当作“可重复表头”来处理——html2pdf.js 底层依赖 html2canvas 截图，而截图时 thead 只是普通 DOM 节点，不会被识别为分页锚点。只有在 Chromium 原生打印（window.print()）或 wkhtmltopdf 这类基于 WebKit 渲染的工具中，thead { display: table-header-group; } 才真正生效。
实操建议：
- 若用
html2pdf.js，必须配合pagebreak.before或 CSS 类手动控制分页位置，不能只靠thead - 若用
wkhtmltopdf，确保thead紧跟在table开始后、且前面没有空行或注释；否则解析器可能跳过该规则 -
thead内含position: sticky或transform会直接破坏续页逻辑，必须移除
flex 容器里子元素被截断的隐蔽原因
flex 布局本身不支持 CSS 分页属性（如 break-inside: avoid），当父容器设为 display: flex，其子项即使加了 page-break-inside: avoid 也大概率失效——因为 flex item 的尺寸由 flexbox 引擎计算，而分页逻辑发生在 layout 阶段之后。
常见错误现象：表格行、卡片列表在 PDF 中被硬生生从中间劈开。
立即学习“前端免费学习笔记（深入）”；
实操建议：
- 导出前临时将父容器改为
display: block，子项用margin-bottom模拟间距，导出完再恢复 - 对关键子项（如
.card）加break-inside: avoid !important，并确保它没被flex-wrap: wrap或align-items: stretch干扰高度计算 - 避免在 flex 容器内嵌套
position: absolute元素——它们脱离文档流后，分页算法完全无法感知其真实高度
svg 和 canvas 在分页时消失或错位
svg 元素默认是内联替换元素，html2canvas 截图时若未显式设置 width/height，或其父容器有 overflow: hidden，就容易被裁切；canvas 更麻烦——它内容不可见，html2canvas 必须等其绘制完成才能截图，但异步绘制（如 ECharts）常在截图后才触发。
实操建议：
- 给
svg加固定尺寸和vertical-align: top，避免基线对齐导致意外留白 - 对
canvas元素，导出前调用其绘图函数并 awaitPromise.resolve()（例如 ECharts 的chart.setOption(...)后接await chart.hideLoading()） - 禁用
html2pdf.js的ignoreElements默认过滤，显式传入ignoreElements: (el) => el.tagName === 'CANVAS' || el.tagName === 'SVG'是错的——应改为false或精准排除无关节点
动态插入的 DOM 节点为何总在 PDF 里“少一页”？
典型场景：Vue/React 组件挂载后通过 ref 插入一个 <div class="pdf-page-break"></div> 用于强制分页，但 html2pdf.js 启动时该节点尚未存在——因为 html2pdf() 调用时机早于框架的 nextTick 或 useEffect 渲染周期。
实操建议：
- 不要依赖“插入节点”来分页，改用
pagebreak.after配置项指向已存在的稳定 DOM 节点（如每个.section的末尾） - 若必须动态生成，用
MutationObserver监听目标容器变化，确认节点插入后再调用html2pdf() - 避免在
mounted/useEffect中立即执行导出，至少加setTimeout(() => {}, 0)或queueMicrotask()让 DOM 更新完成
最易被忽略的一点：所有分页控制都依赖于节点在导出瞬间的 **渲染后高度**，而不是初始 CSS 声明。这意味着 font loading、图片加载、rem/em 单位换算、甚至 scrollbar 出现与否，都会让实际高度偏移几像素——足够让某一行刚好卡在分页临界点上。别信“测好了”，每次导出前都得用 getBoundingClientRect() 实时校验关键节点高度。
