浏览器自动化入门：首次运行地图

第一次自动化运行决定后面整个项目能不能复现。这个枢纽把入门主题簇连起来，并给出一份有边界的首次运行记录：写明安装、启动、上下文边界和证据。起点是Playwright 与 profile 支撑的浏览器身份。

BotBrowser 支持由 Playwright 或 Puppeteer 这类驱动启动授权 profile，并让浏览器可见值与 profile 保持一致；它不能替你安装驱动、替你挑 profile，也不能保证第三方站点接受这次会话，它不替代驱动本身的文档。

TL;DR

• 先装浏览器和驱动，在写任何自动化之前证明两者都能启动。
• 用显式 profile 启动，并记录这次运行用的是哪个 profile 文件。
• 每个任务给它自己的上下文，并在同一次运行里关闭。
• 保留一份简短的首次运行记录，让第二次运行能和第一次对比。

目录

• 四组入门能力面
• 按顺序走入门主题簇
• 跑第一次会话
• 规划第一个项目
• 让运行可重复
• 修复第一个失败
• 实践结论

四组入门能力面

一次首次运行有四组能力面。安装覆盖浏览器包、驱动，以及两者之间的版本对齐。启动覆盖进程怎么起来：哪个可执行文件、哪个 profile 参数、无头还是有界面。上下文隔离覆盖每个任务拥有什么：自己的浏览器上下文、自己的页面，以及关闭它们的清理。证据覆盖这次运行留下了什么：控制台输出、版本字符串，以及自有检查的结果。

只要按顺序排查，这四组失效能让诊断变简单。安装问题在任何东西启动之前就出现。启动问题表现为浏览器起来了但没用你声明的 profile。上下文问题表现为状态在两个本应独立的任务之间泄漏。证据问题出现得更晚，等没人说得出哪个构建产出了结果的时候。

BotBrowser 在首次运行里的作用很窄：加载你指定的 profile，并让浏览器可见值与之保持一致。其他一切，驱动版本、脚本结构、清理，都属于你的自动化代码。

按顺序走入门主题簇

• Playwright 与 profile 支撑的身份是 Playwright 的启动路径和常见坑。
• Puppeteer 启动与 profile 坑覆盖 Puppeteer 的对应内容。
• Selenium 浏览器 profile 集成覆盖 Selenium 的会话归属。
• 浏览器 profile：格式与轮换解释你要传的 profile 文件。
• 启动器指南覆盖 profile、代理与配置。
• CLI 配方收集具体命令示例。
• 基于 DevTools 协议的轻量自动化覆盖无框架路径。
• 浏览器自动化测试夹具与隔离覆盖首次运行应当拥有的东西。
• 可复现的浏览器缺陷报告覆盖首次运行失败时要记录什么。
• 验证浏览器指纹覆盖对页面可见内容的一次有边界检查。

枢纽定下顺序和记录字段，各主题簇文章保留自己那一面可能出现的具体失败。。

跑第一次会话

在第一个请求之前写下输入：驱动及其版本、浏览器包、profile 文件，以及你打算跑的检查。然后跑一次会话，让每组能力面各被触及一次，并记录结果。

{
  "runId": "first-run-20261019-01",
  "declared": {
    "driver": "[email protected]",
    "browserPackage": "standard-linux-x64",
    "profile": "fresh-temporary.enc",
    "mode": "headless"
  },
  "observed": {
    "install": "executable-started",
    "launch": "profile-loaded",
    "context": "closed-after-task",
    "evidence": "console-and-check-recorded"
  },
  "firstFailure": null,
  "testedOn": "2026-10-19"
}

记录是数据，不是报告。它应当短到能贴进支持讨论，又明确到可以用记录下来的驱动和 profile 重跑同样四行。安装和启动是裸命令，可以直接粘进终端。

在写自动化之前证明安装。 先用一个普通页面启动浏览器，确认它能起来，再跑驱动自己的版本命令。起不了浏览器的驱动会报出看起来像 profile 问题的错误，而起了浏览器却连不上驱动会报出看起来像脚本问题的错误。把两项检查分开，花一分钟，省一下午。

