Puppeteer筛选DOM元素时无法获取有效ElementHandle问题咨询

问题背景 #

• 基于Puppeteer爬取PageSpeed Insights站点数据，核心需求是对PageSpeed检测结果页进行截图，官方API仅能返回原始检测数据，无法满足截图需求。
• 目标页面按钮类名随机生成、多元素复用类名，无法通过高精度CSS选择器直接定位目标元素，需要按元素文本（如This URL、Origin按钮）筛选后操作。

问题复现 #

在浏览器原生控制台执行以下代码，可以直接拿到可操作的DOM元素、调用click()等方法：

[...document.querySelectorAll('button')].filter(b => b.innerText === 'This URL')

但在Puppeteer中使用page.$$eval、page.evaluate编写同类逻辑，返回的结果只有序列化后的普通对象，仅携带__incrementalDOMData属性，不具备ElementHandle的操作方法：

const browser = await puppeteer.launch()
const page = await browser.newPage()
await page.goto(`https://pagespeed.web.dev/report?url=${url}`)
await page.waitForSelector(homepageWaitSelector, { visible: true })

// 以下写法均无法返回可用ElementHandle
const buttons = await page.$$eval('button', buttons => buttons.filter(button => button.innerText === 'This URL'))
const buttons = await page.$$eval('button', buttons => buttons.map(b => b.innerText).filter(t => t === 'This URL'))
const buttons = await page.evaluate(() => {
  const b = [...document.querySelectorAll('button')].filter(b => b.innerText === 'This URL')
  return b
})

错误返回结构示例：

[{
  __incrementalDOMData: {
    j: ['class', 'the-classes-used'],
    key: 'a key',
    v: true
}]

问题原因 #

page.evaluate、page.$$eval的返回值会经过JSON序列化跨执行上下文传输，DOM节点包含循环引用无法被完整序列化，仅会保留可枚举的普通属性，不可能直接返回页内DOM对象的引用。
目标页面基于Incremental DOM框架渲染，返回结构中携带的__incrementalDOMData就是框架挂载在元素上的内部属性，不是可操作的DOM对象。

可行实现方案 #

方案1：遍历ElementHandle按文本过滤 #

先用page.$$拿到所有匹配选择器的ElementHandle数组，再逐个读取元素文本做筛选，筛选后保留的就是可直接操作的ElementHandle：

// 拿到页面所有按钮的ElementHandle
const allButtons = await page.$$('button')
const targetButtons = []
for (const btn of allButtons) {
  // 读取单个按钮的文本，自动去除首尾空白字符避免匹配失败
  const btnText = await btn.evaluate(el => el.innerText.trim())
  if (btnText === 'This URL' || btnText === 'Origin') {
    targetButtons.push(btn)
  }
}
// 直接调用ElementHandle方法操作即可
await targetButtons[0].click()

方案2：使用XPath直接按文本定位 #

Puppeteer原生支持XPath表达式查询，XPath原生支持按节点文本匹配，无需手动遍历即可直接拿到目标元素的ElementHandle，代码更简洁：

// 等待目标元素加载完成后直接获取句柄，normalize-space会自动处理文本前后空格、换行
const [thisUrlBtn] = await page.$x('//button[normalize-space(.)="This URL"]')
const [originBtn] = await page.$x('//button[normalize-space(.)="Origin"]')

// 直接操作元素
await thisUrlBtn.click()

注意：如果页面存在动态加载的内容，建议在定位元素前加显式等待，避免拿不到元素报错。

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