最稳定方案是用 Puppeteer 截取完整滚动页面 PNG 再转 PDF：先 page.screenshot({fullPage: true})，再用 img2pdf 转单页 PDF；若直接 page.pdf()，需设大 height 并禁用页眉页脚。
HTML 直接转“长图式 PDF”（即单页、高度自适应、无分页截断的 PDF）不是浏览器原生支持的标准流程，关键在于绕过默认的分页渲染逻辑，用截图方式生成连续图像再转 PDF，或用特定库强制单页输出。
用 puppeteer 截取完整滚动页面并保存为 PDF
这是目前最稳定、可控性最强的方案，适合 Node.js 环境。puppeteer 能真实加载 HTML、执行 JS、等待动态内容，并支持 fullPage: true 截图或直接导出 PDF —— 但注意：PDF 模式默认仍会分页，必须配合 printBackground: true 和 format: 'a4' 等参数调整，而真正“长图式”更推荐先截图再转 PDF。
- 先用
page.screenshot({ fullPage: true, type: 'png' })截取整页 PNG（含滚动区域），生成一张超高分辨率图 - 再用
pdf-lib或命令行工具（如img2pdf）将 PNG 转为单页 PDF - 若坚持用
page.pdf()，需设置height为足够大的像素值（如10000px），并禁用displayHeaderFooter，否则页眉页脚会干扰 - 常见坑：
fullPage: true对含position: fixed的悬浮元素可能截不全；建议截图前用page.evaluate(() => window.scrollTo(0, 0))重置滚动位置
前端用 html2canvas + jsPDF 导出长图 PDF（纯浏览器方案）
适合不能跑服务端、需在用户浏览器里一键导出的场景。核心是先用 html2canvas 把 DOM 渲染成 canvas，再用 jsPDF 将 canvas 转为 PDF —— 但 canvas 高度受限于浏览器内存和最大画布尺寸（通常上限约 32767px），超长页面会白屏或崩溃。
-
html2canvas必须传{ useCORS: true, scrollY: 0, scale: 2 }，否则跨域资源不显示、滚动位置不准、高清图模糊 -
jsPDF添加图片时要用addImage(imgData, 'PNG', 0, 0, width, height)，其中width/height应基于 canvas 实际尺寸计算，别直接用doc.internal.pageSize.getWidth() - 遇到超长页（>2 万 px），可分段截图再拼接 PDF 页面，但要注意元素断层；更稳妥的做法是后端接管截图
- 不支持 CSS
transform、filter、部分 flex 布局，渲染结果和真实页面可能有偏差
Chrome DevTools 协议 + headless Chrome 批量生成（自动化首选）
比 puppeteer 更底层、更轻量，适合集成进 CI/CD 或定时任务。通过发送 DevTools Protocol（CDP）命令控制 headless Chrome，调用 Page.captureScreenshot 并设 format: 'png' + captureBeyondViewport: true，即可拿到整页截图。
立即学习“前端免费学习笔记（深入）”；
- 命令行快速验证：
chrome --headless --disable-gpu --screenshot --window-size=1200,8000 --no-sandbox http://localhost:3000/report.html
，会生成screenshot.png - 注意
--window-size的高度要大于目标页面预估高度，否则截不全；可用--default-background-color=0xffffffff避免透明背景变黑 - 生成的 PNG 再用
convert（ImageMagick）或img2pdf转 PDF：img2pdf screenshot.png -o output.pdf
- 不支持等待 JS 加载完成，需额外加
--dump-dom或配合Runtime.evaluate检查document.readyState === 'complete'
真正难的不是“怎么转”，而是“怎么让 HTML 在截图时保持正确布局和字体渲染”——比如本地字体未加载、rem 单位在高 DPI 下错乱、CSS containment 导致子树被裁剪。这些细节不会报错，但 PDF 一打开就漏内容。建议导出前用 Puppeteer 的 page.emulateMedia('screen') 和 page.addStyleTag 注入重置样式，比依赖浏览器默认行为更可靠。
