入门

Playwright 浏览器自动化与指纹配置文件

将 Playwright 与指纹一致的浏览器配置文件集成的完整指南，包含代理支持和多上下文自动化。

文档中心

想直接看维护中的产品文档？

这篇文章对应的主题已经有文档中心页面。需要规范流程、当前参数和长期参考时，优先看 docs。

打开对应文档浏览 入门

简介

Playwright 是 Microsoft 的开源浏览器自动化框架，以其可靠的自动等待、多浏览器支持和强大的浏览器控制 API 而闻名。BotBrowser 用一个通过配置文件产生一致指纹输出的版本替换标准 Chromium 二进制文件。两者结合，Playwright 处理自动化逻辑，BotBrowser 处理浏览器身份层。

本指南涵盖入门所需的一切：安装、基本启动配置、代理设置、多浏览器上下文、视口管理、常见陷阱和生产部署模式。读完后，你将拥有一个将 Playwright 的自动化能力与 BotBrowser 的指纹控制相结合的工作设置。

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

标准 Playwright 使用一个暴露真实系统指纹的标准 Chromium 二进制文件。每个浏览器实例都揭示相同的宿主机器特征：相同的 GPU、相同的字体、相同的屏幕分辨率，以及表明浏览器正在被程序化控制的自动化特定信号。

BotBrowser 改变了这个等式。每个浏览器实例可以加载不同的指纹配置文件，呈现跨所有信号一致的唯一浏览器身份。自动化框架处理导航、数据提取和交互逻辑。浏览器身份层处理使每个实例看起来像独立的、合法的浏览器会话。

这种关注点分离是清晰和实用的。你不需要修改你的 Playwright 自动化代码来使用 BotBrowser。集成在启动配置级别完成，其他一切（页面交互、选择器、断言、网络拦截）与标准 Playwright 完全相同。

技术背景

为什么用 playwright-core 而不是 playwright

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

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

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

启动配置的工作原理

当你调用 chromium.launch() 时，Playwright 使用指定的参数生成一个 Chrome 进程。BotBrowser 特定的参数（--bot-profile、--bot-config-* 等）通过 args 数组传递，并在初始化期间由 BotBrowser 二进制文件处理。

启动过程：

  1. Playwright 使用提供的参数调用 BotBrowser 可执行文件
  2. BotBrowser 加载指定的配置文件并应用所有指纹设置
  3. BotBrowser 启动 Chrome DevTools Protocol (CDP) 服务器
  4. Playwright 连接到 CDP 服务器并接管自动化控制
  5. 从此点开始，所有 Playwright 操作正常工作

Playwright 中的浏览器上下文

Playwright 的浏览器上下文是一个隔离的浏览会话，有自己的 Cookie、存储和缓存。浏览器实例内的每个上下文共享相同的指纹配置文件（因为配置文件在浏览器级别加载），但有独立的状态。

对于不同的指纹身份，你启动单独的浏览器实例，每个都有自己的配置文件。对于共享同一身份的多个会话，你在单个浏览器实例内创建多个上下文。

常见方案及其局限性

使用 Playwright 内置浏览器

Playwright 捆绑的 Chromium 适用于一般自动化，但没有指纹控制。每个实例都有相同的指纹（宿主机器的），且存在如 navigator.webdriver 等自动化特定信号。

使用自定义 Chromium 构建

一些团队构建带有特定补丁的自定义 Chromium。这需要维护构建管线、跟踪上游 Chromium 更新和管理二进制文件分发。BotBrowser 处理了所有这些，提供内置指纹控制的即用型二进制文件。

JavaScript 级别的指纹覆盖

注入 JavaScript 来覆盖 navigator 属性、Canvas 渲染和其他信号是一种常见方案。然而，JavaScript 注入在页面创建之后运行，可以通过时序分析、原型链检查和其他方法检测。BotBrowser 在引擎级别应用指纹控制，在任何 JavaScript 执行之前。

BotBrowser 的方案

BotBrowser 通过标准 executablePath 参数与 Playwright 集成。不需要 Playwright 插件、补丁或特殊 API。

最简集成

最简单的集成需要三样东西：

  1. 安装了 playwright-core（而非 playwright）
  2. BotBrowser 二进制文件路径
  3. 指纹配置文件

其他一切都是标准 Playwright 代码。

引擎级控制

因为 BotBrowser 修改了 Chromium 引擎本身，所有指纹控制在 Playwright 连接之前就已完成。当你的 Playwright 脚本开始运行时，浏览器已经拥有完整的指纹身份。这意味着：

  • 从第一次页面加载起指纹信号就已存在
  • 你的自动化代码中不需要"设置"阶段
  • 所有 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=/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();
})();

配置文件 + 代理 + 地区

const browser = await chromium.launch({
  executablePath: '/path/to/botbrowser/chrome',
  args: [
    '--bot-profile=/path/to/profile.enc',
    '--proxy-server=socks5://user:pass@proxy:1080',
    '--bot-config-timezone=America/New_York',
    '--bot-config-locale=en-US',
    '--bot-config-languages=en-US,en',
  ],
  headless: true,
});

多上下文（相同身份）

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://example.com');
await page2.goto('https://example.org');

// 每个上下文有独立的 Cookie 和存储
// 两者共享相同的指纹配置文件

多身份（单独浏览器）

