弹出确认框后用例卡死：Playwright 里 dialog 的默认处置是什么

现象长什么样

一个「删除」按钮，点下去弹 confirm。用例跑到 click 那一行就再也不动了，既不报错也不继续，最后被外层超时掐断。更让人费解的是：同一段代码前几天还好好的，你只是”顺手加了一行日志”，想看看弹窗里到底写了什么。

这个”顺手加的一行”往往就是原因本身。Playwright 仓库 docs/src/dialogs.md 里专门用一段标着 WRONG! 的代码演示了它：

page.on('dialog', dialog => console.log(dialog.message()));
await page.getByRole('button').click(); // Will hang here

原样抄自该文件。它给出的解释是：Page.dialog 的监听必须处置这个 dialog，否则你的动作会停住，因为 Web 里的 dialog 是模态的，会阻塞页面后续执行直到被处置。docs/src/api/class-dialog.md 的注记说得更直白——监听存在时必须调用 Dialog.accept 或 Dialog.dismiss，否则页面会一直冻结等着，click 这类动作永远不会结束。

注意「永远不会结束」和「超时失败」是两种不同的形态。前者不是元素找不到，而是浏览器那一侧根本没往下走。

先确认是不是它

有几个可以直接执行的判定动作，按代价从低到高排。

第一，把监听换成会处置的版本再跑一次。 临时把日志监听改成既打印又处置：

page.on('dialog', async dialog => {
  console.log(dialog.type(), dialog.message());
  await dialog.dismiss();
});

以上为按仓库代码中的接口语义组合的示例，未经实测，以仓库最新代码为准。Dialog.type() 与 Dialog.message() 的签名在 docs/src/api/class-dialog.md 里都能查到，前者的返回值文档写明是 alert、beforeunload、confirm、prompt 四者之一，packages/playwright-core/src/server/dialog.ts 里的 DialogType 类型定义与这四个取值一致。如果改完之后用例往下走了，同时日志里打出了弹窗文案，基本可以定案。

第二，看有没有那条特定的报错。 packages/playwright-core/src/server/dialog.ts 的 DialogManager.dialogDidOpen 里，dialog 一打开就会让该页所有 frame 上正在进行的非阻塞求值失效，抛出的错误信息逐字是 JavaScript dialog interrupted evaluation。你在日志里搜到这句，说明确实有原生 dialog 弹出来了。

第三，用有头模式肉眼看。 JS 端的 npx playwright test --headed 在 docs/src/test-cli-js.md 的参数表里写明是「以有头浏览器运行测试（默认 headless）」。该文件给出的这条命令没有区分操作系统写法，Windows 的 PowerShell / cmd 与 Linux、macOS 侧照抄同一行即可（仓库里我们没有找到针对该参数的平台差异说明）。以有头模式复现一次，如果屏幕上确实杵着一个系统级弹窗，就不用再猜了。仓库里另有 Page.dialogClosed 事件（docs/src/api/class-page.md 标注自 v1.63 起可用），其说明里提到 dialog 也可能是「在有头浏览器里由用户手动关闭」的——这也从侧面说明有头模式下弹窗确实会真的显示出来。

仓库给出的处置

不注册监听时会发生什么

这是最容易被误解的一层。docs/src/dialogs.md、docs/src/api/class-dialog.md、docs/src/api/class-page.md、docs/src/api/class-browsercontext.md 四处都写了同一层注记，措辞略有出入：docs/src/dialogs.md 与 docs/src/api/class-dialog.md 只提 Page.dialog，class-page.md 与 class-browsercontext.md 写的是「Page.dialog 与 BrowserContext.dialog 都没有监听时」，落点一致——没有监听时所有 dialog 会被自动处置掉。也就是说不管它反而不会卡，卡是因为你管了一半。

这里有一处值得把两边放在一起看：文档统一的措辞是「自动 dismiss」，而 packages/playwright-core/src/server/dialog.ts 里兜底用的 Dialog._close() 写的是——类型为 beforeunload 时走 _accept()，其余类型才走 _dismiss()。同文件的 DialogManager.dialogDidOpen 在遍历完所有 handler 后，若 hasHandlers 为假就调用 dialog._close()。文档措辞与这段实现对 beforeunload 的处置方向并不一致，这里只把两处指出来，不替作者解释原因。

监听必须放在触发动作之前

docs/src/dialogs.md 的原话是：在触发 dialog 的那个动作之前注册处理器。顺序反了没有任何补救余地——动作已经在等，代码执行不到后面那行注册语句。仓库里的正确示例是两行紧挨着：

page.on('dialog', dialog => dialog.accept());
await page.getByRole('button').click();

Python 侧对应的写法在同一文件里，同步与异步两个版本都是 page.on("dialog", lambda dialog: dialog.accept())；C# 侧是 Page.Dialog += async (_, dialog) => { await dialog.AcceptAsync(); };；Java 侧是 page.onDialog(dialog -> dialog.accept());。跨语言迁移时按各自那一段抄，别把 JS 的写法直译过去。

