返回博客
入门

BotBrowser 与 Playwright 快速上手

将 BotBrowser 与 Playwright 集成以实现可控指纹、代理和多上下文自动化的完整指南。

介绍

Playwright 是 Microsoft 的开源浏览器自动化框架，以其可靠的自动等待、多浏览器支持和强大的 API 著称。BotBrowser 用可控的配置文件替换标准的 Chromium 二进制，使得浏览器输出的指纹一致且可控。Playwright 负责自动化逻辑，BotBrowser 负责浏览器身份层。

本指南覆盖安装、启动配置、代理设置、多浏览上下文、视口管理、常见陷阱与生产部署模式。完成后你将拥有将 Playwright 的自动化能力与 BotBrowser 的指纹控制结合的工作环境。

隐私影响：为什么要组合 Playwright 与 BotBrowser

默认的 Playwright 使用系统的 Chromium，这会暴露主机特征（GPU、字体、分辨率）以及自动化特征。BotBrowser 提供可替换的指纹配置，使每个实例展现独立合法的浏览器身份，而自动化代码仍保持不变。

集成在启动配置层面进行，不需要修改现有 Playwright 脚本。页面交互、选择器、断言与网络拦截均按标准 Playwright 工作。

技术背景

为什么使用 playwright-core 而不是 playwright

playwright 包含预打包的浏览器二进制，会自动下载浏览器，这与 BotBrowser 的自定义二进制冲突。playwright-core 提供相同 API 但不捆绑浏览器，需在 launch 时指定 executablePath，适合指向 BotBrowser 二进制。

# 安装 playwright-core（不要安装 playwright）
npm install playwright-core

启动配置工作原理

调用 chromium.launch() 时，通过 args 将 --bot-profile、--bot-config-* 等参数传递给 BotBrowser。启动流程为：Playwright 启动 BotBrowser 可执行文件 → BotBrowser 加载配置文件并应用指纹设置 → BotBrowser 启动 CDP 服务 → Playwright 连接并控制自动化。

Playwright 中的浏览上下文

浏览上下文是同一浏览器实例内的隔离会话，拥有独立 cookie、存储与缓存。上下文共享浏览器级指纹配置；若需不同指纹，应启动多个浏览器实例，每个实例加载不同配置文件。

常见做法与局限

  • 使用 Playwright 自带浏览器：没有指纹控制，自动化信号明显。
  • 自行构建 Chromium：需维护构建流水线与二进制分发。
  • JS 层覆盖指纹：容易被检测，时序与原型链检查会暴露修改。

BotBrowser 在引擎层进行控制，避免了上述问题。

BotBrowser 的集成方式

集成只需在 executablePath 指向 BotBrowser 二进制，无需插件或特殊 API。

最小集成要求

  1. 安装 playwright-core。
  2. 指定 BotBrowser 可执行路径。
  3. 提供指纹配置文件（.enc）。

启动后，指纹控制在页面加载前已生效。

配置与用法

先决条件

  • BotBrowser 二进制（见 GitHub 仓库）
  • 指纹配置文件（.enc）
  • Node.js 18+
  • npm install playwright-core

确保二进制可执行：

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();

多身份（不同浏览器实例）

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 });
}

网络拦截、视口、截图与 PDF

所有常见 Playwright 功能（page.route、截图、PDF、视口控制等）均按原生方式工作。

验证

可通过在页面内读取 navigator、screen、devicePixelRatio 等属性来验证指纹：

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-core 而非 playwright。
  • 对 --bot-profile 使用绝对路径。
  • 除非需要覆盖，否则不要在上下文中设置 viewport。
  • 在 Linux 服务器上设置 DISPLAY=:10.0。
  • 不同身份使用不同浏览器实例。
  • 使用完毕关闭浏览器实例。

常见问题

  • playwright 可以使用但会下载 Chromium，推荐使用 playwright-core。
  • 不需要手动禁用 navigator.webdriver，BotBrowser 在配置文件层处理自动化信号。
  • Playwright 的 codegen 与 BotBrowser 兼容，指定可执行路径即可。
  • 在 Ubuntu 上运行请设置 DISPLAY 并安装依赖库。
  • BotBrowser 支持 per-context 代理（ENT Tier1）。

总结

将 BotBrowser 与 Playwright 集成所需改动极少：安装 playwright-core、在 launch 时指定 executablePath 并传入 --bot-profile。之后所有 Playwright 功能照常工作。

title: "BotBrowser + Playwright 入门指南" description: "快速入门指南：使用 BotBrowser 与 Playwright 进行浏览器自动化，配合一致的指纹配置文件。" date: "2025-02-18" locale: zh category: getting-started tags: ["playwright", "automation", "getting-started", "tutorial"] published: true

概述

Playwright 负责自动化逻辑，BotBrowser 负责浏览器身份层。两者结合，提供由配置文件控制的一致指纹输出的浏览器自动化。

前置条件

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

快速开始

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');

  // 你的自动化逻辑

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

关键配置

使用 playwright-core 而非 playwright。 完整的 playwright 包会捆绑自己的 Chromium。使用 playwright-core 来启动 BotBrowser 二进制文件。

设置 defaultViewport: null 以防止 Playwright 覆盖指纹配置文件中定义的屏幕尺寸。

配置文件 + 代理示例

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,
});

常见问题

浏览器启动失败：确保 BotBrowser 二进制文件有执行权限（chmod +x chrome）。

配置文件未加载：--bot-profile 使用绝对路径。

屏幕尺寸不匹配：在启动选项中设置 defaultViewport: null。

下一步

#playwright#automation#getting-started#tutorial