Puppeteer中document.querySelectorAll返回空数组问题求助

问题重现 #

使用Puppeteer脚本获取页面元素时返回空数组，但在Chrome控制台执行相同选择器能得到245个元素，截图显示页面已加载。脚本代码如下：

const puppeteer = require('puppeteer')
const fs = require('fs/promises')

async function start() {
    const browser = await puppeteer.launch()
    const page = await browser.newPage()
    await page.setViewport({ width: 1366, height: 768});
    await page.goto("http://localhost:8080/")
    await page.waitForTimeout(5000)
    await page.screenshot({ path: "isc-loc-1.png", fullPage: true})

    const reportElts = await page.evaluate( ()=> {
        return Array.from(document.querySelectorAll("span.css-13whmom")).map(x => x.innerText)
    })

    console.log("Number of Rows in Report: ",reportElts.length)

    await browser.close()
}

start()

可能的原因及解决方法 #

1. 目标元素位于iframe中 #

Puppeteer的page.evaluate默认在主文档上下文执行，若元素嵌套在iframe里，主文档的document无法获取到iframe内的元素。
解决方法：先定位到目标iframe，切换上下文后再执行选择器：

// 在page.goto之后添加
const iframe = await page.waitForSelector('iframe'); // 替换为实际的iframe选择器
const frame = await iframe.contentFrame();

// 用frame.evaluate替代page.evaluate
const reportElts = await frame.evaluate(() => {
    return Array.from(document.querySelectorAll("span.css-13whmom")).map(x => x.innerText)
});

2. 静态等待（waitForTimeout）不可靠 #

waitForTimeout(5000)是固定时长等待，可能元素在截图后才完成渲染，或者页面加载后还有异步请求未完成。应该等待目标元素出现后再执行查询。
解决方法：使用waitForSelector或waitForFunction等待元素：

// 替换waitForTimeout
await page.waitForSelector("span.css-13whmom", { timeout: 10000 }); // 等待至少一个目标元素出现

// 或者等待元素数量符合预期
await page.waitForFunction(() => {
    return document.querySelectorAll("span.css-13whmom").length >= 245;
}, { timeout: 10000 });

// 再执行元素查询
const reportElts = await page.evaluate( ()=> {
    return Array.from(document.querySelectorAll("span.css-13whmom")).map(x => x.innerText)
})

3. 无头浏览器环境差异 #

Puppeteer默认使用无头模式启动浏览器，部分网站会对无头浏览器做渲染限制，或者样式渲染逻辑有差异。
解决方法：以有头模式启动，或添加模拟参数：

// 修改launch参数
const browser = await puppeteer.launch({
    headless: false, // 显示浏览器窗口
    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"'
    ]
});

4. 元素位于Shadow DOM内 #

如果目标元素嵌套在Shadow DOM中，直接用document.querySelectorAll无法穿透Shadow边界获取元素。
解决方法：先获取Shadow根节点再查询：

const reportElts = await page.evaluate(() => {
    const shadowHost = document.querySelector('#shadow-host'); // 替换为实际的Shadow宿主元素选择器
    if (!shadowHost) return [];
    const shadowRoot = shadowHost.shadowRoot;
    return Array.from(shadowRoot.querySelectorAll("span.css-13whmom")).map(x => x.innerText);
});

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