HTML转图片不显示的常见原因及解决方法

将HTML代码转换为图片时出现空白、模糊、样式丢失或内容缺失等问题，往往并非工具本身故障，而是由DOM未完全加载、跨域资源静默失败、CSS高级属性不兼容、字体未预加载、设备像素比未适配等隐蔽因素导致；真正棘手的不是报错，而是那些悄无声息跳过的环节——比如图片跨域留白、WebFont未加载就截图、JS动态内容未就绪便执行渲染。掌握针对性排查策略：确保目标元素可见且挂载完成、统一资源同源或正确配置CORS、内联关键字体、显式等待真实渲染就绪（而非仅网络空闲）、按设备像素比缩放画布，并善用DOM状态日志替代盲目调参，才能稳定生成高质量截图。

为什么 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，写进