Playwright 与配置文件支持的浏览器身份

Playwright 可以使用配置文件支持的身份控制 BotBrowser 可执行文件，但不能保证第三方网站接受，也不能代替应用自身的账号和隐私控制。

TL;DR

• 使用 playwright-core 连接 BotBrowser 可执行文件和已批准的配置文件，不下载捆绑浏览器。
• 把配置文件、网络路径、版本组合、上下文生命周期和清理记录作为一项可审核的单元管理。
• 在提高并发前先验证单个会话，默认只保留运行结果而不收集页面内容。

Contents

• Playwright 与 BotBrowser 如何配合
• 启动、上下文与应用检查
• 验证与版本组合
• 归属、网络一致性与运行观察
• 发布、回退与故障排查
• 实践结论

Playwright 与 BotBrowser 如何配合

Playwright 提供浏览器自动化、可靠等待和清晰的页面工作流接口。BotBrowser 为授权的隐私与兼容性工作增加配置文件支持的浏览器身份。Playwright 继续负责导航和交互，所选浏览器配置文件负责浏览器对外呈现的身份。

集成从启动阶段开始。安装、代理策略、上下文归属、视口设置和进程生命周期需要描述同一项部署。下面的示例使用受支持的 Playwright 工作流，并标出应根据生产版本确认的环节。

标准的浏览器自动化可能暴露超出预期隐私边界的宿主特征。配置文件支持的浏览器允许授权部署控制这类信息，并在整个会话期间让相关浏览器特征保持一致。

Playwright 处理导航、应用检查和交互逻辑。BotBrowser 维护所选浏览器族的身份。这样可以把隐私配置留在页面脚本之外，并让每个浏览器进程或受支持的上下文流程都有一项经过审核的配置文件分配记录。选择器、断言和网络拦截继续使用 Playwright API。

为什么用 playwright-core 而不是 playwright

标准的 playwright npm 包捆绑了自己的 Chromium 二进制文件，并会自动下载浏览器。这对一般用途很方便，但与 BotBrowser 冲突，因为 BotBrowser 提供自己修改过的 Chromium 二进制文件。

playwright-core 包提供相同的 API，但不捆绑浏览器。它要求在启动时指定 executablePath，这正是把 Playwright 指向 BotBrowser 二进制文件的方式。

# 安装 playwright-core，而非 playwright
npm install playwright-core

保持精简的启动配置

让 playwright-core 指向 BotBrowser 可执行文件，并在打开页面前分配已批准的配置文件。版本、配置文件和浏览器模式应明确保存在部署配置中。精简的启动配置更容易审核、复现与回退。

只有应用存在文档化需求时才增加选项。密钥应放在部署的密钥管理路径中，并把 BotBrowser 与 Playwright 版本和任务结果一起记录，便于支持人员复现同一组版本。

Playwright 中的浏览器上下文

Playwright 浏览器上下文为 Cookie、存储、权限与缓存提供会话边界。用它分离获得授权的测试账户和应用状态。每个上下文都应有明确的负责人，并在测试结束后关闭。

配置文件的分配方式取决于所选的 BotBrowser 受支持流程。应在上下文打开第一个页面前完成已批准的分配，并在上下文存续期间保持稳定。

替代方案及其局限

内置浏览器。 Playwright 内置浏览器适合一般自动化，但不会加载 BotBrowser 配置文件包。使用 playwright-core，可以让自动化库连接部署所选的 BotBrowser 二进制文件。

页面级覆盖。 页面脚本只能在导航后改变个别值，无法在启动、worker、图形、媒体和网络行为之间形成一致的浏览器身份。身份设置应放在浏览器配置文件中，不要依赖页面脚本。

自定义构建。 维护私有 Chromium 构建需要跟踪版本、打包并分别发布各平台文件。BotBrowser 提供版本化二进制文件和匹配的配置文件包，应用可以专注于 Playwright 工作流。

启动、上下文与应用检查

前提条件

