puppeteer 是目前最可靠 html 转 jpg 方案，通过真实 chromium 渲染，完美支持 css、字体、svg、canvas 动画；需配置 headless: 'new' 和 --no-sandbox 等参数，避免 docker/权限问题；html2canvas 等替代方案容错率低、兼容性差，仅适用于简单静态场景。
用 Puppeteer 生成 HTML 转 JPG 最可靠
直接用浏览器引擎渲染再截图，是目前最稳定的方式。Node.js 环境下 puppeteer 封装了 Chromium，能真实复现 CSS、字体、SVG、甚至 canvas 动画效果，比纯服务端渲染库（如 html2canvas）容错率高得多。
常见错误：本地开发时没装 Chromium 或权限不足导致 Failed to launch browser；生产环境没配 --no-sandbox 参数在 Docker 或无权用户下直接崩溃。
- 安装：
npm install puppeteer（会自动下载 Chromium；若想跳过下载，用puppeteer-core+ 手动指定已安装的 Chrome 路径） - 关键配置必须加：
headless: 'new'（新版 headless 模式）、args: ['--no-sandbox', '--disable-setuid-sandbox']（尤其 Docker 容器里） - 截图前建议等 DOM 加载完成：
await page.waitForSelector('body')或更稳妥地用page.waitForNetworkIdle() - JPG 质量控制靠
quality参数：await page.screenshot({ type: 'jpeg', quality: 90, fullPage: true })
html2canvas 基本不可用于真实项目
html2canvas 是纯 JS 渲染，不走真实浏览器，对 flex 布局、CSS 变量、@font-face 字体、transform 层叠、position: fixed 元素支持极差，生成图常错位、漏字、空白。它只适合简单内联样式、无交互的静态卡片类场景。
典型报错现象：html2canvas is not defined（没正确引入）或截图后文字全变成方块（字体未加载/跨域限制）。
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
- 必须确保所有字体已加载完成，否则用
useCORS: true+ 后端代理字体资源（CDN 字体常因 CORS 被拒） -
scale: 2可提升清晰度，但会显著增加内存占用，长页面易触发RangeError: Maximum call stack size exceeded - 无法截取
iframe内容、video帧、canvas绘制结果（除非同源且显式调用toDataURL()）
服务端用 wkhtmltopdf + ImageMagick 是旧方案但仍有用
如果不能跑 Node.js，又需要命令行批量处理，wkhtmltopdf 输出 PDF 再转 JPG 是可行路径。但它依赖系统级二进制，macOS 上 Homebrew 安装后可能因 Qt 版本冲突报 Segmentation fault；Linux 上需手动装 libX11 等一堆依赖。
性能上比 Puppeteer 慢约 3–5 倍，且对现代 CSS 支持滞后（比如不识别 gap、aspect-ratio）。
- PDF 转 JPG 推荐用
magick（ImageMagick 7+）：magick input.pdf -density 150 -quality 90 output.jpg - 必须设
-density，否则默认 72dpi 导致图片模糊；-quality对 JPEG 有效，对 PNG 无效 -
wkhtmltopdf --enable-local-file-access index.html out.pdf才能加载本地 CSS/JS/图片，否则全是 404
浏览器里用 Canvas + toBlob 不推荐用于完整页面
前端直接调用 canvas.toBlob() 只适合局部 DOM 片段（比如一个 <div id="card">），整页截图会因滚动、fixed 元素、跨 iframe、字体加载时机等问题失败。而且 iOS Safari 对大 canvas 有尺寸限制（通常超 4096×4096 就静默失败）。
<p>容易被忽略的坑：<code>getBoundingClientRect() 返回的是视口坐标，没考虑页面滚动偏移，直接画会导致顶部内容被截掉。
- 务必用
element.getBoundingClientRect().top + window.scrollY计算真实 Y 坐标 - 字体必须提前用
document.fonts.load()等待加载完成，否则 canvas 里显示为默认字体 - 不要用
toDataURL()（Base64 体积大、内存爆），改用toBlob(callback, 'image/jpeg', 0.9)
page.screenshot() 是目前唯一能兼顾准确性、可控性和可维护性的方案，其他方法要么功能残缺，要么调试成本远高于收益。真正上线前，一定要在目标环境（特别是 Docker、低内存服务器、不同分辨率客户端）跑一遍真实 HTML 样例，别信本地开发机上的“看起来可以”。
