Puppeteer JSHandle.evaluateHandle() 深入解析：持引用返回的页面函数求值

导读

JSHandle.evaluateHandle() 是 Puppeteer 中在页面上下文里执行 JavaScript、并以句柄（handle）形式返回结果对象的核心 API。它在 packages/puppeteer-core/src/api/JSHandle.ts 中与 evaluate() 配对出现，二者共享几乎相同的签名与传参方式，关键差异在于返回值：evaluateHandle() 返回的是指向运行时对象的 JSHandle 引用，而不是被序列化后的值。读完本文，你将掌握该方法与 evaluate() 的取舍、句柄生命周期管理、类型系统在其中的作用，以及在 CDP 层的底层实现原理。

方法签名与语义

JSHandle.evaluateHandle() 的官方签名（见 docs/api/puppeteer.jshandle.evaluatehandle.md）如下：

class JSHandle {
  evaluateHandle<
    Params extends unknown[],
    Func extends EvaluateFuncWith<T, Params> = EvaluateFuncWith<T, Params>,
  >(
    pageFunction: Func | string,
    ...args: Params
  ): Promise<HandleFor<Awaited<ReturnType<Func>>>>;
}

其中每个部分都对应一段明确语义：

组成	含义
pageFunction: Func | string	以当前句柄引用的对象作为第一个参数参与求值的函数；也可以传入字符串形式的表达式
...args: Params	从 Node.js 侧传入的额外参数，会作为 pageFunction 的后续实参
Params extends unknown[]	类型层面的参数元组约束
Func extends EvaluateFuncWith<T, Params>	求值函数类型，T 即当前句柄的泛型类型
返回 Promise<HandleFor<Awaited<ReturnType<Func>>>>	对函数返回类型先取 Awaited（自动展开 Promise），再交给 HandleFor 决定返回句柄的具体形态

返回值类型 HandleFor 的分派规则

返回类型并非恒定的 JSHandle，而是由 common/types.ts 中定义的 HandleFor 条件类型决定：

export type HandleFor<T> = T extends Node ? ElementHandle<T> : JSHandle<T>;

也就是说：当函数返回值是一个 DOM 节点（Node）时，方法返回的是功能更丰富的 ElementHandle；否则返回通用 JSHandle。这意味着 evaluateHandle(() => document.body) 会得到一个可直接调用 click()、screenshot() 等元素级 API 的 ElementHandle。

与 JSHandle.evaluate() 的关键差异

对比同一类上相邻定义的 JSHandle.evaluate()，二者的函数体几乎一致（源码见 JSHandle.ts）：

async evaluate(pageFunction, ...args): Promise<Awaited<ReturnType<Func>>> {
  pageFunction = withSourcePuppeteerURLIfNone(this.evaluate.name, pageFunction);
  return await this.realm.evaluate(pageFunction, this, ...args);
}

async evaluateHandle(pageFunction, ...args): Promise<HandleFor<Awaited<ReturnType<Func>>>> {
  pageFunction = withSourcePuppeteerURLIfNone(this.evaluateHandle.name, pageFunction);
  return await this.realm.evaluateHandle(pageFunction, this, ...args);
}

从源码可以归纳出三点差异：

1. 前者返回序列化值，后者返回远程引用：evaluate() 把结果对象按可序列化部分拷贝回 Node.js 侧（原始值、数组、可 JSON 化的普通对象等）；evaluateHandle() 则在页面里保留对象本身，仅在 Node.js 侧持有一个轻量引用。
2. 后者能承载不可序列化对象：Map、Set、WeakMap、Proxy、函数、window、DOM 节点等对象无法安全序列化往返，却可以被句柄安全引用。正因如此，CDP 层的注释直接点明该方法"更适合对象无法被序列化（例如 Map）且需要进一步操作的场景"。
3. 前者依赖 returnByValue，后者依赖句柄转换：在 CDP 实现中，二者本质是同一个 #evaluate() 私有方法的两种调用，区别仅在于传给协议层的 returnByValue 布尔标志（详见下文"底层实现"）。

