html2canvas不是“所见即所得”工具，它解析DOM和CSS后重绘，不处理transform动画、iframe、跨域图片等原生行为；文字样式丢失因不继承浏览器默认样式表，仅读取显式CSS规则；跨域图片报错源于Canvas污染机制，需设useCORS:true并确保服务返回Access-Control-Allow-Origin:*；截图模糊因未适配设备像素比，应显式配置scale、width、height；Vue/React中需用nextTick或useLayoutEffect确保DOM就绪。
html2canvas 不是“所见即所得”的截图工具，它靠解析 DOM 和 CSS 后重绘，很多浏览器原生行为（比如 transform 动画、iframe、跨域图片）它不处理或处理不一致。直接调用 html2canvas(element) 很可能得到空白、模糊、样式错乱或跨域报错的图——问题不在代码写错，而在没绕过它的底层限制。
为什么截图后文字/标题样式丢失？
常见现象：页面里有 <h2>雷猴</h2>，但生成的 Canvas 里字体变小、加粗失效、颜色不对。
- 根本原因是
html2canvas不继承浏览器默认样式表（user agent stylesheet），只读取你显式声明的 CSS 规则 - 没写
font-weight、margin、color的标签，它就按空值渲染 -
em/rem在重绘时计算不稳定，容易失真
解决方法：
- 给所有要截图的语义标签（
h1–h6、p、li、span等）显式声明基础样式，例如：h2 { font-size: 18px; font-weight: bold; margin: 12px 0; color: #222; } - 避免依赖
em/rem，统一用px单位 - 确保样式在调用
html2canvas()前已加载完成——不要靠@import或异步 CSS
跨域图片显示为空或报 Failed to execute 'toDataURL' 错误
错误信息典型为：Failed to execute 'toDataURL' on 'HTMLCanvasElement': Tainted canvases may not be exported.
立即学习“前端免费学习笔记（深入）”；
- 这是 Canvas 污染（tainting）机制触发的，本质是浏览器阻止从不同源读取像素数据
-
allowTaint: true是危险选项，开启后toDataURL()必然失败，基本不可用 - 本地开发用
file://协议会直接触发该限制，必须起本地服务器（如vite preview或http-server）
正确做法：
Html To Pdf
下载
使用 Puppeteer + Chrome 将 HTML 渲染为中文 PDF，自动处理图表等待、Tab 展开、动画、测高、白边消除、防分页，适用于看板、报表、网页和交互图表转 PDF。
- 优先设
useCORS: true，并确认图片服务返回了Access-Control-Allow-Origin: * - 若服务不支持 CORS，必须配
proxy参数走后端代理，例如：proxy: '/api/cors-proxy' - 不要在生产环境依赖
file://协议调试
截图模糊、尺寸异常或背景发灰
默认输出常偏小、模糊，尤其在高分屏（Retina）设备上。
-
scale默认值是window.devicePixelRatio，但这个值在某些浏览器或 iframe 中不可靠 - 不设
width/height会导致 html2canvas 自动计算区域，易受滚动、缩放影响 -
backgroundColor: '#ffffff'是默认值，但导出 PNG 时若设为透明（null）又未指定格式，可能发灰
建议配置：
- 固定
scale: 2（兼顾清晰度与内存占用），印刷场景可试scale: 3 - 显式传入
width和height，例如：width: element.offsetWidth, height: element.offsetHeight - 需要透明背景时设
backgroundColor: null，并确保后续用canvas.toDataURL('image/png')导出 - 禁用
logging: true——它打印大量无用 DOM 解析日志，拖慢性能
Vue/React 中截图为空或只截到初始状态
典型错误：组件挂载后立即调用 html2canvas(ref.value)，结果 canvas 是空的或内容未更新。
- 原因在于 DOM 还没真正渲染完成，或者异步数据还没填充进模板
- 在 Vue 中，
onMounted不等于“DOM 已就绪”，特别是含v-if、transition或动态 class 的节点 - React 中
useEffect也存在类似时机问题，尤其配合 Suspense 或懒加载
可靠做法：
- Vue：用
nextTick()包裹调用，或监听 ref 元素的offsetHeight变化 - React：用
useLayoutEffect+ref.current?.offsetHeight判断渲染完成 - 通用兜底：加
setTimeout(..., 100)（慎用，仅临时调试） - 对动态内容，用
onclone回调预处理克隆后的 DOM，例如：onclone: (doc) => doc.querySelector('.loading').remove()
最易被忽略的一点：html2canvas 对 CSS 伪元素（::before/::after）、filter、backdrop-filter 和部分 Flex/Grid 子项的渲染支持有限，遇到这类样式异常，优先检查是否属于已知不支持特性，而不是反复调参。
