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

Playwright 与 BotBrowser

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

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

隐私影响：为什么选择 Playwright + BotBrowser

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

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

集成方式

为什么用 playwright-core 而不是 playwright

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

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

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

保持精简的启动配置

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

只有应用存在文档化需求时才增加选项。密钥应由部署系统管理，并把 BotBrowser 与 Playwright 版本和任务结果一起记录。

Playwright 中的浏览器上下文

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

Profile 分配方式取决于所选的 BotBrowser 受支持流程。应在上下文打开第一个页面前完成分配，并在整个会话期间保持稳定。

常见方案及其局限性

Playwright 内置浏览器

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

页面级覆盖

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

自定义构建

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

BotBrowser 的方案

BotBrowser 通过 Playwright 标准的 executablePath 选项连接。启动需要 playwright-core、BotBrowser 二进制文件和匹配的配置文件包。页面、上下文、导航、截图和追踪继续使用标准 Playwright API。

必须在创建首个页面前加载配置文件。使用 Per-Context Fingerprint 时，应在该上下文的首个页面或 worker 启动前应用配置文件。Context 和受支持的 Live 工作流均需要 ENT Tier3。

配置和用法

前提条件

• 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=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();
})();

Headless 启动与配置文件校验

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

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

配置文件 + 代理 + 地区

把 profile、批准的网络路径、地区、时区和应用账户作为同一项部署决策审核。它们的地区假设应保持一致。通过部署密钥系统提供凭据，不要写入追踪、截图或终端输出。

会话隔离检查

const browser = await chromium.launch({
  executablePath: 'path/to/botbrowser/chrome',
  args: [
    '--bot-profile=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();

// 拦截应用测试所需的请求
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=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。验证集成改动时，保持二进制版本、配置文件包、代理策略和视口策略不变。

明确记录版本组合

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

发布检查应使用团队自有或明确授权的代表性页面，确认正常导航、必要交互、应用断言、作业所需的截图或文档以及有序关闭。只测试实际会部署的运行模式。把浏览器、自动化包、配置文件和操作系统镜像作为一个可追踪的发布单元。

复核候选版本组合

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

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

执行单会话质量检查

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

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

保存恢复证据

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

候选组合未通过时，记录第一个没有完成的生命周期边界以及恢复的发布单元。重新开放队列前，用同一项单会话检查确认恢复后的组合。这样的证据能够说明实际部署内容、应用观察结果和恢复服务所用的已知版本，比不受限制的页面跟踪更适合发布审核。

进程与上下文归属

每个浏览器进程都应在应用生命周期中有明确的负责组件。它负责创建进程、分配获批准的配置文件与网络路径、观察启动，并在成功、取消或错误后关闭进程。即使使用公共辅助模块，应用也应等待清理完成后再报告作业结束。

浏览器上下文同样需要明确的会话与存储边界。工作结束后应关闭上下文。除非下一项工作明确允许继承存储、权限和配置文件分配，否则不要把上下文放回通用池。取消路径也要停止新页面工作、关闭活动上下文并依照部署策略释放浏览器。

配置文件与网络一致性

把配置文件分配与网络路径视为同一项审核决定。地区、时区、区域设置和代理区域应描述同一个授权环境。代理凭据变化时，保持配置文件和验证页面不变；配置文件变化时，保持获批准路径不变。一次只改一个部分，结果才容易判断。

不要把代理凭据写入终端输出、跟踪记录、截图或作业元数据。通过部署环境的密钥管理方式传入，并限制启动相关流程的服务账号访问。生产环境启用 Playwright 跟踪前，应先检查应用日志的敏感信息清理。

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

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

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

升级与回退

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

回退材料应包含上一版浏览器、自动化依赖锁定、兼容配置文件和部署配置，并在仍然有效时实际验证。处理失败作业时，按第一个未完成的可观察边界分类：启动、配置文件校验、首次导航、应用断言或关闭。先回到最后正常的发布单元，再一次引入一项变化。

支持记录只需包含受影响部署组、可观察结果、发布标识、处理动作和最终验证结果。常规排查不需要完整页面历史或浏览器内部跟踪。确实需要更多页面材料时，应先取得应用负责人的授权。

生产环境注意事项

• 使用 playwright-core，而非完整的 playwright 包。完整包会下载你不需要的 Chromium。
• 使用绝对路径指定 --bot-profile。相对路径可能因工作目录不同而解析不正确。
• 不要在浏览器上下文上设置视口，除非你特别需要覆盖配置文件的视口。让配置文件控制显示尺寸。
• 在 Linux 服务器上设置 DISPLAY=:10.0，即使在 headless 模式下。
• 明确 profile 归属。 只使用所选 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，让 executablePath 指向 BotBrowser 二进制文件，并在启动时分配获批准的配置文件。页面交互、网络拦截、截图和断言使用 Playwright 支持的工作流，实际表现取决于所选版本与运行环境。上线前应在目标负载下验证准确的版本组合。

相关主题请参阅Puppeteer 快速上手了解 Puppeteer 的等效方案，CLI 配方了解更多标志组合，以及配置文件管理了解如何组织配置文件。