Puppeteer ElementHandle.$$eval() 详解：在指定元素内批量查询并对元素数组求值

本指南聚焦 Puppeteer 中 ElementHandle.$$eval() 这一核心方法：它能够在当前元素作用域内，按照给定选择器查询出一组元素，并将这组元素作为数组传递给一个在页面上下文中执行的函数。读完本文，你将掌握其完整签名与类型约束、参数语义、底层实现原理，以及如何用它批量提取数据、并将它与 $$、$eval、page.$$eval 正确区分使用。

本文内容以 API 文档 docs/api/puppeteer.elementhandle.__eval.md 为骨架，并结合 packages/puppeteer-core/src/api/ElementHandle.ts 的源码实现进行印证与扩充。

方法与核心作用

ElementHandle.$$eval() 属于 ElementHandle 类的实例方法，其行为可概括为两句话：

• 在当前元素（ElementHandle 所引用的 DOM 节点）内部，查询所有匹配给定 selector 的元素；
• 把匹配到的元素集合作为数组传给 pageFunction，并在页面上下文（而非 Node.js 上下文）中执行该函数。

关键特性是：如果 pageFunction 返回一个 Promise，那么 $$eval() 会等待该 Promise 兑现后再返回结果，因此它天然支持异步回调与 await 链式调用。

方法签名与类型系统

官方文档给出的签名如下：

class ElementHandle {
  $$eval<
    Selector extends string,
    Params extends unknown[],
    Func extends EvaluateFuncWith<Array<NodeFor<Selector>>, Params> =
      EvaluateFuncWith<Array<NodeFor<Selector>>, Params>,
  >(
    selector: Selector,
    pageFunction: Func | string,
    ...args: Params
  ): Promise<Awaited<ReturnType<Func>>>;
}

该签名中的三个泛型参数逐层体现了类型安全设计：

泛型	含义	说明
Selector extends string	选择器字面量类型	让 TypeScript 能够根据传入的 CSS 选择器推断元素类型
Params extends unknown[]	额外参数类型	与 pageFunction 的入参类型一一对应
Func	回调函数类型	默认为 EvaluateFuncWith<Array<NodeFor<Selector>>, Params>，即第一个入参为匹配元素数组的函数

其中 NodeFor<Selector> 是类型层面的“字符串选择器 → 对应 DOM 节点类型”映射工具，EvaluateFuncWith<V, T> 则描述“第一个实参类型为 V、后续实参依次为 T 展开”的可执行函数签名，二者均定义于 packages/puppeteer-core/src/common/types.ts（见该文件第 106、113 行附近的 EvaluateFuncWith 与 NodeFor 类型）。借助它们，当 selector 是 'div.tweet' 时，回调里的数组元素会被推断为相应的 HTML 元素类型，从而获得 IDE 自动补全与编译期检查。

参数与返回值详解

selector

用于在当前元素内查询子元素的选择器。

• CSS 选择器可直接传入，例如 '.tweet'、'ul > li'；
• Puppeteer 还支持其特有的非 CSS 选择器语法，允许按文本（text selector）、可访问性角色与名称（ARIA selector）、XPath 查询，也支持跨 shadow root 组合查询（在 Shadow DOM 内部查找元素）；
• 也可以使用选择器前缀来显式指定查询类型（prefixed selector syntax），例如 'text/Hello'、'aria/button[name="Submit"]'、'xpath//div' 等。

需要注意的是，与 page.$() / page.$$() 的“全页面范围内查询”不同，ElementHandle.$$eval() 的查询范围被限定在当前 ElementHandle 所代表的子树内——这正是它区别于 page.$$eval() 的关键。

pageFunction

要在元素所在页面的上下文中执行的函数。它接收一个参数：匹配 selector 的所有元素所构成的数组，作为其第一个实参。

传入的形式有两种：

• 一个真正的函数（会被 Puppeteer 序列化后注入页面执行）；
• 一个函数体字符串。

如果该函数返回 Promise，$$eval() 会等待其兑现，因此可以在函数体内放心使用 await 或返回异步表达式。

args

可变数量的额外参数，会按顺序传给 pageFunction。这常用于把 Node.js 侧的数据传入页面回调，例如分页号、索引、阈值等。从源码看，这些参数通过 elements.evaluate(pageFunction, ...args) 传递（见下文实现分析），因此在回调形参表中应放在数组参数之后。

返回值

类型为 Promise<Awaited<ReturnType<Func>>>——即 pageFunction 返回值（若为 Promise 则取其兑现值）的 Promise。实际使用中通常直接 await 拿到最终结果，例如一个 string[]。

官方示例：批量提取推文文本

文档给出了最典型的应用场景——在 .feed 容器内批量读取每一条 .tweet 的文本内容：

<div class="feed">
  <div class="tweet">Hello!</div>
  <div class="tweet">Hi!</div>
</div>

const feedHandle = await page.$('.feed');

const listOfTweets = await feedHandle.$$eval('.tweet', nodes =>
  nodes.map(n => n.innerText),
);

