PuppeteerJS截图异常：参数错误/空白图/视口尺寸不生效

问题1：Protocol error参数类型错误 #

报错提示int32 value expected，核心原因是从req.body获取的width/height是字符串类型，但Puppeteer的视口设置要求必须是整数类型。

解决方法：
将宽高转为整数，同时添加默认值（防止前端不传参数导致报错）：

const width = parseInt(req.body.width) || 1280;
const height = parseInt(req.body.height) || 720;

问题2：截图空白/尺寸始终800*600 #

尺寸不生效的原因 #

之前代码里的page.setViewport是异步函数，但没加await，导致截图操作在视口设置完成前就执行了，因此用了默认的800*600尺寸。

空白截图的原因 #

• waitUntil: 'domcontentloaded'仅等待DOM加载完成，页面的图片、样式、动态脚本可能还没渲染完毕，此时截图就会出现空白。
• 部分SPA页面（React/Vue）需要等待组件渲染完成，仅靠DOM加载事件不够。

综合解决方案 #

1. 给page.setViewport加await，确保视口设置完成后再进行后续操作
2. 调整page.goto的waitUntil参数，改用networkidle2（网络请求空闲2秒），兼顾加载速度和渲染完整性；复杂SPA可改用networkidle0或等待特定元素
3. 可选：添加page.waitForSelector等待页面关键元素渲染完成
4. 用try/catch包裹流程，确保浏览器在异常时也能正常关闭

修正后的完整代码 #

exports.captureWebsite = asyncHandler(async (req, res, next) => {
  const url = req.body.url;
  const format = req.body.format ? req.body.format : 'jpeg';

  if (!url) {
    return next(new ErrorResponse(`Please add an URL`, 500));
  }

  // 转换为整数并设置默认值
  const width = parseInt(req.body.width) || 1280;
  const height = parseInt(req.body.height) || 720;

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

    // 先设置视口，再跳转页面（推荐顺序）
    await page.setViewport({
      width: width,
      height: height
    });

    // 等待网络空闲2秒，确保页面资源加载完成
    await page.goto(url, { waitUntil: 'networkidle2' });

    // 等待页面关键元素出现，确保渲染完成
    await page.waitForSelector('body');

    const image = await page.screenshot({
      encoding: 'base64',
      fullPage: true,
      type: format
    });

    await browser.close();

    res.status(200).json({
      success: true,
      data: `data:image/${format};base64,${image}`
    });
  } catch (err) {
    // 异常时确保浏览器关闭
    if (browser) await browser.close();
    next(err);
  }
});

额外注意事项 #

• 如果是无头模式运行，部分网站会检测无头浏览器，可添加启动参数规避：

  browser = await puppeteer.launch({
    args: ['--no-sandbox', '--disable-setuid-sandbox', '--user-agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/114.0.0.0 Safari/537.36"']
  });
  

• fullPage: true会截取整个页面高度，此时设置的height会被页面实际高度覆盖，但width仍然生效。

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