• BotBrowser 二进制文件（从 GitHub 下载）
• 指纹配置文件（.enc 格式）
• Node.js 18+
• npm install playwright-core

确保 BotBrowser 二进制文件有执行权限：

chmod +x path/to/botbrowser/chrome

基本启动

const { chromium } = require('playwright-core');

(async () => {
  const browser = await chromium.launch({
    executablePath: 'path/to/botbrowser/chrome',
    args: ['--bot-profile=/absolute/path/to/profile.enc'],
    headless: true,
  });

  const context = await browser.newContext();
  const page = await context.newPage();
  await page.goto('https://example.com');

  // 你的自动化逻辑
  const title = await page.title();
  console.log('Page title:', title);

  await browser.close();
})();

配置文件、网络路径与区域设置

把配置文件系列、获批准的网络路径、区域设置、时区和应用账户作为同一项部署决策来审核，它们的地区假设应保持一致。通过 args 中的 --proxy-server 传入网络路径，而不是使用 Playwright 自带的代理选项，并为 --bot-profile 使用绝对路径。

通过部署的密钥存储提供凭据，不要写入追踪、截图或终端输出。当获授权的测试需要特定地区时，同一次启动还可以带上 --bot-timezone、--bot-locale 和 --bot-languages。

const browser = await chromium.launch({
  executablePath: 'path/to/botbrowser/chrome',
  args: [
    '--bot-profile=/absolute/path/to/profile.enc',
    // 从部署的密钥存储中提供路由
    `--proxy-server=${process.env.BOT_PROXY_URL}`,
    '--bot-timezone=Europe/Berlin',
    '--bot-locale=de-DE',
    '--bot-languages=de-DE,de,en-US,en',
  ],
  headless: true,
});

会话隔离检查

const browser = await chromium.launch({
  executablePath: 'path/to/botbrowser/chrome',
  args: ['--bot-profile=/absolute/path/to/profile.enc'],
  headless: true,
});

const context1 = await browser.newContext();
const context2 = await browser.newContext();

const page1 = await context1.newPage();
const page2 = await context2.newPage();

await page1.goto('https://staging.example.test/account-a');
await page2.goto('https://staging.example.test/account-b');

// 对每个获授权的测试账户执行常规应用断言。
await context1.close();
await context2.close();

检查应使用自己的预发布应用和常规产品断言。确认登录、退出、存储清理、取消和上下文关闭符合测试计划。不要收集应用测试不需要的浏览器信号或页面内容。

网络拦截

const context = await browser.newContext();
const page = await context.newPage();

// 使用常规 Playwright API 拦截请求
await page.route('**/*.png', route => route.abort());
await page.route('**/api/**', route => {
  console.log('API request:', route.request().url());
  route.continue();
});

await page.goto('https://example.com');

视口管理

// 选项 1：让配置文件控制视口（推荐）
const browser = await chromium.launch({
  executablePath: 'path/to/botbrowser/chrome',
  args: ['--bot-profile=/absolute/path/to/profile.enc'],
  headless: true,
});
const context = await browser.newContext(); // 不覆盖视口

// 选项 2：显式视口（可能与移动配置文件冲突）
const context2 = await browser.newContext({
  viewport: { width: 1920, height: 1080 },
});

移动配置文件应保留配置文件提供的视口。BotBrowser 150.0.7871.46 会在软件键盘改变可见页面区域时保持 visual viewport 对齐。除非测试明确需要其他尺寸，否则不要通过 Playwright 覆盖视口。

截图和 PDF

const page = await context.newPage();
await page.goto('https://example.com');

// 生成已获授权的测试计划所要求的产物。
await page.screenshot({ path: 'screenshot.png', fullPage: true });

// 生成 PDF
await page.pdf({ path: 'page.pdf', format: 'A4' });

验证与版本组合

先运行一个授权的预发布会话，确认浏览器能够启动、首次导航完成、截图结束，并且浏览器关闭时没有配置文件或进程错误。使用同一配置文件和网络路径重复运行，保持基线可比较。