async function createIdentity(profilePath, proxyUrl) {
  const args = [
    `--bot-profile=${profilePath}`,
  ];
  if (proxyUrl) args.push(`--proxy-server=${proxyUrl}`);

  return chromium.launch({
    executablePath: '/path/to/botbrowser/chrome',
    args,
    headless: true,
  });
}

const identity1 = await createIdentity(
  '/profiles/win11-us.enc',
  'socks5://user:pass@us-proxy:1080'
);
const identity2 = await createIdentity(
  '/profiles/win11-de.enc',
  'socks5://user:pass@de-proxy:1080'
);

// 每个浏览器实例有唯一的指纹

网络拦截

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

// 拦截请求 - 与标准 Playwright 相同
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 },
});

截图和 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' });

验证

通过检查指纹信号验证集成是否正常：

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

const fingerprint = await page.evaluate(() => ({
  userAgent: navigator.userAgent,
  platform: navigator.platform,
  languages: navigator.languages,
  hardwareConcurrency: navigator.hardwareConcurrency,
  deviceMemory: navigator.deviceMemory,
  webdriver: navigator.webdriver,
  maxTouchPoints: navigator.maxTouchPoints,
  screenWidth: screen.width,
  screenHeight: screen.height,
  dpr: devicePixelRatio,
}));

console.log('Browser fingerprint:', JSON.stringify(fingerprint, null, 2));
Playwright + BotBrowser Architecture Your Script Automation logic Playwright CDP protocol BotBrowser Identity layer Script controls behavior. Playwright controls automation. BotBrowser controls identity. Standard Playwright API - no plugins or patches needed

最佳实践

  • 使用 playwright-core，而非完整的 playwright 包。完整包会下载你不需要的 Chromium。
  • 使用绝对路径指定 --bot-profile。相对路径可能因工作目录不同而解析不正确。
  • 不要在浏览器上下文上设置视口，除非你特别需要覆盖配置文件的视口。让配置文件控制显示尺寸。
  • 在 Linux 服务器上设置 DISPLAY=:10.0，即使在 headless 模式下。
  • 为不同身份使用单独的浏览器实例。 浏览器上下文共享相同的指纹。对于不同身份，启动不同浏览器。
  • 使用完毕后关闭浏览器。 每个浏览器实例是一个 Chrome 进程。未关闭的实例消耗内存和 CPU。
  • 处理启动错误。 如果启动失败，检查二进制文件路径是否正确且二进制文件有执行权限。

常见问题

我可以使用完整的 playwright 包代替 playwright-core 吗？

技术上可以，但它会下载一个不必要的 Chromium 二进制文件。使用 playwright-core 避免额外下载，并明确表示你使用的是自定义浏览器二进制文件。

我需要禁用 navigator.webdriver 吗？

BotBrowser 通过配置文件处理自动化信号控制。你不需要添加 JavaScript 来修改 navigator.webdriver 或其他自动化指标。

我可以将 Playwright 的 codegen 或 inspector 与 BotBrowser 一起使用吗？

可以。Playwright 的 codegen 工具在指定可执行文件路径时可与 BotBrowser 配合使用。运行 npx playwright codegen --browser-channel=chromium 并在 Playwright 配置中配置自定义可执行文件。

如何在 Ubuntu 上运行 BotBrowser + Playwright？

设置 DISPLAY 环境变量并安装所需库：

export DISPLAY=:10.0
# 如需安装依赖
apt-get install -y libnss3 libatk-bridge2.0-0 libdrm2 libxrandr2 libgbm1

我可以将 Playwright 的按上下文代理与 BotBrowser 一起使用吗？

BotBrowser 通过自己的机制支持按上下文代理。使用 --proxy-server 设置浏览器级代理。对于按上下文代理，使用 BotBrowser 的按上下文指纹功能（ENT Tier1），它自动派生地理信息。避免使用 Playwright 的 page.authenticate() 进行代理认证，因为它可能干扰 BotBrowser 的地理检测。

我可以运行多少个并发浏览器实例？

这取决于你的系统资源。每个 BotBrowser 实例是一个 Chrome 进程，通常使用 200-500 MB RAM。一台 32 GB RAM 的服务器可以舒适地运行 30-60 个并发实例，取决于页面复杂度。

Playwright 的追踪和调试功能与 BotBrowser 配合使用吗？

是的。Playwright 的 trace viewer（context.tracing.start()）、截图和视频录制都能正常与 BotBrowser 配合使用。

我可以将 TypeScript 与 playwright-core 一起使用吗？

可以。playwright-core 包含 TypeScript 类型定义。使用方式与标准 Playwright 配合 TypeScript 相同：

import { chromium, Browser, Page } from 'playwright-core';

总结

将 BotBrowser 与 Playwright 集成只需对标准 Playwright 代码做最小改动：安装 playwright-core，将 executablePath 指向 BotBrowser 二进制文件，并在启动参数中添加 --bot-profile。其他一切（页面交互、网络拦截、截图、断言）完全按 Playwright API 文档所述工作。

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

#Playwright#Automation#快速开始#Tutorial

相关文章

入门

Puppeteer 浏览器自动化与指纹配置文件

入门

浏览器自动化 CLI 食谱: 实用命令示例

入门

浏览器指纹配置文件管理：实用指南

让 BotBrowser 从研究走向生产

先用这些指南理解模型，再进入跨平台验证、隔离上下文和面向规模化的浏览器部署。

查看方案探索功能