Puppeteer Realm.evaluate() 深度解析：在页面执行上下文中运行函数并取回结果

Realm.evaluate() 是 Puppeteer 中"在一个 JavaScript 执行上下文（Realm）内运行任意函数并取回返回值"的底层抽象方法。本文围绕 Realm.evaluate 官方 API 文档，结合仓库内 Realm 抽象基类及其 CDP / WebDriver BiDi 实现源码，讲清它的方法签名、Promise 自动解包语义、JSHandle 参数传递、与 evaluateHandle 的区别，以及它如何被 Page、Frame、Worker 等高层 evaluate 方法复用。读完你将理解 Puppeteer 求值体系的统一入口，并能写出类型安全、可复现的页面函数求值代码。

Realm 是什么：Puppeteer 对"执行上下文"的抽象

在进入 evaluate 之前，需要先明确 Realm 在 Puppeteer 中的地位。根据 Realm 类文档，Realm 是一个抽象类，其构造函数被标记为 internal，第三方代码不应直接实例化或继承它。它代表一个可以执行 JavaScript 的"领域"——通常对应浏览器内部的一个 JavaScript 执行上下文。

在源码 api/Realm.ts 中可以看到它的骨架：

export abstract class Realm {
  /** @internal */
  protected readonly timeoutSettings: TimeoutSettings;
  /** @internal */
  readonly taskManager = new TaskManager();

  /** @internal */
  constructor(timeoutSettings: TimeoutSettings) {
    this.timeoutSettings = timeoutSettings;
  }
}

• timeoutSettings：求值（含 waitForFunction 的默认超时）所需的超时配置；
• taskManager：管理该 Realm 内的等待任务，当 Realm 被 dispose() 时会调用 taskManager.terminateAll(...) 终止仍在运行的任务（见 api/Realm.ts）。

Realm 抽象类声明的核心成员包括（见 Realm 类文档 的方法表）：evaluate、evaluateHandle、waitForFunction、extension()，以及实验性只读属性 origin（当 Realm 由扩展 content script 创建时返回扩展源）。此外从源码看还有 adoptHandle、transferHandle、adoptBackendNode 等被标记为 @internal 的句柄迁移方法（api/Realm.ts）。

谁实现了 Realm？

在当前仓库中，Realm 有两条协议通道的实现：

• CDP（Chrome DevTools Protocol）通道：cdp/IsolatedWorld.ts 中的 export class IsolatedWorld extends Realm。Frame 通过 mainRealm()（主世界）和 isolatedRealm()（隔离世界）分别暴露两个 IsolatedWorld 实例（见 cdp/Frame.ts）；
• WebDriver BiDi 通道：bidi/Realm.ts 中的 abstract class BidiRealm extends Realm，其下有 WindowRealm、DedicatedWorkerRealm、SharedWorkerRealm 等核心实现（见 bidi/core/Realm.ts）。

也就是说，"在某个 Realm 里求值" 最终会落到 CDP 的 Runtime.evaluate 或 BiDi 的对应调用上——这正是 Realm.evaluate 统一对外提供的抽象入口。

Realm.evaluate 方法签名与语义

Realm.evaluate 文档 给出的核心语义是：

Evaluates a function in the realm's context and returns the resulting value.（在 Realm 的上下文中执行一个函数，并返回其结果值。）

方法签名（与源码 api/Realm.ts 一致）：

abstract evaluate<
  Params extends unknown[],
  Func extends EvaluateFunc<Params> = EvaluateFunc<Params>,
>(
  pageFunction: Func | string,
  ...args: Params
): Promise<Awaited<ReturnType<Func>>>;

这里有几个值得注意的设计点：

1. abstract：Realm 只声明契约，实际求值逻辑由上文提到的 IsolatedWorld / BidiRealm 等子类实现；
2. pageFunction: Func | string：既可以传一个真正的函数，也可以传一个字符串形式的 JavaScript 表达式（此时相当于在页面里执行这段脚本）；
3. 泛型参数全自动推导：Params 由实际传入的 args 推导，Func 默认取 EvaluateFunc<Params>，因此返回值类型 Promise<Awaited<ReturnType<Func>>> 能精确反映函数真实的返回值类型。

参数详解

