Playwright 四种调试手段怎么选：Inspector、UI Mode、Trace、日志

2026-08-18

用例挂了，你手上其实只有两个问题：一是当时页面长什么样，二是 Playwright 当时在等什么。Playwright 仓库里针对这两个问题给了四条路子——Playwright Inspector、UI Mode、Trace Viewer，以及 DEBUG 环境变量打出来的日志。这四个东西的文档分散在 docs/src/debug.md、docs/src/test-ui-mode-js.md、docs/src/trace-viewer.md 和 docs/src/ci.md 里，各自看都挺好用，凑到一起就容易选错。

下面只对照这几个文件里白纸黑字写明的机制。不排名，也不下”哪个更好”的结论。

第一条分界线：事中还是事后

这条线决定了一半的选择。

Inspector 是事中的。docs/src/debug.md 写明它是一个 GUI 工具，能让你逐步走完用例、实时编辑 locator、拾取 locator，并查看 actionability 日志。事中的含义是：脚本必须停在那里等你。文档里说，当 Playwright 在一次点击上暂停时，它已经做完了可操作性检查，检查过程会体现在日志里——元素是否可见、是否 enabled、是否 stable、locator 有没有解析到元素、有没有滚动进视口；如果可操作性一直达不到，这个动作会显示为 pending。

Trace Viewer 是事后的。docs/src/trace-viewer.md 开头就写明它用来在脚本跑完之后探索已录制的 trace，并且直接点名 trace 适合排查 CI 上的失败。事后的含义是：现场已经封存在一个 trace.zip 里，你什么时候看都行，看多少遍都行，但你不能改变它。

UI Mode 骑在两者中间。docs/src/test-ui-mode-js.md 说它把所有用例文件列在侧边栏里，可以按名称、project、@tag 或者 passed / failed / skipped 的状态过滤，运行之后能看到完整的 trace 并前后拖动。它还有 watch mode——每个用例名字旁边有个眼睛图标，点开之后改动这个用例就会重跑。所以它既是运行器又是回看器。

日志是流水账。docs/src/debug.md 里的 DEBUG=pw:api 输出的是 API 层面的详细日志；docs/src/ci.md 另外写明 DEBUG=pw:browser 用于排查 Error: Failed to launch browser 这类启动失败。日志没有画面，但它是唯一一种不需要任何图形环境的手段。

各自能看到什么

先说一个容易被忽略的重合：UI Mode 和 Trace Viewer 的面板几乎是同一套。两份文档里都各自列出了 Actions、Source、Call、Log、Errors、Console、Network、Metadata、Attachments 这些页签，描述文字也基本一致——Actions 里能看到每个动作用了哪个 locator，Call 里能看到是否处于 strict mode、按了哪个键，Console 里用不同图标区分日志来自浏览器还是来自用例文件，Network 里可以按状态码、方法、content type 等排序并展开请求与响应体。

真正只有 Trace Viewer 文档单独讲清楚的，是 snapshot 的三种类型。docs/src/trace-viewer.md 用一张表列明：Before 是动作被调用那一刻的快照，Action 是实际输入发生那一刻的快照（文档说这一类在你想搞清楚 Playwright 到底点在了哪里时特别有用），After 是动作之后的快照。同一份文档还提到，Action 快照会同时高亮 DOM 节点和精确的点击位置。这是”点了但没生效”这类问题最直接的证据。

UI Mode 这边独有的是 watch mode，以及把 DOM 快照弹成独立窗口的能力——文档说弹出之后可以打开浏览器 DevTools 去看 HTML、CSS、Console，还可以把两个动作分别弹出来并排比对。

Inspector 独有的是”暂停在这里，我现在去试”。要跳到指定位置，docs/src/debug.md 给的做法是在用例里插一句 page.pause()：

await page.pause();

page.pause()

之后在 debug 模式下运行，点 Resume 就只会停在 page.pause() 这一处。

还有一种更接近浏览器原生的路子：PWDEBUG=console。文档写明在这个模式下，DevTools 控制台里会多出一个 playwright 对象，可以调 playwright.$(selector)、playwright.$$(selector)、playwright.inspect(selector)、playwright.locator(selector) 和 playwright.selector(element)。最后一个是反向的：选中 Elements 面板里的元素、传 $0 进去，它给你生成选择器。

CI 上只能用哪几种

这是四选一里最硬的约束，也是最容易踩的地方。

Inspector 在 CI 上基本用不了。 docs/src/api/class-page.md 在 Page.pause 下面挂了一条 note，逐字写明这个方法要求 Playwright 以 headed 模式启动，即 headless 选项为假值。而 docs/src/ci.md 写明 Playwright 默认以 headless 启动浏览器，Linux agent 上跑 headed 需要装 Xvfb，做法是在命令前面加 xvfb-run：

xvfb-run npx playwright test

文档说官方 Docker 镜像和 GitHub Action 里预装了 Xvfb。但即便把窗口开出来了，Inspector 的价值在于有人坐在那里点 Resume——无人值守的流水线上没有这个人。

UI Mode 在容器里可以开，但要看清那条警告。 docs/src/test-ui-mode-js.md 给了 Docker 与 GitHub Codespaces 的做法：端口要绑到 0.0.0.0 才能从容器外访问。

npx playwright test --ui-host=0.0.0.0

想固定端口就再加 --ui-port：

npx playwright test --ui-port=8080 --ui-host=0.0.0.0

上面这两条命令都是仓库文档里的原样示例，8080 只是文档给的示例端口，换成任何空闲端口都行。

