Puppeteer截图前需确保页面完全渲染：使用waitUntil: "networkidle0"等待网络空闲，显式设置viewport，处理Web Font和中文字体缺失，并校验资源路径。
用 Puppeteer 截图前先确认页面是否已完全渲染
直接保存 index.html 文件本身不会生成图片——浏览器必须实际加载并渲染它，才能截图。Puppeteer 是目前最可靠的选择，但很多人卡在「截出来是白屏」或「缺样式/字体」上。核心原因是没等 DOM、CSS、字体、异步 JS 都就绪就调用了 screenshot()。
- 确保启动时加
headless: "new"（旧版true在 Chrome 112+ 已弃用） - 用
page.goto("file:///path/to/index.html", { waitUntil: "networkidle0" })，比load更稳妥 - 若页面含 Web Font，加一行
await page.waitForFunction(() => document.fonts.check("12px Arial"));防止文字空白
截图分辨率与裁剪要手动控制 viewport 和 clip
默认截图是整个页面滚动高度，不是你看到的视口区域；而且高分屏（如 Mac Retina）下不设缩放会模糊。关键参数不是靠 guess，而是明确设：
-
viewport必须显式传入，例如{ width: 1200, height: 800 }，否则用系统默认（常为 800×600） - 要截「可视区域」而非整页，用
fullPage: false+clip，比如{ x: 0, y: 0, width: 1200, height: 800 } - 高清输出加
deviceScaleFactor: 2，但文件体积翻倍，按需开启
中文乱码或图标不显示？检查字体和资源路径
Puppeteer 内置 Chromium 不自带中文字体，index.html 里用的 font-family: "PingFang SC" 或 "Microsoft YaHei" 在 Linux/macOS headless 环境大概率 fallback 到无字形的字体，结果是方块或空白。这不是代码 bug，是环境缺失。
- Linux 下运行前装系统字体：Ubuntu 执行
sudo apt-get install fonts-wqy-zenhei，再启动 Puppeteer - 避免相对路径引用 CSS/JS：把
index.html中的./style.css改成绝对路径file:///full/path/to/style.css，否则 Puppeteer 加载失败静默忽略 - 图标（如 iconfont、SVG sprite）404 时截图不会报错，但区域留空——用
page.on("response", r => { if (r.status() === 404) console.log(r.url()); })排查
命令行快速试跑别写一整套 Node.js 脚本
只想临时转一张图？不用新建 script.js。直接终端一行命令更省事，也方便调试参数：
立即学习“前端免费学习笔记（深入）”；
node -e "
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch({ headless: 'new' });
const page = await browser.newPage();
await page.setViewport({ width: 1200, height: 800 });
await page.goto('file:///Users/me/project/index.html', { waitUntil: 'networkidle0' });
await page.screenshot({ path: 'output.png', fullPage: false, clip: { x: 0, y: 0, width: 1200, height: 800 } });
await browser.close();
})()
"
改路径、宽高、输出名，回车就执行。出问题看终端报错，比埋在脚本里 debug 快得多。
真正麻烦的从来不是调用 screenshot() 这一行，而是让页面在无 GUI 的 Chromium 里，表现得跟你本地 Chrome 里一模一样——字体、路径、异步时机、缩放，每个点都可能断掉链条。