用显式 profile 路径启动。 依赖默认 profile 的首次运行，测的不是你的自动化。显式传入 profile 文件，然后读一个 profile 声明的浏览器可见值，例如平台或时区，并记录下来。如果值对不上，失败的是启动那一面，而不是脚本。

每个任务给自己的上下文。 在互不相关的任务之间复用同一个上下文，早晚会把 cookie、存储或权限泄漏过去。每个任务建一个上下文，跑完，在同一个函数里关闭。记录关闭是否发生，因为泄漏的上下文在主机内存耗尽之前是看不见的。

第一个检查要自有且小。 用你们团队控制的页面，固定版本，只断言一件事：profile 加载了、页面渲染了，或交互完成了。拿第三方站点做首次运行，测到的是那家站点的策略加上你的配置，失败时也说不清四组能力面里哪一组出了问题。

两边都记录版本。 驱动版本和浏览器包版本要和结果写在同一份记录里，因为共享配置的失败层次和驱动更新的失败层次不同。下一次运行行为变了，两份记录能显示是哪一边动了。

有意识地选择无头还是有界面。 无头首次运行更容易自动化、更容易进 CI，有界面首次运行在页面渲染和预期不同时更容易调试。记录你用的模式，因为两次运行之间换模式是另一个实验，无头下的渲染差异不能当作有界面行为的证据。

即使失败也要清理。 把会话包起来，让上下文和浏览器在异常时同样关闭。留下浏览器进程的首次运行，会让第二次运行测到残留状态，简单的配置就是这样变成间歇性失败的。

规划第一个项目

首次运行之后立刻要决定的是项目形状。把三件事从一开始就分开：知道浏览器和 profile 的启动代码、知道被测页面的任务代码，以及两者共用的夹具代码。三者混在一起时，每个新任务都复制一遍启动细节，之后改 profile 要改十几个地方。

把 profile 路径放进配置值，而不是写死在脚本里的字面量。首次运行通常只用一个 profile，第二次运行换一个，可能是为了测试轮换，也可能是为了隔离团队；两种容器决定传入哪个文件，见 profile 格式说明。配置值让这件事变成一行改动，也让 profile 成为被记录的输入，而不是看不见的常量。

让浏览器启动是一个类似 createSession({ profile, headless }) 的函数，返回会话对象。会话对象拥有浏览器、上下文和一个关闭方法。任务接收会话，看不见启动参数。这和 Playwright 与 Puppeteer 对上下文归属的描述一致，也意味着为一个驱动写的任务可以适配另一个驱动而不用重写页面逻辑。

夹具页面要和代码一起做版本。没有版本号就改动的夹具会让两次运行无法比较，最先出现的症状是看起来像浏览器回归的差异。夹具里和记录里各有一个版本字符串就够了。

按任务选驱动，不按演示选

Playwright、Puppeteer、Selenium 和直接使用 DevTools 协议的客户端驱动的是同一个浏览器，各有权衡。Playwright 有成熟的上下文 API 和 trace viewer，Puppeteer 表面更小且在 Chrome 自动化里历史更长，Selenium 对应更广的跨浏览器标准，协议客户端去掉框架但要把管道自己做。

首次运行就选团队已经在别的页面上用的驱动。你要测的是启动路径，不熟悉的驱动会多出一个未知数。上面链接的主题簇覆盖了各主要驱动的 profile 启动方式，以及无框架配置下的协议路径。

不论用哪个驱动，profile 参数都放在启动选项里，不要放进页面级脚本。页面级在加载后设置某个值的变通做法，测的是浏览器没有提供的东西，而且下一次导航就会和声明的 profile 对不上。

想清楚首次运行要证明什么

首次运行是一次只问一个问题的检查，问题应当在写脚本之前写下来。「浏览器能否用这个 profile 启动」是好的第一个问题。「页面能否在声明的平台上渲染」是好的第二个问题。「站点是否接受这次会话」是关于站点的问题，属于后面你自己拥有的测试。

把预期结果写成值，而不是感觉。例如预期 navigator.platform 报出 profile 里声明的值，或预期自有夹具返回固定形状的状态对象。值可以在两次运行之间比较，感觉不能。