紧跟着的 note 值得逐字读：指定 --ui-host=0.0.0.0 之后，UI Mode 连同你的 trace、密码和 secrets 都可以被网络里的其它机器访问；文档补充说 Codespaces 的端口默认只对你自己的账号开放。这是一个开发环境里的便利开关，不是给共享 CI 用的。

Trace 是为 CI 准备的那一个。 docs/src/trace-viewer.md 给的建议是在配置里把失败用例的第一次重试打开 trace：

import { defineConfig } from '@playwright/test';
export default defineConfig({
  retries: 1,
  use: {
    trace: 'on-first-retry',
  },
});

docs/src/test-api/class-testoptions.md 里 TestOptions.trace 把各个取值的语义写得比指南更细：'on-first-retry' 只在第一次重试时录并保留；'retain-on-failure' 每次都录但只保留失败那次，且即使后续重试通过了，失败那次的 trace 仍然保留；'retain-on-first-failure' 只录首次运行、且只在首次失败时保留。同一处写明 trace 默认是 'off'——这是仓库当前文档里的默认值，随版本可能变动。另外 docs/src/trace-viewer.md 在自己那份取值说明里给 'on'（每次都录）标了「不推荐」，理由写的是它对性能负担重。上面配置块里的 retries: 1 是仓库文档原样给出的示例值，不是推荐配置，重试次数按自己的用例定。

Python 侧不要照抄 JS 的写法。docs/src/trace-viewer.md 里 Python 那一节用的是 pytest 参数：

pytest --tracing on

文档说 Python 侧的取值是 on / off / retain-on-failure，默认 off，trace 会落到 test-results 目录下的 trace.zip。docs/src/ci.md 里的 Python 工作流示例跑的是 pytest --tracing=retain-on-failure，然后用 actions/upload-artifact 把 test-results/ 整个传上去。这就是 trace 在 CI 上的完整用法：机器录，人回来看。

拿到 zip 之后本地打开，JS 侧是 npx playwright show-trace path/to/trace.zip，Python 侧是 playwright show-trace trace.zip。文档还写明可以直接喂一个 URL，省掉手动下载：

npx playwright show-trace https://example.com/trace.zip

另有一个静态托管的版本 trace.playwright.dev，文档写明它把 trace 完全加载在你的浏览器里、不向外传输任何数据。

日志是保底的那一个。 当浏览器压根没起来的时候，前面三个都指望不上，只剩 DEBUG=pw:browser。这也是它在 docs/src/ci.md 而不是 docs/src/debug.md 里的原因。

语言绑定与 Windows 侧的差别

--debug 和 --ui 是 JS 测试运行器的命令行参数。docs/src/test-cli-js.md 的参数表里逐字写明 --debug 是 PWDEBUG=1 环境变量加上 --timeout=0 --max-failures=1 --headed --workers=1 这组选项的快捷方式——这是仓库当前文档里的行为，随版本可能变动。而 UI Mode 的文档页在仓库里只有 test-ui-mode-js.md 这一个语言版本，不带 -js 的共用页并不存在。

Python、Java、C# 走的是环境变量。docs/src/debug.md 里对应语言的那一节给的是 PWDEBUG=1，Windows 上分 cmd 和 PowerShell 两种写法：

set PWDEBUG=1
pytest -s

$env:PWDEBUG=1
pytest -s

DEBUG=pw:api 同理，Windows 上是 set DEBUG=pw:api 或 $env:DEBUG="pw:api"，别把 Linux 的 DEBUG=pw:api pytest -s 这种前置赋值写法搬到 cmd 里。Java 还多一条：文档说要告诉 Playwright 去哪里找被调试的源码，得通过 PLAYWRIGHT_JAVA_SRC 传源码目录列表，而且分隔符在 macOS 和 Linux 上是冒号、在 Windows 上是分号——这条差异是文档里明写的，不是我们推的。

另外 docs/src/debug.md 末尾有一条 WebKit 的提醒：执行过程中启动 WebKit Inspector 会让 Playwright 脚本无法继续执行，并且会重置预先配置的 user agent 与设备模拟。

一条选择路径

从你的处境倒推：

浏览器没起来、日志里是启动失败 → DEBUG=pw:browser。其余三个此刻都没有输入。
本地写用例、locator 匹配不上或者不确定该用哪个 → Inspector 或 UI Mode。两边都有 Pick Locator，都能改完立刻看高亮；page.pause() 让你直接跳到怀疑的那一步。
本地反复改同一个用例 → UI Mode 的 watch mode。这是另外三个都没有的能力。
CI 上偶发失败、本地重现不了 → trace，并且是 'on-first-retry' 或 'retain-on-failure' 这类只在失败路径上留档的模式，配合把产物目录上传成 artifact。
要搞清楚 Playwright 在动作前等了什么 → Inspector 的 actionability 日志（事中）或 trace 里的 Log 页签（事后）。两份文档对这一栏的描述是一致的：滚动进视口、等待可见、等待 enabled 与 stable，然后执行动作。

有几条我们没有依据，就不比：这四种手段各自的资源开销、打开一个大 trace 的表现、UI Mode 与 Trace Viewer 在同一份数据上的渲染差异——仓库文档里没有可引用的说明，我们也没有跑过，所以这里不给结论。文档明说的只有 trace: 'on' 被标为不推荐、理由是性能负担重这一条。

最后提醒一句边界：trace 里存的是真实运行时的 DOM 快照、console 与网络往来，--ui-host=0.0.0.0 那条 note 说的 secrets 暴露风险同样适用于 trace 文件本身。把 trace 当 CI artifact 上传、或者丢到任何在线查看器之前，先想清楚里面有没有你不想外流的东西。

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

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

安全与合规相关做法请结合自身环境评估，本文不构成安全方案建议。