BotBrowser 与 Puppeteer 快速上手

介绍

Puppeteer 是 Google 的 Node.js 库，用于通过 Chrome DevTools Protocol (CDP) 控制 Chrome。它提供了导航、截图、表单交互、网络拦截等高级 API。BotBrowser 用受配置文件控制的一致指纹二进制替换标准的 Chromium。Puppeteer 负责自动化，BotBrowser 负责身份。

本指南涵盖安装、启动配置、视口管理、代理设置、CDP 使用、在 Linux 服务器上的生产部署与常见故障排查。

隐私影响：为何使用 Puppeteer + BotBrowser

默认 Puppeteer 使用捆绑或系统 Chromium，会暴露主机指纹（GPU、字体、分辨率等）并显示自动化迹象。使用 BotBrowser 可以为每个实例加载不同的指纹配置，从而生成独立的浏览器身份，而无需修改现有自动化代码。

技术背景

使用 puppeteer-core 而非 puppeteer

puppeteer 包包含预打包的 Chromium，会在安装时下载二进制。puppeteer-core 提供相同 API 但不带浏览器，需在 launch 时指定 executablePath，以便指向 BotBrowser 二进制。

# 安装 puppeteer-core，而不是 puppeteer
npm install puppeteer-core

注意 defaultViewport

Puppeteer 默认会将 defaultViewport 设为 800x600，这会覆盖 BotBrowser 配置文件中的视口设置。务必将 defaultViewport: null，以让配置文件控制视口。

CDP 访问

Puppeteer 提供 CDP 会话，BotBrowser 的一些高级功能通过自定义 CDP 命令暴露，需在浏览器级会话发送这些命令。

基本启动示例

const puppeteer = require('puppeteer-core');

(async () => {
  const browser = await puppeteer.launch({
    executablePath: '/path/to/botbrowser/chrome',
    args: ['--bot-profile=/path/to/profile.enc'],
    headless: true,
    defaultViewport: null, // 关键：让配置文件控制视口
  });

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

  console.log('Page title:', await page.title());
  await browser.close();
})();

配置示例：配置文件 + 代理 + 区域设置

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

最佳实践

• 始终使用 puppeteer-core。
• 将 defaultViewport 设为 null。
• 对 --bot-profile 使用绝对路径。
• 在 Linux 服务器上设置 DISPLAY=:10.0 并确保二进制有执行权限。
• 处理完毕后关闭浏览器实例。

验证

通过读取 navigator、screen 等属性来验证指纹是否按预期应用。

总结

集成很简单：安装 puppeteer-core、在 launch 中指定 executablePath 并传入 --bot-profile，再将 defaultViewport 设为 null。随后所有 Puppeteer 功能照常工作。

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

概述

Puppeteer 是 Google 的 Node.js Chrome 控制库。BotBrowser 替换标准 Chromium 二进制文件，提供由配置文件控制的一致指纹输出。Puppeteer 负责自动化，BotBrowser 负责身份。

前置条件

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

快速开始

const puppeteer = require('puppeteer-core');

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

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

  // 你的自动化逻辑

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

关键配置

使用 puppeteer-core，而非完整的 puppeteer 包（后者会下载自带的 Chromium）。

设置 defaultViewport: null 以避免 Puppeteer 覆盖指纹配置文件中的视口尺寸。

配置文件 + 代理示例

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

Ubuntu 无头模式

在 Linux 服务器上运行时，即使是无头模式也需要设置 DISPLAY=:10.0 环境变量。

常见问题

浏览器启动失败：检查二进制文件的执行权限和路径。

视口不匹配：始终设置 defaultViewport: null。

配置文件路径问题：--bot-profile 使用绝对路径。

下一步

• CLI 使用技巧 了解更多参数组合
• 无头服务器设置 了解生产部署
• 配置文件管理 了解配置文件组织方式