批量自动化应记录每个 worker 的启动错误、浏览器退出状态和 stderr。验证集成改动时，保持二进制版本、配置文件包、代理策略和视口策略不变。

Headless 启动与配置文件校验

BotBrowser 150.0.7871.46 会在 headless 启动期间通过终端输出报告配置文件缺失、无效、过期或版本不匹配。必须在导航前加载匹配的配置文件包，并把校验失败视为 worker 启动失败。

每个浏览器进程使用独立的用户数据目录，并保留各 worker 的 stderr。先从小规模分组开始，确认带配置文件的页面正常打开，再通过有界队列提高并行度。所有退出路径都要关闭页面、上下文和浏览器。

明确记录版本组合

把 BotBrowser 版本与 Playwright 包版本记录在一起。浏览器自动化库会随浏览器协议演进，一个版本组合运行稳定，不代表任意一方变化后仍会保持相同表现。在应用的依赖锁定文件或部署清单中固定两者，并沿用其他生产依赖的审核流程来更新。

发布检查应使用团队自有或明确授权测试的代表性页面，确认正常导航、必要交互、应用断言、作业所需的截图或文档以及有序关闭。只有在两种模式都属于实际部署时，才同时检查 headless 和有界面模式。从不发布的模式不需要扩大发布检查矩阵。

把配置文件包、浏览器二进制文件、自动化包和操作系统镜像作为一个可追踪的发布单元。如果应用在容器中运行，还应记录镜像修订版本。这样出现意外结果时可以复现，而无需收集与集成无关的页面数据。

复核候选版本组合

在实际部署使用的同类主机上准备候选组合。恢复依赖锁定文件，安装选定的 BotBrowser 版本，并使用针对该版本审核过的配置文件包。开始会话前，对照发布记录检查可执行文件路径、启动模式、网络策略和应用配置。开发电脑上的结果适合用于准备阶段，但不能代替目标运行环境中的检查。

在团队自有的稳定页面集上运行候选组合。保持测试账号、应用数据、网络路径和预期断言不变，比较导航完成、表单操作、文档生成和有序关闭等用户可观察结果。如果预期结果发生变化，应继续保留上一组版本，直到差异得到审核。不要在一次发布中同时更换浏览器、Playwright 包、配置文件包和应用代码，否则验收材料无法说明哪一项需要处理。

执行单会话质量检查

先使用一个会话和一个获批准的账号。把启动、打开第一个必要页面、执行应用操作、清理状态和退出浏览器作为一个完整生命周期检查。关闭上下文前，确认测试只创建了应用预期的 Cookie、存储、权限和文件。关闭后新建会话，确认上一个账号的状态已经消失，除非保留该状态本来就是明确需求。

除了成功路径，还应检查取消和应用断言失败。任务取消后应停止新的页面活动，关闭所属上下文，并按部署策略释放浏览器。应用断言失败时只保留必要的运行记录，同时执行相同的清理流程。完成这项检查后，团队才有可信的会话边界，再把更多任务放入队列或评估容量。

保存恢复证据

为每个通过验收的版本组合保留精简的发布记录，包括浏览器版本、Playwright 包版本、配置文件包系列、操作系统镜像、部署组、验证日期和最终结果。分别记录启动、代表性应用流程、状态清理、取消和关闭是否通过，并引用应用测试的修订版本，便于其他人员重复同一项获批准的检查。

候选组合未通过时，记录第一个没有完成的生命周期边界以及恢复的发布单元。重新开放队列前，用同一项单会话检查确认恢复后的组合。这些证据能够说明实际部署了什么、应用观察到了什么，以及哪一个已知版本让服务回到了已审核的状态。

归属、网络一致性与运行观察

进程与上下文归属

用 browserProcessId 和 contextId 作为生命周期锚点。

每个浏览器进程都应在应用生命周期中有明确的负责方。负责方创建进程、分配获批准的配置文件与路径策略、观察启动，并在成功、取消或错误后关闭进程。公共辅助模块可以强制执行这一生命周期，但应用代码仍应等待清理完成后再报告作业结束。

