使用Puppeteer导出PDF/WebP/PNG时出现模糊问题求助

问题描述 #

我使用Puppeteer导出PDF、WebP、PNG文件时遇到模糊问题，即使严格按照官方文档的基础示例代码执行，生成的图片仍然模糊。

示例代码：

const browser = await puppeteer.launch();
const page = await browser.newPage();

// Navigate the page to a URL
await page.goto("https://developer.chrome.com/");

// Set screen size
await page.setViewport({ width: 1080, height: 1024 });

const screenshot = await page.screenshot({
  quality: 100,
  type: "webp",
});

res.set("Content-Type", "image/webp");
res.send(screenshot);

生成的模糊效果参考图：

尝试过多种方法仍未解决，求有相关经验的人帮忙排查原因。

解决方法 #

1. 提升设备缩放因子（deviceScaleFactor） #

Puppeteer默认的deviceScaleFactor为1，这是导致高分辨率截图模糊的核心原因之一。在setViewport中设置更高的缩放因子，直接提升截图的像素密度：

await page.setViewport({ 
  width: 1080, 
  height: 1024,
  deviceScaleFactor: 2 // 生成2倍分辨率的截图，清晰度翻倍
});

如果需要保持输出尺寸与原设置一致，可以先放大视口，再通过clip裁剪回目标尺寸：

await page.setViewport({ 
  width: 2160, 
  height: 2048, // 先设置2倍宽高
  deviceScaleFactor: 1
});

const screenshot = await page.screenshot({
  quality: 100,
  type: "webp",
  clip: { x: 0, y: 0, width: 1080, height: 1024 } // 裁剪回原尺寸
});

2. 等待页面完全加载再截图 #

page.goto默认仅等待DOM加载完成，页面内的图片、字体等资源可能还未加载完毕，导致截图时内容缺失或模糊。添加waitUntil参数等待网络空闲：

await page.goto("https://developer.chrome.com/", {
  waitUntil: 'networkidle0' // 等待500ms内无网络请求，确保资源加载完成
});

也可以结合waitForSelector等待关键元素可见：

await page.goto("https://developer.chrome.com/");
await page.waitForSelector('body', { visible: true }); // 等待页面主体完全渲染

3. 禁用页面自适应缩放规则 #

部分页面会根据设备视口自动调整缩放比例，导致截图内容被压缩。可以通过注入脚本强制禁用页面缩放：

await page.setViewport({ width: 1080, height: 1024, deviceScaleFactor: 2 });
await page.evaluate(() => {
  // 替换或添加viewport元标签，禁止用户缩放
  const viewportMeta = document.querySelector('meta[name="viewport"]');
  if (viewportMeta) {
    viewportMeta.content = 'width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no';
  } else {
    document.head.insertAdjacentHTML('beforeend', '<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">');
  }
});

4. PDF导出的专属优化 #

如果是PDF文件模糊，除了上述设置，还需在page.pdf中开启背景打印并调整缩放比例：

await page.pdf({
  path: 'output.pdf',
  printBackground: true, // 确保页面背景图、样式被打印
  scale: 2, // 提升PDF渲染缩放比例
  format: 'A4'
});

5. 调整浏览器启动参数 #

确保Chrome浏览器以高分辨率模式启动，避免启动时的默认低分辨率限制：

const browser = await puppeteer.launch({
  args: [
    '--disable-dev-shm-usage',
    '--no-sandbox',
    '--force-device-scale-factor=2', // 全局设置设备缩放因子
    '--start-maximized' // 最大化窗口，避免布局异常
  ]
});

内容的提问来源于stack exchange，提问作者user3708221