只想处置一次的话，docs/src/events.md 有「一次性监听」一节，示例是 page.once('dialog', dialog => dialog.accept('2021'))（'2021' 是该文件里的示例值，不是什么约定俗成的取值）。注意这一节的 langs 标记是 js, python, java——C# 不在其列，C# 侧的增删走 += 与 -=。JS 移除监听用 page.off，Python 用 remove_listener，Java 用与 onXxx 对应的 offXxx，这几种写法都在 docs/src/events.md 里。

移除还有一处副作用值得知道：DialogManager.removeDialogHandler 在移除后发现 handler 集合空了，会把当前还开着的 dialog 全部 _close() 掉。所以”用完就摘掉监听”这个动作本身可能顺带关掉一个正开着的弹窗。

拿到 dialog 之后能问它什么

docs/src/api/class-dialog.md 列的方法不多：accept(promptText?)、dismiss()、message()、type()、defaultValue()、page()。两处细节容易踩：accept 的 promptText 参数文档写明”若 dialog 类型不是 prompt 则不产生任何效果”；defaultValue() 在非 prompt 时返回空串——所以拿它去判断类型是没用的，判类型请用 type()。

page() 这个方法标注自 v1.34 起可用，返回类型是 null 或 Page。为什么会是 null？packages/playwright-core/src/client/dialog.ts 的构造函数里留了一行注释，说页面初始化早期打开的 dialog 会阻塞初始化，因此必须在不带 page 的情况下把它上报出来。写通用处理器时对 page() 做空值判断不是多此一举。

beforeunload 特殊在哪

它和另外三种不是一回事。docs/src/api/class-page.md 里 Page.close 的说明写明：默认情况下 page.close() 不会运行 beforeunload 处理器；runBeforeUnload 这个选项文档写的默认值是 false（这是仓库当前文档里的默认值，随版本可能变动）。传 true 时它会运行 unload 处理器，但不等待页面真的关闭——docs/src/dialogs.md 补了一句，这是 Page.close 唯一不等待页面实际关闭的情形，因为操作结束时页面有可能还开着。

所以想让 beforeunload 弹出来必须主动要：

page.on('dialog', async dialog => {
  assert(dialog.type() === 'beforeunload');
  await dialog.dismiss();
});
await page.close({ runBeforeUnload: true });

原样抄自 docs/src/dialogs.md。Python 同步版在同一文件里是 page.close(run_before_unload=True)。这里要提醒一句：该文件 Python 两段示例注册监听写的是 page.on('dialog', lambda: handle_dialog)，与同一文件上方 page.on("dialog", lambda dialog: dialog.accept()) 的形参写法不一致，照抄之前先核对仓库最新内容。

服务端还有一个 DialogManager.closeBeforeUnloadDialogs()，只对类型为 beforeunload 的开着的 dialog 调 _dismiss()，其余类型不动。这也说明 beforeunload 在实现里确实被单独拎出来处理。

处置完怎么验证

• 原来卡住的那一行能走完，用例继续往下跑；
• 日志里能打出 dialog.type() 与 dialog.message()，说明监听真的被触发过，而不是碰巧没弹；
• 需要更硬的证据就监听 Page.dialogClosed（自 v1.63 起可用），确认关闭事件也发生了；
• 若走的是 BrowserContext 级别的 context.on('dialog')（自 v1.34 起可用），验证时要确认同一个上下文里其它页面的弹窗也被覆盖到了——文档那句注记是「Page.dialog 与 BrowserContext.dialog 都没有监听时才自动处置」，只在 context 上挂了个只打日志的监听，页面级照样会卡。

什么情况说明不是这个原因

• 卡住的是页面里的 HTML 模态框，比如 <div role="dialog"> 那种。它压根不走 Page.dialog，用定位器正常点关闭按钮即可；出现时机不固定的遮挡层，仓库提供的是 Page.addLocatorHandler（docs/src/api/class-page.md 标注自 v1.42 起可用），文档同时写明当遮挡层出现时机可预期时更推荐在用例里显式等待并关掉它。
• 打印对话框不算。docs/src/dialogs.md 把 Print dialogs 单列一节，给的办法是先 page.evaluate 覆盖 window.print，再用 page.waitForFunction 等待，并提示这段脚本要在点击之前、页面加载之后执行。走的完全不是 dialog 事件。
• 文件选择器不算。<input type=file> 触发的是 Page.fileChooser 事件（见 docs/src/api/class-page.md），与 dialog 是两套东西。
• 你压根没注册过 dialog 监听。按上面四处注记，无监听时会被自动处置掉，此时的卡住要往别处查。
• 报的是超时而不是永不结束。加了处置监听重跑仍然在同一处超时、且日志里既没有 dialog 类型也没有 JavaScript dialog interrupted evaluation 这句，那就是别的问题。

排查顺序其实很短：先确认有没有监听，再确认监听里到底有没有调 accept 或 dismiss，最后确认注册语句在触发动作之前。三步都对了还卡，就该怀疑别的方向了。

---

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