html-to-image是当前最可控、可编程、适配现代项目的方式；其toPng()/toJpeg()失败主因包括跨域图片未设crossOrigin、字体未加载、fixed/transform节点干扰，需确保DOM就绪、正确配置pixelRatio与quality，并避开file://协议限制。
直接用 html-to-image 是当前最可控、可编程、适配现代项目的方式；浏览器原生截图或在线工具只适合临时一用，没法集成进业务逻辑里。
toPng() / toJpeg() 调用失败常见原因
不是所有 DOM 都能被正常捕获——比如跨域图片、未加载完成的字体、position: fixed 或 transform 过深的嵌套节点，都可能让 toPng() 报错或生成空白图。
- 确保目标元素已挂载到 DOM 且完全渲染（可用
setTimeout或requestAnimationFrame延迟调用） - 跨域图片必须加
crossOrigin="anonymous"属性，否则会被 canvas 污染而拒绝读取 - 字体加载需显式等待：用
document.fonts.load('14px "PingFang SC"')+await再执行转换 - 避免在
filter回调里直接操作 DOM（如node.remove()），只做布尔判断返回true/false
pixelRatio 和 quality 参数怎么设才不糊也不卡
pixelRatio 控制输出图像的物理像素密度，quality 仅对 toJpeg() 生效；两者叠加不当会导致内存暴涨或白屏崩溃。
- 移动端海报常用
pixelRatio: 2+quality: 0.92，平衡清晰度与体积 - 高清大屏长图慎用
pixelRatio: 3，DOM 高度超 5000px 时容易触发 Chrome 的 canvas 尺寸限制（最大约 32767px × 32767px） - 若目标区域含大量 SVG 或纯色块，优先用
toSvg()，体积小、缩放无损，但不支持 CSS 滤镜和部分阴影效果
本地 HTML 文件怎么绕过 CORS 直接转图
本地双击打开的 file:// 协议下，html-to-image 会因跨域策略拒绝加载本地图片或字体文件，报错类似 Failed to execute 'toDataURL' on 'HTMLCanvasElement'。
立即学习“前端免费学习笔记（深入）”；
- 必须起一个本地 HTTP 服务：Python 用户运行
python -m http.server 8000，然后访问http://localhost:8000/index.html - Node.js 用户推荐
npx http-server -p 8000，比全局安装更干净 - 开发阶段可在 vite / webpack 项目中直接
importHTML 片段为字符串，用DOMParser解析后挂载到隐藏容器再转换，彻底避开文件协议限制
真正难的从来不是“怎么转”，而是“转出来能不能跟页面一模一样”——字体 fallback、CSS 变量计算、伪元素渲染、阴影层级、甚至 subpixel 渲染差异，都会在 canvas 里悄悄偏移一两个像素。别指望一次配置打遍天下，得对着真实设备反复比对输出。