浏览器上下文同样需要明确的归属。用上下文承载一个确定的存储与会话边界，工作结束后关闭它。除非下一项工作明确允许继承存储、权限和配置文件分配，否则不要把上下文放回通用池。对于隐私敏感的工作，新建边界通常比职责不断变化的长期上下文更容易审核。

取消路径应与成功路径得到同样的重视。当队列项过期或调用方断开时，应停止新的页面工作、关闭活动上下文，并按部署策略释放浏览器，同时记录清理是否完成。静默取消却让浏览器进程继续运行，最终会表现为内存压力或无法解释的配置文件复用。

代理与配置文件保持一致

把审核后的网络决定记录为 routePolicy。

把配置文件分配与网络路径视为同一项经过审核的决定。区域设置、时区、地区设置和代理所在地区应描述同一个授权环境。路由选择应保留在受支持的浏览器或部署流程中，不要分散在页面代码和多个外部处理程序之间。

凭据轮换时，保持配置文件和页面集不变，只验证新的网络路径。配置文件包变化时，保持获批准的路径不变，只验证新的配置文件包。同时改变两者会让故障难以归类。每次变更后，重复常规应用检查，并只记录支持人员需要的版本标识和结果。

不要把代理凭据写入控制台输出、追踪记录、截图或作业元数据。通过部署的密钥管理路径传入，并限制启动授权流程的服务账号的访问。在生产环境启用 Playwright 追踪前，应先检查应用日志记录器的敏感信息脱敏。

不收集页面内容的运行观察

保留 firstPageReadyMs 和 exitCode 作为运行锚点，不保存页面内容。

集成所需的遥测主要是运行状态：浏览器启动完成、首个页面就绪、任务耗时、上下文关闭、浏览器退出状态、队列延迟和发布标识。这些观察足以判断系统是否健康，无需保留页面内容或详细浏览历史。

截图、视频、追踪记录和网络归档可能包含账号数据或私有应用状态。仅在经过批准的支持场景或流程本身确实需要时启用，并在收集开始前设定访问控制和保留期限。问题解决后应关闭临时诊断。

容量数据应按部署组汇总，不要把详细的浏览器活动附加到单个会话上。内存趋势、CPU 饱和度、浏览器退出次数和已完成作业数量足以支持大多数扩缩容决策。当隐私与性能的证据有不同的保留要求时，应把两类审查分开。

发布、回退与故障排查

升级与回退

用可追踪的 deploymentGroup 标识发布分组。

先把新的浏览器或 Playwright 版本部署到小型分组，并使用相同负载、配置文件系列、路径策略和主机类别与未改动组比较。如果应用断言、浏览器稳定性或清理结果偏离发布计划，应暂停，并在尝试第二项变化前恢复上一组版本。

回退材料应包含上一版浏览器二进制文件、自动化依赖锁定、兼容的配置文件包和部署配置，并在它们仍然有效时实际验证。如果回退所需的二进制文件已被移除，或配置文件包已经过期，这份回退说明就没有价值。

成功发布后，按组织的保留策略清理旧包。只保留支持所需的发布记录：版本组合、配置文件系列、部署组、验证窗口和结果。不要仅因为预发布阶段收集过完整追踪记录就长期保留它们。

处理启动与运行问题

用 failureBoundary 字段记录第一个失败边界。

按第一个没有完成的用户可见边界对失败作业分类。启动失败、配置文件校验失败、首次导航失败、应用断言失败和关闭失败的负责方各不相同。保留正常的终端输出和退出状态，然后把所分配的发布单元与上一次成功作业比较。

先回到最后一组可正常运行的版本，再考虑调整多项设置。通过部署的常规检查确认二进制文件访问、配置文件分配、路径可用性和主机资源。基线恢复后，一次只引入一项变化，并重复代表性应用流程。

不要把生产事件变成没有边界的页面检查。支持记录应包含受影响的部署组、可观察结果、发布标识、处理动作和最终验证结果。只有应用负责人授权且常规运行证据不足时，才收集额外的页面材料。