参数	类型	说明
pageFunction	Func | string	需要在 Realm 上下文中执行的函数。它会在浏览器侧、而非 Node.js 侧运行，因此闭包捕获的 Node 变量不可见，必须通过 args 显式传入；若传字符串，则当作 JavaScript 表达式直接在 Realm 中求值
args	Params	传给 pageFunction 的参数。除了可序列化的普通值（number、string、boolean、object、array 等），还可以传入 JSHandle 句柄，此时句柄会被解析为其引用的真实对象后再传给函数

返回值

返回 Promise<Awaited<ReturnType<Func>>>——即 resolve 为 pageFunction 返回值的一个 Promise。Awaited 这一层类型包装正是为了体现下面的语义：如果函数返回一个 Promise，方法会等待该 Promise 落定，并把最终值交给调用方。

关键语义一：返回 Promise 时自动等待

文档明确说明：

If the function passed to realm.evaluate returns a Promise, the method will wait for the promise to resolve and return its value.（如果传给 realm.evaluate 的函数返回 Promise，该方法会等待 Promise 解析并返回其值。）

这意味着你在页面侧写的异步逻辑可以直接返回，外层 await 拿到的就是最终结果，而不需要像某些原始协议那样手动管理 awaitPromise 标志。文档示例：

const result = await realm.evaluate(() => {
  return Promise.resolve(8 * 7);
});
console.log(result); // prints "56"

即便 pageFunction 内部没有 async 关键字，只要它返回一个 Promise（例如 Promise.resolve(...) 或异步 DOM API 的结果），realm.evaluate 都会帮你解包。

从源码结构看，CDP 通道正是借助 Runtime.evaluate 协议调用完成这一步——ExecutionContext 最终通过 client.send('Runtime.evaluate', {...}) 发送请求，并依据 returnByValue 标志决定返回原始值还是句柄（见 cdp/ExecutionContext.ts）。

关键语义二：JSHandle 可以作为参数传入

文档指出：

JSHandle instances can be passed as arguments to the function.（JSHandle 实例可以作为参数传给函数。）

例如你先拿到一个 DOM 元素的句柄，再把它传给求值函数使用（示例来自 ExecutionContext.evaluateHandle 文档注释 的同款用法）：

const bodyHandle = await realm.evaluateHandle(() => {
  return document.body;
});
const innerHtml = await realm.evaluate(
  body => body.innerHTML, // 句柄会被解析为其引用的 body 元素
  bodyHandle,
);
await bodyHandle.dispose();

这一行为由类型系统保证：在 common/types.ts 中定义了 HandleOr、FlattenHandle、InnerParams 与 EvaluateFunc：

export type HandleOr<T> = HandleFor<T> | JSHandle<T> | T;
export type FlattenHandle<T> = T extends HandleOr<infer U> ? U : never;
export type InnerParams<T extends unknown[]> = {
  [K in keyof T]: FlattenHandle<T[K]>;
};
export type EvaluateFunc<T extends unknown[]> = (
  ...params: InnerParams<T>
) => Awaitable<unknown>;

也就是说，你在 pageFunction 参数位置标注的类型即使写的是普通 DOM 类型，实参仍然可以传对应元素的 ElementHandle——框架会负责在跨进程边界时把它解析成真正可用的对象。这让 evaluate 既能传纯数据，也能"搬运"页面对象引用，同时保持 TS 类型安全。

提醒：句柄与页面对象一样占用资源，用完后应调用 dispose() 释放（官方注释也强调 "Always dispose your garbage! :)"）。

传字符串表达式

除了函数，pageFunction 还可以是字符串。对应 CDP 实现（cdp/ExecutionContext.ts 附近的 isString(pageFunction) 分支）以及 jsHandle 相关的字符串求值示例都支持这种形式。例如：

const one = await realm.evaluate('1 + 1'); // 数字表达式，返回 2

字符串形式适合动态拼接简单表达式，但维护性与可读性不如函数形式；涉及外部数据时务必自行序列化，避免注入风险。

与 evaluateHandle 的区别：取"值"还是取"句柄"

Realm 上有两个容易混淆的求值方法（见 Realm 类文档 方法表，以及 Realm.evaluateHandle 文档）：

• evaluate：把结果序列化为普通 JS 值返回（Promise<Awaited<ReturnType<Func>>>）。适合返回数字、字符串、可序列化对象等"按值"使用的场景；
• evaluateHandle：把结果包装成 JSHandle（Promise<HandleFor<Awaited<ReturnType<Func>>>>）返回，对象本身不离开页面，后续仍可通过句柄继续操作或再次传给别的求值函数。适合返回 Node、Map、函数等无法直接序列化、或需要继续在页面内操作的对象。

