Playwright Locator vs ElementHandle：查询还是句柄

有个现象大概每个写过一阵子 Playwright 的人都遇到过：一段点击代码，之前一直好好的，某次页面改了个渲染方式，它就开始间歇性地抛 Element is not attached to the DOM。翻代码发现，出问题的那几行长这样（这段是仓库 docs/src/handles.md 里的原文示例）：

const handle = await page.$('text=Submit');
// ...
await handle.hover();
await handle.click();

而没出问题的地方长这样（同一篇文档的下半段）：

const locator = page.getByText('Submit');
// ...
await locator.hover();
await locator.click();

两段代码从字面上看几乎一模一样，中间都有个 // ... 表示”这里还干了点别的”。差别不在写法上，在这两个对象各自是什么东西。仓库 docs/src/handles.md 的 “Locator vs ElementHandle” 一节把这句话写得很直接：ElementHandle 指向某一个具体元素，而 Locator 装的是”怎么把那个元素找出来”的逻辑。

这句话有点抽象。往源码里看一眼就具体了。

第一层：Locator 的构造函数什么都没做

packages/playwright-core/src/client/locator.ts 里的 class Locator，构造函数只干了一件事——往两个字段上赋值：

constructor(frame: Frame, selector: string, options?: LocatorOptions) {
  this._frame = frame;
  this._selector = selector;

后面那一串 options 分支也不例外，它们把过滤条件拼成更长的选择器字符串，比如 hasText 会追加 >> internal:has-text=...，has 会追加 >> internal:has= 加上内层 locator 的 _selector 序列化结果。也就是说，page.getByText('Submit') 这一行执行完，Playwright 跟浏览器之间连一次通信都没发生。它手里只有一个 frame 引用和一个字符串。

这就是惰性求值的字面含义：定位这件事被推迟到你真正对它做什么的时候。

对照之下，page.$() 是即时的。仓库 docs/src/api/class-page.md 里 Page.querySelector（JS 别名 $，Python 别名 query_selector）的返回类型写的是 <[null]|[ElementHandle]>，正文写明：没有元素匹配时返回值 resolve 成 null；要等元素出现，用 Locator.waitFor。这一句其实已经把话说明白了——它是一次性的快照查询，不等，查不到就给你 null。

docs/src/handles.md 也给出了另一条取句柄的路子：需要 ElementHandle 时，推荐用 Page.waitForSelector 或 Frame.waitForSelector 去拿，文档说这两个 API 会等到元素 attached 且 visible。但注意，它等的是”取到句柄的那一刻”，取到之后，这个句柄就跟当时那个 DOM 节点绑死了。

第二层：动作发生时，两条路走的是不同的入口

回到 locator.ts，看 click 的实现：

async click(options: channels.ElementHandleClickOptions & TimeoutOptions = {}): Promise<void> {
  return await this._frame.click(this._selector, { strict: true, ...options });
}

传给下游的是 this._selector——一个字符串，不是元素。而且 strict: true 是在这里硬写死的。仓库 docs/src/locators.md 的 “Strictness” 一节讲的就是这个：所有隐含单个目标元素的 locator 操作，匹配到多于一个元素时会抛异常；而像 count() 这种明确的多元素操作则不受影响。相比之下，Page.querySelector 的 strict 只是个可选项，仓库 docs/src/api/params.md 里对它的描述是”为 true 时要求选择器解析到单个元素”，并没有写默认值。

选择器字符串一路传到服务端，落进 packages/playwright-core/src/server/frames.ts 的 _retryWithProgressIfNotConnected。这个方法名基本就是文档：它在一个重试循环里，每一轮都重新调用 this.selectors.callOnSelectorHandle(selector, ...) 去解析一次，拿到元素后才执行动作。日志里那句 waiting for <locator> 也是这里打出来的。

ElementHandle 走的是另一条：packages/playwright-core/src/server/dom.ts 里 ElementHandle 自己的 click，直接对手里这个节点做 _retryPointerAction。它也重试，但重试的是指针动作本身（可见性、命中检测这些），不会重新去页面里找元素——它没有选择器可以拿去找。

第三层：元素脱离 DOM 的那一刻，分岔在这里

这是我认为最值得看的一处。两个类的 API 文档里，写着同一句话。docs/src/api/class-elementhandle.md 的 ElementHandle.click：

If the element is detached from the DOM at any moment during the action, this method throws.

docs/src/api/class-locator.md 的 Locator.check 等方法下面，是逐字相同的一句。

但源码里，这两条路径对同一个内部结果的处置是不一样的。服务端用一个字符串常量 'error:notconnected' 表示”元素已经不在 DOM 上了”。

在 frames.ts 的 _retryWithProgressIfNotConnected 里，动作返回这个值时：

if (result === 'error:notconnected') {
  if (noAutoWaiting)
    throw new dom.NonRecoverableDOMError('Element is not attached to the DOM');
  progress.log('element was detached from the DOM, retrying');
  return continuePolling;
}

它记一条日志，然后继续轮询——下一轮会拿着选择器重新解析一遍，找到新元素接着做。

而在 dom.ts 里，ElementHandle.click 拿到同样的结果之后：

const result = await this._click(progress, { ...options, waitAfter: !options.noWaitAfter });
return assertDone(throwRetargetableDOMError(result));

throwRetargetableDOMError 的实现就在同一个文件下方，遇到 'error:notconnected' 就调 throwElementIsNotAttached()，抛出 Element is not attached to the DOM——正是文章开头那条报错。

我只把这两处放在一起指出：文档对两个类写了同一句”会抛”，源码里 locator 这条路径在抛之前多了一次重新解析的机会。至于官方是出于什么考量这么写文档，仓库里没有找到相关说明，我不替作者解释。

顺带说一句，throwRetargetableDOMError 这个函数名里的 retargetable（可重新指向）也挺说明问题：能不能”重新指向”，取决于你手里有没有那个查询逻辑。

官方标 discouraged 时给的原话

docs/src/api/class-elementhandle.md 的类说明顶部就有一个警告框，逐字是：ElementHandle 的使用是 discouraged 的，请改用 Locator 对象与 web-first 断言。往下翻，这个类几乎每个方法上都挂了一行 discouraged: 元数据，绝大多数是”改用对应的 Locator.xxx”。

有两处给了具体理由，值得单独摘出来。一处在 docs/src/api/class-locator.md 的 Locator.elementHandle 上——就是那个从 locator 反向拿句柄的方法：

discouraged: Always prefer using [Locator]s and web assertions over [ElementHandle]s because latter are inherently racy.

inherently racy，天生带竞态。另一处在 ElementHandle.evalOnSelector（JS 别名 $eval，Python 别名 eval_on_selector）上，理由是这个方法不会等待元素通过可操作性检查，因此可能导致测试不稳定。

docs/src/handles.md 里还有一个 caution 框，划出了官方认可的适用范围：只建议在需要对静态页面做大量 DOM 遍历这种少见情况下用 ElementHandle，所有用户动作和断言都该用 locator。这是仓库文档自述的边界，不是我的推断。

生命周期：谁在收拾这些句柄

docs/src/handles.md 的 “Handle Lifecycle” 一节写明：句柄创建之后会把对象从垃圾回收中保留下来，除非页面发生导航，或者你手动调 JSHandle.dispose。class-elementhandle.md 的类说明补了一条：ElementHandle 在其所属 frame 发生导航时会自动 dispose。

有意思的是 locator 这一侧。locator.ts 里有个私有方法 _withElement，boundingBox() 这类需要真实节点的操作走的是它：

const result = await this._frame._channel.waitForSelector({ selector: this._selector, strict: true, state: 'attached' }, { signal: options.signal, timeout });
const handle = ElementHandle.fromNullable(result.element) as ElementHandle<SVGElement | HTMLElement> | null;
if (!handle)
  throw new Error(`Could not resolve ${this._selector} to DOM Element`);
try {
  return await task(handle, deadline ? deadline - monotonicTime() : 0);
} finally {
  await handle.dispose();
}

它内部照样要句柄，只是借完就在 finally 里还掉了。你从来不持有它，所以也没有机会让它变陈旧。

一个例外：Locator.all() 不是惰性的

别把”locator 总是惰性”当成绝对规律。docs/src/api/class-locator.md 里 Locator.all 带了一个 note 明确写着：这个方法不会等待元素匹配，而是立刻返回页面里当下存在的东西；当元素列表动态变化时，它会产生不可预测且不稳定的结果。文档给的处置是：列表稳定但异步加载时，先等整个列表加载完再调它。

这一条正好呼应前面：all() 返回的是一组已经定死的 locator，那一瞬间的求值结果被固化了下来。它和 ElementHandle 的陈旧问题不完全是一回事，但踩坑的姿势很像。

落到写代码上

如果只想记一条判断规则：手里握着的是”元素”还是”找元素的办法”。握着元素，页面重渲染就把你甩了；握着办法，每次用都重新找一遍。

如果你确实碰上文档说的那种情形——静态页面、大量 DOM 遍历——需要从 locator 拿句柄，仓库里的接口是 Locator.elementHandle（docs/src/api/class-locator.md 里签名标着 since: v1.14，返回 <[ElementHandle]>，正文写明：解析到第一个匹配的 DOM 元素；没有匹配就等；有多个匹配就抛）和 Locator.elementHandles（返回数组，没有匹配时返回空列表）。两者都挂着上面那句 racy 的 discouraged 说明。各语言绑定的方法名按各自命名惯例转写，具体拼法请以对应语言的 API 文档为准，别拿 JS 的写法直接套到 Python 上。

顺带一提版本线索：class-elementhandle.md 顶部标的是 since: v1.8，class-locator.md 标的是 since: v1.14。ElementHandle 是更早就在的那个，Locator 是后来加进来并成为推荐路径的。这只是仓库里记录的历史事实。

这条路径是纯 API 语义，仓库文档里没有为这两个类给出 Windows 与 Linux/macOS 的行为差异说明，所以本文也不区分平台。

最后放一段把上述接口语义组合起来的对照写法：

// 推荐路径：每次使用都重新定位
const submit = page.getByText('Submit');
await submit.click();

// 确需句柄时的路径，注意它被标为 discouraged
const handle = await page.getByText('Submit').elementHandle();
const box = await handle.boundingBox();
await handle.dispose();

以上为按仓库代码中的接口语义组合的示例，未经实测，以仓库最新代码为准。该项目持续更新，文中涉及的 API 签名、配置项与内部实现随版本变动，请以仓库最新内容为准。

---

本文依据 github.com/microsoft/playwright 仓库于 2026-08-18 的公开内容整理， 事实来自仓库内的文档与源码。我们没有对文中涉及的功能做过实测， 因此不涉及运行速度、稳定性与实际表现的任何描述。 该项目迭代频繁，文中涉及的 API 签名、配置项与默认值随版本变动，请以仓库最新内容为准。 本文不涉及浏览器版本矩阵与版本清单，相关信息请以官方发布说明为准。

本文对照的是同一项目内的两种用法，依据均为上述仓库内容，不对两种用法做优劣排名， 选型结论只在仓库文档写明的能力边界内成立。