生产环境检查清单

• 使用 playwright-core，而非完整的 playwright 包。完整包会下载你不需要的 Chromium。
• 使用绝对路径指定 --bot-profile。相对路径可能因工作目录不同而解析不正确。
• 不要在浏览器上下文上设置视口，除非你确实需要覆盖配置文件的视口。让配置文件控制显示尺寸。
• 在 Linux 服务器上设置 DISPLAY=:10.0，即使在 headless 模式下也是如此。
• 明确配置文件归属。 只使用所选 BotBrowser 流程支持的分配方式，并在第一个页面前完成。
• 使用完毕后关闭浏览器。 未关闭的浏览器任务会继续占用主机容量。
• 处理启动错误。 如果启动失败，检查二进制文件路径是否正确，以及二进制文件是否有执行权限。

常见问题

• 可以使用完整的 Playwright 包吗？ 可以，但它会下载本方案不需要的另一个浏览器。playwright-core 能把自动化库与 BotBrowser 二进制文件分开管理。
• 身份设置需要页面脚本吗？ 不需要。在浏览器启动时加载匹配的配置文件包，或在首个目标启动前应用受支持的按上下文配置文件。
• 可以使用 Playwright codegen 或 inspector 吗？ 可以。开发工具应使用与项目相同的自定义可执行文件和配置文件设置，并保持开发与生产的配置文件版本一致。
• 如何在 Ubuntu 上运行？ 安装所选版本需要的运行库，并按照 Headless Server Setup 指南配置。图形路径请参考 Linux GPU Backend 指南。
• 可以使用按上下文代理吗？ 可以。BotBrowser 的 Context 和 Live 代理工作流需要 ENT Tier3。必须在首个页面或 worker 启动前应用代理和配置文件，不要用框架层认证替代该路径。
• 可以运行多少个 worker？ 在目标主机上测量代表性页面。通过有界队列限制并发，保留内存余量，并在提高并发前确认资源已彻底释放。
• 追踪和截图可以正常使用吗？ 当所选版本组合和运行环境支持时，可以通过 Playwright 使用这两项功能。应检查应用实际需要的产物，设置访问与保留规则，并在容量测量中计入资源开销。
• 可以使用 TypeScript 吗？ 可以。playwright-core 包含 TypeScript 类型定义。

实践结论

使用 playwright-core 将自动化与 BotBrowser 可执行文件分开，在打开首个页面前分配已批准的配置文件，并把路径、版本、上下文清理和运行遥测作为一项审核流程。这样可以得到可重复的启动边界，但不声称能够控制第三方应用。

BotBrowser 在这一流程中的作用

BotBrowser 支持通过 Playwright 标准的 executablePath 配合 --bot-profile（以及可选的 --proxy-server）启动，由所选配置文件决定浏览器身份，而 Playwright 继续在同一套可重复的启动配置中处理导航、上下文和断言。对本方案而言，这意味着团队可以把一份经过审核的启动定义作为发布单元来固定、重复和回退。BotBrowser 不替代 Playwright 的自动化 API，不保证在任何第三方网站上获得特定结果，也不能控制被测应用、代理服务商或账号状态。Per-Context 和 Live 代理工作流还需要 ENT Tier3。

安装 playwright-core，让 executablePath 指向 BotBrowser 二进制文件，并在启动时分配获批准的配置文件。上线前应在目标负载下验证准确的版本组合。可以下载 BotBrowser，或查看所需工作流对应的定价方案。

相关主题请参阅 Puppeteer 快速上手了解 Puppeteer 的等效方案，CLI 配方了解更多标志组合，配置文件管理了解如何组织配置文件，以及按上下文分配代理了解独立上下文的路由归属。

关于首次运行应覆盖的四组能力面，先读浏览器自动化入门地图。

公开来源

• BotBrowser 的 GitHub 仓库
• BotBrowser Playwright 指南
• Playwright BrowserType API