html2canvas渲染空白或部分截图的主因是目标元素未加载完、含跨域资源或被隐藏；需确保dom挂载可见、图片同源或开启cors、避免高级css属性，并等待资源加载完成后再调用。
为什么 html2canvas 渲染空白或只截到部分？
最常见原因是目标元素未完全加载、含跨域资源（如图片/CSS字体）、或被 display: none / visibility: hidden 隐藏——html2canvas 不会等待异步资源加载完成，也不渲染不可见区域。
- 确保目标容器已挂载到 DOM 且可见（检查
offsetParent是否为NULL） - 所有图片必须同源，或服务端开启
access-Control-Allow-Origin；否则会静默失败，截图留白 - CSS 中的
transform、Filter、mask等高级属性可能被忽略或错位，优先用基础布局 - 避免在截图前调用
html2canvas，等img.onload或promise.all([...])完成后再执行
用 puppeteer 截图时页面没渲染完就保存了
puppeteer 默认不等页面“视觉空闲”，尤其含动态加载内容（如 React/Vue 组件、懒加载图片）时，page.screenshot() 可能截到白屏或骨架屏。
- 别只依赖
page.goto(url, { waitUntil: 'networkidle0' })，它只等网络请求，不等 js 渲染完成 - 改用
page.waitForFunction检测真实就绪状态，例如：page.waitForFunction(() => document.querySelector('#app')?.offsetHeight > 0) - 对单页应用，可加短延时（
await page.waitForTimeout(500)），但更稳妥的是监听关键 DOM 节点出现 - 启用
fullPage: true时注意内存占用，长页面建议分段截图再拼接
CSS 样式丢失或字体不显示
本地字体、WebFont（如 Google Fonts）、或内联 @font-face 在截图中常失效——html2canvas 不解析远程字体文件，puppeteer 若未预加载也会 fallback 到系统默认字体。
- 把 WebFont 改成 base64 内联：下载
.woff2文件并转为 data URL，写进<style></style>中的@font-face - 避免使用
font-display: swap，改为block或直接移除，强制等待字体加载 -
html2canvas对rem/em单位支持不稳定，优先用px或vh/vw - 截图前手动触发重排：
element.offsetHeight（读取 layout 属性）可确保样式已计算
导出图片模糊或分辨率低
默认按设备像素比（devicePixelRatio）1x 截图，高清屏上会模糊；html2canvas 和 puppeteer 都需显式放大 canvas 或设置 viewport。
立即学习“前端免费学习笔记（深入）”；
-
html2canvas加参数：{ scale: window.devicePixelRatio || 2 }，同时设width/height为实际尺寸 × scale -
puppeteer启动时传defaultViewport: { width: 1920, height: 1080, deviceScaleFactor: 2 } - 导出 PNG 前检查 canvas 的
toDataURL('image/png', 1.0)第二个参数是否被误设为0.8导致压缩失真 - 若用
node-canvas合成，注意其createCanvas(w, h)的单位是物理像素，别和 CSS 像素混淆
真正卡住人的往往不是 API 调用本身，而是那些没报错、却悄悄跳过的环节：字体加载失败不抛异常，跨域图片静默降级，CSS 动画未结束就截图。多打几次 console.log 查 DOM 状态，比反复调参更省时间。