注意：二者共享 EvaluateFuncWith<T, Params> 类型——当前句柄的泛型 T 会作为求值函数第一个参数的类型。当你在一个 JSHandle<Window> 上调用 evaluateHandle 时，第一个形参会被推导为 Window。

典型使用方式与实战示例

持有 DOM 节点

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.setContent('<div>Hello Puppeteer</div>');

// evaluateHandle 返回句柄；由于结果是 Node，句柄实际是 ElementHandle
const bodyHandle = await page.evaluateHandle(() => document.body);
const divHandle = await page.evaluateHandle(() => document.querySelector('div'));
console.log(bodyHandle.constructor.name); // ElementHandle

// 句柄可以直接传给下一次求值，在函数中作为第一个实参被还原
const text = await bodyHandle.evaluate((body) => body.innerText);
console.log(text); // Hello Puppeteer

await browser.close();

保留不可序列化对象（Map / Set / 函数）

const mapHandle = await page.evaluateHandle(() => new Map([['key', 'value']]));

// 序列化会丢信息，但句柄可原样传回页面
const keyCount = await mapHandle.evaluate((m) => m.size);
console.log(keyCount); // 1

await mapHandle.dispose();

这一行为有测试用例佐证：在 test/src/jshandle.test.ts 中，测试覆盖了"句柄接受不可序列化值"——例如 evaluateHandle(() => Infinity) 后通过 page.evaluate(e => Object.is(e, Infinity), aHandle) 验证引用还原正确，也覆盖了向 evaluateHandle 传入含循环引用的对象时抛出 Recursive objects are not allowed. 错误的行为。

作为 page.evaluate 的参数传递

句柄可用作任何求值 API（如 Page.evaluate、Page.$eval、Page.evaluateHandle）的实参，在页面内会被自动还原为其引用的对象：

const navigatorHandle = await page.evaluateHandle(() => navigator);
const ua = await page.evaluate((nav) => nav.userAgent, navigatorHandle);
console.log(ua); // 以 'Mozilla' 开头的 UA 字符串

对应的测试见 jshandle.test.ts 中 'should accept object handle as an argument' 用例。

传参支持：把参数当成表达式字符串执行

与 evaluate 一样，pageFunction 也可以直接是字符串表达式。句柄字符串表达式同样返回句柄，这在 toString() 测试里体现得很直观：await page.evaluateHandle('12')、await page.evaluateHandle('Symbol()')、await page.evaluateHandle('new Map()') 会分别得到标识为 JSHandle:12、JSHandle@symbol、JSHandle@map 的句柄（见 jshandle.test.ts）。

源码层面，当 pageFunction 是字符串时，CDP 执行上下文会先通过 withSourcePuppeteerURLIfNone 为表达式补充 //# sourceURL 注释，再走 Runtime.evaluate 通道；当它是函数时则走 Runtime.callFunctionOn 通道（详见 cdp/ExecutionContext.ts）。因此两种形式在性能与可调试性上有差异——函数形式支持源码映射与断点定位，是官方推荐的默认方式；字符串形式适合调试或快速验证。

句柄生命周期与内存管理

句柄引用会阻止页面内对象被垃圾回收，因此必须显式释放。整个生命周期规则定义在 JSHandle.ts 的类注释中：

• 句柄可通过 Page.evaluateHandle 等 API 创建；
• 未释放的句柄会阻止其引用对象被 GC；调用 dispose() 后释放；
• 当句柄所属 frame 发生导航、或父级上下文被销毁时，句柄会被自动释放；
• 句柄可作为任何求值函数的参数，并在函数内解析为原对象。

推荐使用 TypeScript/现代 JS 的显式资源管理语法（using / await using）来自动释放：

// 'using' 声明的句柄在离开作用域时自动调用 Symbol.dispose
using windowHandle = await page.evaluateHandle(() => window);
// ... 使用 windowHandle ...
// 离开作用域后句柄自动释放

// 更显式的写法
const bodyHandle = await page.evaluateHandle(() => document.body);
try {
  // 业务逻辑
} finally {
  await bodyHandle.dispose(); // 或者 bodyHandle[Symbol.dispose]()
}

