Playwright 执行轨迹（Tracing）完整指南：用 playwright-cli 捕获、检查与回放每一步浏览器操作

本文面向使用 Playwright 浏览器自动化 CLI 的开发者，系统讲解 playwright-cli tracing-start / tracing-stop 这一对命令：它能在自动化会话中对浏览器上下文做细粒度记录，产出包含动作日志、DOM 快照、截图、网络活动与 console 日志的可回放 trace 文件。读完本文，你将掌握捕获时机、产物文件的组织方式与含义、三大典型使用场景（失败定位、性能分析、证据留存），以及用 Playwright Trace 工具链离线分析这些 trace 的完整工作流。

什么是 playwright-cli 的 Tracing

playwright-cli 是 Playwright 面向"Agent + LLM 驱动浏览器自动化"场景提供的命令行技能，其完整命令说明见 SKILL.md，而本文所讲的 Tracing 专题是它的官方参考文档（tracing.md）。

Tracing（执行轨迹记录）解决的核心问题是：浏览器自动化过程中到底发生了什么。与普通日志不同，trace 是结构化的、分阶段的记录——每个动作执行前/后的 DOM 状态、每一步的视觉截图、全部网络请求与响应细节、console 消息、精确时序等都会被一并捕获，事后既可以按"动作—快照—网络"层层下钻复盘，也可以在 Trace Viewer 中逐步回放。

从源码实现看，这对命令注册在 cli-daemon/commands.ts，实际逻辑位于 backend/tracing.ts：tracing-start 对应内部工具 browser_start_tracing，tracing-stop 对应 browser_stop_tracing。启动时它直接调用 Playwright 的 browserContext.tracing.start()，并固定打开三个开关：

await browserContext.tracing.start({
  name,            // 即 'trace-' + Date.now()
  screenshots: true,   // 每个动作后截图，用于查看页面视觉状态
  snapshots: true,     // 每个动作前后抓取完整 DOM 快照
  live: true,          // 流式实时写入，方便停止前即可读取已生成部分
});

这解释了为什么产物天然包含"动作 + DOM 快照 + 截图"三要素；停止时（browser_stop_tracing）调用 tracing.stop()，并把 Action log、Network log、Resources 三个文件链接返回给调用者。若未先执行 tracing-start 就执行 tracing-stop，会抛出 Tracing is not started 错误（对应源码中的判空校验）。

基本用法：开始 → 操作 → 停止

使用遵循"开始录制、执行动作、停止录制"三段式：

# 开始记录执行轨迹
playwright-cli tracing-start

# 执行你的自动化动作
playwright-cli open https://example.com
playwright-cli click e1
playwright-cli fill e2 "test"

# 停止记录
playwright-cli tracing-stop

两个命令都无需参数、可在会话中多次启停。open 命令若需指定浏览器或移动端仿真，可参考 SKILL.md 中的 Open 参数，例如 playwright-cli open --browser=firefox 或 playwright-cli open --mobile——这些仿真设置同样会被记录进 trace 的上下文元数据中。需要说明的是，记录的是当前浏览器上下文的全部活动，因此先 open 再 tracing-start 也是可行的，只不过会漏掉页面加载阶段；推荐做法是先 tracing-start 再导航，见下文"最佳实践"。

Trace 输出产物：.playwright-cli/traces/ 目录

启动 tracing 后，Playwright 会在 .playwright-cli/traces/ 目录下生成多类文件。目录名由 backend/context.ts 中的输出目录逻辑决定：在 skill 模式下基目录固定为当前工作目录下的 .playwright-cli（若当前目录是系统目录或不可写，则回退到系统临时目录），tracing 工具再把产物放到底下的 traces/ 子目录中。

trace-{timestamp}.trace —— Action log（动作日志）

整个 trace 的主文件，文件名中的 {timestamp} 即 tracing-start 时刻的毫秒时间戳（见源码中 'trace-' + Date.now()）。内容包括：

• 每一个执行过的动作（点击、填写、导航、键盘输入等）；
• 每个动作前后的 DOM 快照；
• 每个步骤的截图；
• 时序信息；
• console 消息；
• 源码位置（动作对应的调用位置）。

trace-{timestamp}.network —— Network log（网络日志）

完整的网络活动记录：

• 全部 HTTP 请求与响应；
• 请求头与请求体；
• 响应头与响应体；
• 各阶段耗时（DNS、连接、TLS、TTFB、下载）；
• 资源体积；
• 失败请求与错误信息。

resources/ —— Resources 目录（资源缓存目录）

用于回放与重建页面状态而缓存的资源：

• 图片、字体、样式表、脚本；
• 用于回放的响应体；
• 重建页面状态所需的各类资产。

提示：.playwright-cli/traces/ 目录会随自动化会话持续累积，是磁盘空间的增长来源之一，应纳入清理策略（见"最佳实践"）。

一条 Trace 捕获了什么

类别	细节
动作 Actions	点击、填写、悬停、键盘输入、导航
DOM	每个动作前后的完整 DOM 快照
截图 Screenshots	每个步骤的视觉状态
网络 Network	全部请求、响应、请求头/体、响应头/体、时序
Console	全部 console.log / warn / error 消息
时序 Timing	每个操作的精确耗时

典型使用场景

1. 调试失败的动作

当某个点击或填写动作失败却说不清原因时，先在失败前开启 tracing，随后在 trace 里检查"动作发生时页面 DOM 究竟长什么样"：

playwright-cli tracing-start
playwright-cli open https://app.example.com

# 这个点击失败了——为什么？
playwright-cli click e5

playwright-cli tracing-stop
# 打开 trace，查看该次点击被尝试时的 DOM 状态

