Puppeteer 是 HTML 转图片最稳方案，因启动真实 Chromium 可正确渲染 CSS、字体、SVG 等；html2canvas 仅适用于纯前端场景但缺陷多；Node 端推荐搭配 sharp 高效处理截图图像。
用 Puppeteer 直接截图 HTML 页面最稳
本地开发或 CI 环境里需要把 HTML 转成图片，Puppeteer 是目前最可靠的选择——它启动真实 Chromium 实例，能正确渲染 CSS、字体、SVG、Canvas，连 position: sticky 和 @media print 都能按需处理。
常见错误是直接用 html2canvas：它纯靠 JS 模拟渲染，遇到 transform 层叠上下文、跨域图片、Web Font 加载未完成、iframe 内容，就大概率白屏或错位。
- 必须等页面真正“可交互”再截图：
page.waitForSelector('main')比page.waitForTimeout(2000)更安全 - 设置视口尺寸要匹配目标容器：
page.setViewport({ width: 1200, height: 800 })，否则截出来是默认 800×600 的小图 - 导出 PNG 推荐用
page.screenshot({ type: 'png', fullPage: true })；JPG 需显式加quality: 90，否则默认是 100（但 Chromium 对 JPG 的 quality 参数实际支持有限）
本地调试时别用在线转换工具
所谓“HTML 转图片”的在线服务，背后基本也是 Puppeteer 或类似方案，但你无法控制其环境：字体缺失、CORS 拦截、JS 执行超时、甚至页面被注入广告脚本。本地跑不通的 HTML，在线工具几乎一定失败。
典型报错：net::ERR_BLOCKED_BY_CLIENT（广告拦截器干的）、Failed to launch chrome（Docker 容器缺 sandbox 依赖）、Font not found（没装中文字体）。
立即学习“前端免费学习笔记（深入）”；
把任意文章或文档内容转换成精美的全屏翻页 HTML 演示文件（幻灯片风格）。当用户发来一篇文章、文档链接、Markdown 内容、或粘贴的文本，并且希望生成演示用的 HTML 时触发。支持任意内容来源：iWiki 链接、KM 链接、本地文件路径、直接粘贴的文本。生成的 HTML 文件保存到本地工作区，并通过企微直接发送给用户。触发词示例：帮我把这篇文章做成PPT、转成演示文档、生成HTML幻灯片、做个演示、转成可以演示的格式、article to deck、make a slide。
- Linux 服务器上跑 Puppeteer，必须安装字体包：
apt-get install fonts-wqy-zenhei（中文）或fonts-liberation（西文） - Docker 里要加启动参数：
--no-sandbox --disable-setuid-sandbox，否则chrome进程直接崩溃 - 本地开发用
puppeteer-core+ 已安装 Chrome，避免重复下载 Chromium 二进制（省 150MB+）
纯前端场景下 html2canvas 是唯一选项，但得绕开它的硬伤
如果 HTML 必须在浏览器里转图（比如用户点按钮生成分享图），html2canvas 没有替代品，但它不支持 background-image: url(data:...)、不能读取跨域 img、对 filter 和 clip-path 渲染极不稳定。
最容易被忽略的是字体加载时机：document.fonts.load() 必须 await 完，否则截图全是方框。
- 强制触发重排再截图：
el.offsetHeight; html2canvas(el)，避免因 CSS 动画未结束导致布局错乱 - 替换跨域图片为代理地址，或提前用
fetch+createObjectURL转成同源 blob URL - 避开
transform: scale()，改用width/height+font-size缩放，html2canvas对 transform 的矩阵计算经常失准
Node.js 里用 Sharp 处理截图后图像
Puppeteer 截出来的 Buffer 是原始 PNG 数据，想压缩、加水印、改尺寸、转 WebP，别手写 canvas 操作——sharp 库快一个数量级，内存占用低，API 直白。
比如生成带压缩的 JPG：sharp(buffer).jpeg({ quality: 85 }).toBuffer()；而用 Canvas 自己做，光解码 PNG 就要多占 3 倍内存。
-
sharp不支持 GIF 动画帧，别试图用它合并多张截图做动图 - 截图宽高不是 4 的倍数时，某些 JPEG 编码器会自动 pad，用
sharp().ensureAlpha()可避免黑边 - 如果最终要传 CDN，优先转 WebP：
sharp(buffer).webp({ quality: 75 }).toBuffer()，体积比 JPG 小 25%～30%
真正麻烦的从来不是“怎么转”，而是“转出来的图和屏幕上看到的是否一致”。字体、缩放、设备像素比、CSS containment、甚至 will-change 的 presence，都会让截图结果偏移几像素——调试时一定要开 fullPage: false 截固定区域，对比 DOM 元素边界盒再调。