执行流程为：先通过 page.$('.feed') 拿到容器元素的句柄 feedHandle，再调用 feedHandle.$$eval('.tweet', ...)——注意这里的查询只会在 .feed 内部发生，即使页面其它位置存在不属于该容器的 .tweet 也不会被纳入结果。回调中 nodes 是一个 HTMLDivElement[]，这里使用原生 Array.prototype.map 与 innerText 提取纯文本，最终 listOfTweets 为 ['Hello!', 'Hi!']。

结合源码理解底层实现原理

$$eval 的具体实现在 packages/puppeteer-core/src/api/ElementHandle.ts 的 async $$eval<...>(...) 方法中（约第 563 至 588 行），其内部流程可分为四步：

1. 记录函数来源：调用 withSourcePuppeteerURLIfNone(this.$$eval.name, pageFunction)，为匿名函数附加调试用 URL，便于 DevTools 中定位与排错；
2. 批量查询元素：const results = await this.$$(selector);——this.$$() 会在当前元素子树内执行真实查询，返回一组 ElementHandle（而非扁平数组），每个句柄对应一个匹配节点；
3. 把元素句柄打包成数组：借助 this.evaluateHandle((_, ...elements) => { return elements; }, ...results) 在页面端把这一组元素句柄重新组装为一个“元素数组句柄” elements，从而能以单一句柄形式交给后续的 evaluate；
4. 执行回调并立即回收资源：Promise.all([elements.evaluate(pageFunction, ...args), ...results.map(r => r.dispose())])——一方面在页面上下文中以元素数组作为第一实参执行 pageFunction，另一方面并行地逐个 dispose 临时句柄以避免内存泄漏，最后取出第一个（即求值结果）返回。

从实现可以得出两点实战启示：

• $$eval 是“查询 + 求值”的组合拳，它替你完成了“批量 $$ → 组装数组 → evaluate → 释放句柄”的全流程，因而比手写 $$ + 循环更简洁、更不容易泄漏句柄；
• 回调在页面上下文执行，只能操作可被序列化的数据与 DOM，不能直接访问 Node.js 侧闭包变量（需通过 ...args 传入）。

与其他 API 的取舍

在实际编码中，$$eval 常与下面几个方法放在一起权衡：

方法	查询范围	传给回调的第一个实参	典型用途
ElementHandle.$eval(selector, fn, ...args)	当前元素内首个匹配	单个元素	提取/修改容器内第一个匹配节点的值
ElementHandle.$$eval(selector, fn, ...args)	当前元素内所有匹配	元素数组	批量提取文本、属性或做聚合统计
ElementHandle.$$(selector)	当前元素内所有匹配	—（返回句柄数组）	需要对每个句柄继续交互/逐一遍历时
page.$$eval(selector, fn, ...args)	整个页面	元素数组	不需要限定作用域时的批量求值

其中 page.$$eval 是 Frame/Page 层面的近似方法，实现在 packages/puppeteer-core/src/api/Page.ts 与 packages/puppeteer-core/src/api/Frame.ts 中可查。选择建议：查询范围需要限定在某个容器元素内部时用 ElementHandle.$$eval；已持有句柄且后续需逐元素点击、拖拽时，则更适合 $$ 拿到句柄数组再循环操作——因为一旦把元素交给 pageFunction 求值，返回的仅是求值结果（通常是普通 JSON 值），无法再对其进行 Puppeteer 级的交互操作。

更多实战用法

批量收集 href 与属性

const links = await containerHandle.$$eval('a', (anchors, attr) =>
  anchors.map(a => a.getAttribute(attr)),
  'href',
);

这里通过 ...args 把属性名 'href' 从 Node.js 侧传入页面回调，展示了参数透传的典型姿势。

异步回调与汇总统计

const total = await listHandle.$$eval('li', async items => {
  const values = items.map(el => Number(el.dataset.price ?? 0));
  return values.reduce((sum, v) => sum + v, 0);
});

若 pageFunction 为异步函数（返回 Promise），$$eval 会等待其兑现后再返回最终数值，这一行为与文档中“If the given function returns a promise, then this method will wait till the promise resolves”的约定完全一致。

注意事项与限制

• 范围限定：查询只发生在当前 ElementHandle 对应节点的子树内；如需全页面查询，改用 page.$$eval。
• 句柄自动释放：由 $$eval 内部产生的临时句柄会被自动 dispose，因此不要在回调内长期保存传入的元素引用供方法返回后使用——它们对应的句柄可能已被回收，元素句柄的跨调用复用应交给调用方自行管理的 $$。
• 返回值可序列化：pageFunction 的返回结果必须是可序列化的普通值（字符串、数字、数组、普通对象等），不能返回 DOM 节点或不可序列化对象。
• 回调闭包限制：传入的 pageFunction 会被序列化到浏览器中执行，无法捕获外层作用域变量，需要的数据一律通过 ...args 显式传入。

通过上述内容，你已经可以熟练使用 ElementHandle.$$eval() 在容器元素内完成“范围受限的批量元素求值”，并可结合源码理解其句柄管理与资源释放机制，从而写出更安全、高效的页面数据提取代码。