对应测试见 jshandle.test.ts 中 JSHandle[Symbol.dispose] 与 JSHandle[Symbol.asyncDispose] 两组用例——它们验证句柄同时实现了 Symbol.dispose 与 Symbol.asyncDispose，且离开作用域时会自动触发释放。此外类上的 @moveable 装饰器提供了 move() 方法，用于在自动释放作用域间安全转移句柄所有权，避免提前释放导致悬垂引用（如 getProperties() 内部就使用了 property.handle.move()）。

底层实现原理：进入 CDP 层

抽象基类 JSHandle.evaluateHandle 只是门面，真正的求值委托给当前句柄所在的 Realm（页面 Frame、worker、扩展 realm 等执行环境）。Realm 又进一步将工作下沉到 CDP/BiDi 协议层。

以 Chromium CDP 路径为例，cdp/ExecutionContext.ts 中 evaluate 与 evaluateHandle 共用同一个 #evaluate(returnByValue, pageFunction, ...args)：

async #evaluate(
  returnByValue: true,
  pageFunction: Func | string,
  ...args: Params
): Promise<Awaited<ReturnType<Func>>>;
async #evaluate(
  returnByValue: false,
  pageFunction: Func | string,
  ...args: Params
): Promise<HandleFor<Awaited<ReturnType<Func>>>>;

• 函数形式：将函数与参数序列化为 Runtime.callFunctionOn 调用，objectId 指向当前句柄的 RemoteObject，returnByValue 设为 false，并带 awaitPromise: true（自动等待 Promise 决议）与 userGesture: true；
• 字符串形式：改用 Runtime.evaluate，仅传入表达式字符串与上下文 id；
• 结果处理：协议返回的是 RemoteObject。当 returnByValue === false 时，代码调用 this.#world.createCdpHandle(remoteObject) 把它包装为 JSHandle/ElementHandle 并返回（见 ExecutionContext.ts）——这就是 Node.js 侧"句柄"的直接来源。

两个设计细节值得留意：

1. 因为 evaluateHandle 不要求 JSON 序列化，传参时可以保留 BigInt、Infinity、-0 等不可 JSON 序列化的值（convertArgument 会用 CDP 的 unserializableValue 通道传输）；而含循环引用的对象则会被拒绝，并附加 ' Recursive objects are not allowed.' 的错误信息（ExecutionContext.ts）。
2. 测试中常见到 page.evaluateHandle('new Set()') 之后立刻用 using 释放——这正好演示了"远程对象 + 本地引用"的资源模型：协议层的 RemoteObject 与 Node.js 侧的句柄一一对应，句柄 dispose() 本质是向协议层发出 release 请求。

常见问题与最佳实践

Q：什么时候该用 evaluateHandle()，而不是 evaluate()？ 当结果需要被"再次传回页面"做多轮操作、或对象本身不可序列化（Map/Set/DOM/函数）时用 evaluateHandle()；当只需要一次性的值（字符串、数字、简单 JSON）时用 evaluate()，避免泄漏句柄。

Q：句柄会不会造成内存泄漏？ 会，如果一直不释放。务必在 finally 或 using 作用域中释放；frame 导航、上下文销毁时会自动清理，但不要把自动清理当作常态依赖。

Q：拿到的"句柄"一定是 JSHandle 吗？ 不一定。由 HandleFor 分派，返回 DOM 节点时是 ElementHandle，可继续使用 ElementHandle.click、ElementHandle.asLocator 等元素级 API；用 JSHandle.asElement() 可在运行时判断或转换。

Q：传字符串和传函数有什么区别？ 字符串走 Runtime.evaluate，函数走 Runtime.callFunctionOn 并携带源码 URL 注释（便于在 DevTools 中定位）。函数形式类型更安全、可调试性更好，是默认推荐。

参考资料

• API 文档：JSHandle.evaluateHandle、JSHandle.evaluate、Page.evaluateHandle、HandleFor、EvaluateFuncWith
• 实现源码：api/JSHandle.ts、api/Realm.ts、cdp/ExecutionContext.ts、common/types.ts
• 测试用例：test/src/jshandle.test.ts