把实际结果写在预期结果旁边。只是「通过」的首次运行，不如记录了观测值的有用，因为下一次比较需要两边。驱动更新后观测值变了，记录能直接指出是哪个字段动了。

让运行可重复

首次运行的价值在于让第二次运行变成比较而不是调查。只有第二次运行重复同样的声明输入、产出同样的记录时，这才成立。把运行标识、驱动版本、浏览器包和 profile 写进记录，在改动其中任何一项之前，先把同样的检查重跑一遍。

把整个流程放到一条命令后面，例如 npm run first-run，失败时以非零退出。写成五个手工步骤的配置会变成没人会跑的配置。一条不安装任何东西、用配置好的 profile 启动浏览器、跑自有检查、写出记录的命令，才是当天就能在持续集成里和新同事的 checkout 里跑的配置。

把第一次成功的运行当作回归测试，而不是里程碑。证明配置可用的那次检查应当继续跑，这样后来的驱动更新或包变更会被同一次检查抓到。只存在于聊天截图里的首次运行保护不了任何东西。

把 profile 和清理放在一起

profile 文件和清理路径是同一个决定的两端。从不删除的 profile 会在主机上堆积，从不关闭的上下文会让自己的状态一直活着。两个问题都以内存压力的形式出现，而不是明显的错误，只要首次运行记录了 profile 从哪来、关闭了哪些上下文，两件都容易避免。

首次运行优先用全新的临时 profile（profileClass: "fresh-temporary"），如果 profile 里含敏感内容，就记录类别而不是路径。全新 profile 让首次运行独立于之前的活动，也让与第二次运行的比较有意义。长寿命 profile 是合理的后续步骤，但它应当是一个有意识的步骤。

运行使用共享存储里的 profile 时，记录存储和选择规则，而不是完整文件名，这样复核者能看出 profile 是怎么选出来的，又不会拿到 profile 本身。

把手动做过的检查自动化

首次运行被记录之后，它的大部分行都可以自动化。安装检查变成版本断言，启动检查变成读一个声明值，上下文检查变成关闭断言，证据检查就是记录文件本身。自动化不改变它们证明的东西，只让它们便宜到可以每次变更都跑。

自动化要诚实对待自己的边界。浏览器起来了，不证明页面行为正确；页面渲染了，不证明服务接受了会话。每一行自动检查只断言一件事、只报一个结果，失败就指向一组能力面而不是整套配置。

在合并任何对启动代码的改动之前，先跑自动化的首次运行（npm run first-run）。启动代码小而核心，改动会影响每个任务，最便宜的回归测试就是已经存在的那个。

写清团队真正会敲的那条命令

列出一个新手可能需要的所有参数，不如给出一条能用的命令。把命令放在最上面，解释放在下面，并确保文档里的命令和自动化跑的是同一条。和代码脱节的文档命令比没有命令更糟，因为它教的是一套没人用的配置。

文档里要写出预期输出，而不只是命令。新手需要知道成功长什么样，一份四行都填好的记录文件比一句「跑通了」清楚得多。

驱动或包变化时回头看看这条命令。首次运行是项目里最容易过期的部分，因为它是每个人只配一次、之后就不再看的部分。

修复第一个失败

如果什么都起不来，先查安装那一面：可执行文件、权限，以及驱动能否找到它。如果浏览器起来了但 profile 值对不上，查启动那一面：参数名、文件路径、profile 格式。如果两个任务共享了状态，查上下文那一面：上下文在哪创建、在哪关闭。如果结果无法复现，查证据那一面：记录了哪些版本和输入。

每次只修一面并保留记录。以一组具名能力面收尾的首次运行，可以直接变成项目其余部分的模板。

实践结论

一次可重复的首次运行由四条记录组成：安装、启动、上下文和证据。用这个枢纽确定顺序，用主题簇获取细节，所有结论都限定在产生它的驱动、包和 profile 之内。

来源

• Playwright：浏览器上下文
• Puppeteer：浏览器管理
• MDN：WebDriver
• BotBrowser 文档：入门
• BotBrowser 文档：profile 管理