HTML转PDF时z-index失效的根本原因是PDF为静态矢量文档，不支持浏览器动态层叠上下文；wkhtmltopdf按DOM顺序绘制，需将置顶元素移至文档末尾；Playwright/Puppeteer导出PDF会跳过合成层，应清理父级触发新层叠上下文的样式并临时提升元素；最可靠方案是弃用z-index，改用position:absolute手动定位并确保DOM顺序与视觉顺序一致。
HTML 转 PDF 时层级（z-index）失效的根本原因
HTML 中的 z-index 在转 PDF 时几乎总是失效，不是工具用错了，而是底层逻辑不同：PDF 是静态、分层渲染的矢量文档，而浏览器的层叠上下文（stacking context）依赖动态布局和合成层。主流转换工具（如 wkhtmltopdf、pdfkit、playwright）都不真正支持 CSS 层叠上下文的完整还原，尤其当涉及 position: absolute + z-index + 父级 transform 或 opacity 时，层级顺序常被扁平化为 HTML 的 DOM 顺序。
wkhtmltopdf 中 z-index 失效的典型修复手法
wkhtmltopdf 基于 Qt WebKit，对现代 CSS 支持有限。它按 DOM 流顺序绘制元素，忽略 z-index 计算结果。可行的绕过方式是控制 DOM 顺序本身：
- 把需要「置顶」的元素（如弹窗、遮罩）移到 HTML 文档末尾，靠 DOM 顺序覆盖前面内容
- 避免在父容器上使用触发新层叠上下文的属性（如
opacity: 0.99、transform: translateZ(0)），否则子元素z-index将仅在该局部上下文中生效，无法跨容器比较 - 慎用
position: fixed——wkhtmltopdf对其支持不稳定，常导致位置偏移或消失；改用position: absolute并配合top/left显式定位
/* 错误：z-index 不起作用 */
.modal { position: absolute; z-index: 1000; }
.header { position: relative; z-index: 1; }
/ 正确：靠 DOM 顺序 + 显式定位 /
...
...
Playwright / Puppeteer 转 PDF 时的层级控制要点
playwright 和 puppeteer 基于 Chromium，理论上支持完整 CSS 层叠，但 PDF 导出（page.pdf()）会跳过合成层，仍按 DOM 顺序+部分样式推导绘制。关键对策：
- 确保目标元素所在层叠上下文「干净」：父级不要有
will-change、filter、transform（除非必要），否则 Chromium 可能提前 flatten - 强制重绘前等待：用
await page.waitForTimeout(100)或await page.evaluate(() => document.fonts.ready)，避免字体加载未完成导致布局错位 - 导出前临时提升元素：通过
page.evaluate把关键元素appendChild到document.body末尾，再调用pdf()
await page.evaluate(() => {
const modal = document.querySelector('.modal');
if (modal) document.body.appendChild(modal);
});
await page.pdf({ path: 'output.pdf' });真正可靠的替代方案：放弃 z-index，改用绝对定位叠加
如果业务要求精确叠放（比如水印盖在表格上、图标浮在图表右上角），最稳的方式是彻底放弃依赖 z-index，改为手动计算并固定所有元素的 position: absolute 坐标，让它们在同一个层叠上下文中（即共享同一个 position: relative 父容器），且 DOM 顺序与视觉顺序一致：
立即学习“前端免费学习笔记（深入）”；
- 给最外层容器设
position: relative - 所有子元素用
position: absolute+top/left显式定位，不设z-index - DOM 顺序按从底到顶排列：背景 → 内容 → 装饰图标 → 水印 → 遮罩
- 测试时打开 PDF 查看器的「对象检查」（如 Adobe Acrobat 的「Edit Object」），确认每个元素是否作为独立图层存在
复杂交互型 HTML（含 Vue/React 动态组件）转 PDF，建议服务端预渲染为纯静态 HTML 后再转，否则客户端 JS 渲染状态不可控，层级问题会叠加时机问题。
