使用Puppeteer截取超出视口元素时截图空白的解决方法

核心原因 #

Puppeteer默认仅渲染当前浏览器视口内的内容，超出视口的部分不会自动滚动渲染，即便通过clip参数指定了完整尺寸，未被渲染的区域仍会显示空白。针对元素溢出body的场景，需要通过调整视口或确保元素完全进入渲染区域来解决。

可行解决方案 #

• 调整页面视口匹配元素尺寸：直接将页面视口的宽高设置为目标元素的scrollWidth和scrollHeight，让整个元素处于视口范围内，确保全部内容被渲染。
• 替换固定延迟为智能等待：用waitForFunction替代setTimeout，确保元素内容完全加载完成后再截图，避免因异步加载导致的内容缺失。
• 避免强制裁剪：不要使用clip参数强制指定截图尺寸，该参数仅裁剪区域，不会触发视口外内容的渲染。

修改后的代码示例 #

it("Test", async () => {
    // 获取目标元素的完整尺寸
    const [elementWidth, elementHeight] = await page.evaluate(() => {
        const appEl = document.querySelector(".app");
        return [appEl.scrollWidth, appEl.scrollHeight];
    });

    // 调整页面视口，让元素完全处于视口内
    await page.setViewport({
        width: elementWidth,
        height: elementHeight,
        deviceScaleFactor: 1 // 保持正常的像素缩放比例
    });

    // 等待元素内容完全渲染完成（替代固定延迟，更可靠）
    await page.waitForFunction(
        (selector) => {
            const el = document.querySelector(selector);
            return el.scrollHeight === el.offsetHeight;
        },
        {},
        ".app"
    );

    // 截取目标元素
    const el = await page.$(".app");
    const image = await el.screenshot();

    expect(image).toMatchImageSnapshot({
        failureThreshold: "0.10",
        failureThresholdType: "percent",
    });
});

额外说明 #

如果目标元素依赖父容器的样式（如overflow: hidden）导致内容被隐藏，需先在page.evaluate中临时修改父容器的样式（例如设置overflow: visible），确保元素完整内容可被渲染后再截图。

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