类型层面二者也对应了不同的返回值：HandleFor<T> = T extends Node ? ElementHandle<T> : JSHandle<T>（见 common/types.ts），即当结果本身是 DOM Node 时自动返回 ElementHandle。

一个记忆口诀：只想要数据用 evaluate，想继续在页面里"抓住"对象用 evaluateHandle。

底层调用链：Realm.evaluate 是如何落到协议的

以 CDP 通道为例，调用链可以概括为三层（从 cdp/IsolatedWorld.ts 可以完整看到）：

1. Realm.evaluate（抽象契约） → 由 IsolatedWorld 实现；
2. IsolatedWorld.evaluate(...) 先获取其绑定的 ExecutionContext（若执行上下文尚未就绪则通过 #waitForExecutionContext() 等待），再调用 context.evaluate(pageFunction, ...args)；
3. ExecutionContext 内部区分 returnByValue 走 #evaluate 私有方法，最终通过 Runtime.evaluate 协议消息与浏览器通信，并对基本类型远程对象做 valueFromPrimitiveRemoteObject 转换（见 cdp/ExecutionContext.ts）。

在 BiDi 通道中，等价逻辑由 BidiRealm 实现（bidi/Realm.ts），其内部进一步细分为 WindowRealm、DedicatedWorkerRealm、SharedWorkerRealm 等，分别对应当前标签页主世界、专用 Worker、共享 Worker 的执行环境。

高层 API 对 Realm.evaluate 的复用

Realm.evaluate 也是 Puppeteer 各高层求值 API 的公共底座。从源码结构看：

• Page.evaluate / Frame.evaluate 最终会委托给对应 Frame 的 Realm（主世界或隔离世界）执行。例如 CDP 的 Frame 暴露 mainRealm() 与 isolatedRealm()（见 cdp/Frame.ts），Page 内部大量逻辑经由 .mainRealm() / .isolatedRealm() 完成求值（见 cdp/Page.ts 与 cdp/Page.ts）；
• Web Worker 也持有自己的 Realm：WebWorker.mainRealm(): Realm（见 cdp/WebWorker.ts），因此 Worker 内同样可以走 Realm 求值体系。

这解释了为什么不同执行环境（主页面、iframe、隔离世界、Worker）都能使用风格一致的 evaluate 语义：它们共享的是同一套 Realm 抽象。

使用注意事项

1. 作用域隔离：pageFunction 运行在浏览器 Realm 中，不能直接引用 Node.js 侧的变量（如 fs、进程环境变量）。需要传入数据时一律走 args；在函数体内拼接外部变量属于常见错误。
2. 返回值必须可序列化：evaluate 是"按值"返回，遇到无法序列化的对象（如 DOM 节点、Map 的某些表示、函数）应改用 evaluateHandle 拿到句柄，再按需 jsonValue() 或继续传入下一次求值。
3. 句柄生命周期：传入的 JSHandle 参数在用完后记得 dispose()；句柄与不同 Realm 之间默认不能直接混用，源码中 Realm 提供的 adoptHandle / transferHandle（@internal）即用于跨 Realm 迁移句柄（api/Realm.ts）。
4. 超时与销毁：Realm 内等待类任务（waitForFunction）会受 timeoutSettings 约束；当 Realm 对应的 frame 被 detach、页面被关闭时，dispose() 会终止其中未完成的等待任务并抛出 waitForFunction failed: frame got detached. 之类的错误（见 api/Realm.ts）。因此长生命周期脚本要妥善处理页面导航 / 关闭带来的 Realm 失效。
5. 字符串求值的边界：以字符串传入时它会在目标 Realm 中作为表达式解析，需自行负责转义与安全，优先使用函数 + 参数的形式。

参考资源

• 本方法原始 API 文档：docs/api/puppeteer.realm.evaluate.md
• Realm 类总览（属性 / 方法表）：docs/api/puppeteer.realm.md
• 姊妹方法（返回句柄版）：docs/api/puppeteer.realm.evaluatehandle.md
• 句柄 API：docs/api/puppeteer.jshandle.md
• 抽象基类实现：api/Realm.ts
• CDP 实现与协议衔接：cdp/IsolatedWorld.ts、cdp/ExecutionContext.ts
• BiDi 实现：bidi/Realm.ts、bidi/core/Realm.ts
• 相关类型定义（EvaluateFunc、InnerParams、HandleFor）：common/types.ts