典型结论往往是：元素被遮挡、选择器命中了多个节点、页面尚未加载完成等——这些都能从动作前后快照的对比中直接看到。

2. 分析页面性能

录制一次完整加载，再通过网络瀑布图定位慢资源：

playwright-cli tracing-start
playwright-cli open https://slow-site.com
playwright-cli tracing-stop

# 查看网络瀑布图，识别拖慢页面的资源

.network 日志里每个请求的 DNS/连接/TLS/TTFB/下载分段耗时，让"慢在服务端还是慢在资源本身"一目了然。

3. 留存操作证据

为文档、报告或 Bug 单录制一段完整且可复现的用户操作序列：

# 记录完整用户流程作为证据
playwright-cli tracing-start

playwright-cli open https://app.example.com/checkout
playwright-cli fill e1 "4111111111111111"
playwright-cli fill e2 "12/25"
playwright-cli fill e3 "123"
playwright-cli click e4

playwright-cli tracing-stop
# trace 忠实记录了事件的精确顺序

回放与分析：打开 trace 文件

录制只是第一步，真正高价值的是事后检查。tracing-stop 返回的 .trace 文件是 Playwright 标准 trace 格式，分析方式有两种：

方式一：可视化 Trace Viewer。 标准 Playwright trace（通常打包为 .zip）可用官方 Trace Viewer 逐动作回放，观察快照、截图、网络时间线与 console 输出。

方式二：命令行 Trace CLI（免开浏览器）。 仓库内置了独立的 npx playwright trace 检查命令族，定义见 traceCli.ts 与其配套技能 playwright-trace/SKILL.md。其典型排查流程如下：

# 1. 打开 trace 并查看元信息（浏览器、视口、时长、动作/错误计数）
npx playwright trace open trace-<timestamp>.trace

# 2. 查看动作树（带 action-id 与耗时）
npx playwright trace actions

# 3. 只看失败动作
npx playwright trace actions --errors-only

# 4. 下钻到具体动作：参数、日志、源码位置、可用快照
npx playwright trace action <action-id>

# 5. 取该动作的 DOM 快照
npx playwright trace snapshot <action-id> --phase after

# 6. 甚至对冻结快照执行查询，如读取错误文案
npx playwright trace snapshot <action-id> -- eval "document.querySelector('.error').textContent"

# 7. 检查网络失败
npx playwright trace requests --failed

# 8. 检查 console 错误
npx playwright trace console --errors-only

# 9. 检查完清理
npx playwright trace close

轨迹的加载实现位于 traceUtils.ts（含动作树序号映射、快照阶段 before/action/after 等），检查时动作既可用序号也可用 callId 定位。

Trace vs Video vs Screenshot

三种"看得见"的记录方式各有取舍，按需组合：

特性	Trace	Video	Screenshot
格式	.trace 文件	.webm 视频	.png/.jpeg 图片
DOM 检查	支持	不支持	不支持
网络细节	支持	不支持	不支持
逐步回放	支持	连续播放	单帧
文件体积	中等	大	小
最适合	调试定位	演示	快速抓取

三者在 playwright-cli 中均有对应命令：Trace 用 tracing-start/tracing-stop，视频用 video-start/video-stop（含章节标注，见 video-recording.md 与 SKILL.md），截图用 playwright-cli screenshot。实践建议是：需要深入排障用 Trace，需要给用户/团队做演示用 Video，只想留一张图用 Screenshot。

最佳实践

1. 在问题发生前就开启记录

永远记录完整流程，而不是只录失败的那一步——失败往往由更早的状态累积导致：

# 记录从导航到出问题的所有步骤
playwright-cli tracing-start
playwright-cli open https://example.com
# ... 所有通向问题的步骤 ...
playwright-cli tracing-stop

同时注意：tracing 开启状态下会话开销会增大，若问题稳定复现，优先考虑"正常流程不录、复现问题前再开"或"小范围录制（如单条关键路径）"的平衡策略；对成功路径与失败路径分两次录制，对比会更有说服力。

2. 及时清理旧 trace

trace 会显著占用磁盘空间，应纳入定期清理。例如删除 7 天前的产物：

# 删除 7 天前的 trace
find .playwright-cli/traces -mtime +7 -delete

由于 .trace 是文本加资源的组合、.network 与 resources/ 也会同步累积，务必整套目录一起清理。若用命令行工具解压检查过 trace，结束后记得 npx playwright trace close，避免 .playwright-cli/trace 残留。

局限与注意事项

• 性能开销：开启 tracing 会给自动化引入额外开销（快照抓取、截图、网络体记录均耗时耗内存），长会话或高频命令场景需评估影响；
• 磁盘占用：大 trace（尤其含大量截图与响应体）可能消耗可观磁盘空间，需要配合清理策略；
• 动态内容回放不完全保真：依赖实时网络/时间/随机数的动态内容（如广告、实时推送、倒计时）在回放时可能无法完美还原，分析时应结合动作前后快照与 console 日志交叉判断；
• 务必成对启停：tracing-start 后要记得 tracing-stop，否则录制中的上下文状态与未落盘的数据会滞留；而对未启动的会话调用 tracing-stop 会直接报错。

小结

playwright-cli 的 Tracing 能力把"浏览器里发生了什么"从黑盒变成了可回放、可检索、可分层的结构化证据：动作、DOM、截图、网络、console、时序六类数据一网打尽。它既是失败动作的第一现场取证工具，也是页面性能的水下剖面，更是向文档与 Bug 单交付可复现证据的标准姿势。配合仓库内建的 npx playwright trace 命令行检查链与官方 Trace Viewer，开发者可以在完全不重跑测试的情况下完成绝大多数排障工作。