如何使用 SeleniumBase 驱动 Brave 浏览器？配置指南与最佳实践详解

在自动化测试和爬虫开发中，浏览器的选择直接影响脚本的稳定性与效率。Brave 浏览器凭借其内置的广告拦截、指纹随机化等隐私保护机制，以及对 Chromium 生态的兼容性，逐渐成为开发者的新宠。然而，主流的自动化框架如 Selenium 和 SeleniumBase 并未原生支持 Brave，这让不少人在配置时走了弯路。本文将系统讲解如何利用 SeleniumBase 驱动 Brave 浏览器，涵盖兼容原理、配置步骤、项目级最佳实践以及常见问题的排查方法，帮助你在实际项目中平稳落地。

一、Brave 与 SeleniumBase 的兼容原理

1.1 Brave 本质上是“换壳的 Chrome”

Brave 浏览器基于 Chromium 开源项目构建，其渲染引擎、网络栈、JavaScript 解析器与 Google Chrome 高度一致。这意味着 Chrome 能打开的网页，Brave 同样能正常渲染；Chrome 能接受的自动化指令，Brave 也能理解。正因为这种同源性，ChromeDriver —— 原本为 Chrome 设计的 WebDriver 实现 —— 同样可以用来驱动 Brave，只要我们在启动时告诉 WebDriver “我要运行的浏览器可执行文件是 brave.exe 而不是 chrome.exe”。

不过，两者并非完全等价。Brave 有自己的发布节奏，版本号通常与 Chromium 大版本对齐，但补丁级别可能不同。例如 Brave 1.60.x 对应 Chromium 119，而 Chrome 119 的 ChromeDriver 理论上可以驱动它，但偶尔会出现细微的协议不兼容。因此，在实际操作中，我们必须确保 Brave 版本、ChromeDriver 版本以及 Selenium 库之间的兼容性，避免因版本错配导致会话创建失败。

1.2 SeleniumBase 的底层机制

SeleniumBase 是一个建立在 Selenium 之上的高级测试框架，它封装了浏览器启动、等待、截图、报告等功能，让测试用例编写更加简洁。在驱动浏览器时，SeleniumBase 内部仍然调用selenium.webdriver.Chrome来创建浏览器实例。关键区别在于，SeleniumBase 允许我们通过driver_options参数传入自定义的Options对象，从而覆盖浏览器的二进制路径、启动参数等。

换句话说，我们只需要在标准 Chrome 配置的基础上，将binary_location指向 Brave 的安装路径，其余一切照旧。SeleniumBase 不会检查浏览器是否是 Chrome，它只负责把配置传递给底层的 WebDriver。这正是驱动 Brave 的理论基础。

二、基础配置：指定 Brave 二进制路径

2.1 找到 Brave 的可执行文件

不同操作系统下 Brave 的安装路径各不相同，这是配置的第一步。以下是常见的位置：

• Windows：C:\Program Files\BraveSoftware\Brave-Browser\Application\brave.exe
• Linux：通常为/usr/bin/brave-browser，也可能是/snap/bin/brave（Snap 安装）或/opt/brave.com/brave/brave（官方包）
• macOS：/Applications/Brave Browser.app/Contents/MacOS/Brave Browser

建议先在命令行中执行which brave-browser（Linux/macOS）或where brave（Windows）确认实际路径，避免写死错误的位置。

2.2 编写第一个驱动脚本

下面是一个最简单的例子，演示如何使用 SeleniumBase 的Driver类启动 Brave 并访问一个网站：

from seleniumbase import Driver
from selenium.webdriver.chrome.options import Options

def test_brave_open():
    options = Options()
    # 指定 Brave 浏览器可执行文件路径
    options.binary_location = "/usr/bin/brave-browser"  # 根据实际系统修改
    # 常用启动参数
    options.add_argument("--no-sandbox")
    options.add_argument("--disable-dev-shm-usage")
    # 创建 Driver 实例，uc=False 表示不使用反检测模式
    driver = Driver(uc=False, headless=False, driver_options=options)
    driver.get("https://ippipp.com")
    print(driver.title)
    driver.quit()

在这段代码中，Driver是 SeleniumBase 提供的核心类，它自动处理了 WebDriver 的下载与初始化。driver_options参数接受标准的Options对象，我们在这里设置了binary_location和两个常见的 Linux 参数。--no-sandbox是必需的，因为在 root 用户或 Docker 容器中，Chrome/Chromium 默认不允许使用沙箱，不加这个参数浏览器会直接崩溃。--disable-dev-shm-usage则解决了共享内存不足导致页面加载失败的问题。

2.3 关于 headless 模式

SeleniumBase 的headless参数控制是否启用无头模式。对于爬虫或 CI 环境，通常设置为True以节省资源。但需要注意的是，Brave 的老版无头模式（--headless）在某些版本中存在渲染 bug，比如 Canvas 指纹生成异常。从 Brave 1.45 开始，Chromium 推出了新版无头模式--headless=new，它更接近有头浏览器的行为。我们可以通过options.add_argument("--headless=new")来启用，同时将headless=False传给 Driver，避免重复设置。示例如下：

options.add_argument("--headless=new")
driver = Driver(uc=False, headless=False, driver_options=options)

三、pytest 全局配置与最佳实践

3.1 通过 conftest.py 统一管理

在大型项目中，每个测试用例都重复指定浏览器路径显然不合理。更好的做法是利用 pytest 的 fixture 机制，在conftest.py中定义一个基类，所有业务测试类继承它即可自动获得 Brave 环境。

下面是一个完整的conftest.py示例，它根据操作系统自动选择路径，并添加了必要的启动参数：

import os
from seleniumbase import BaseCase

class BraveBaseCase(BaseCase):
    def setUp(self):
        options = self.driver_options()
        # 根据操作系统设置 binary_location
        if os.name == "posix":
            # Linux 或 macOS
            if os.path.exists("/usr/bin/brave-browser"):
                options.binary_location = "/usr/bin/brave-browser"
            elif os.path.exists("/Applications/Brave Browser.app/Contents/MacOS/Brave Browser"):
                options.binary_location = "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser"
            else:
                raise FileNotFoundError("未找到 Brave 可执行文件，请检查安装路径")
        elif os.name == "nt":
            options.binary_location = r"C:\Program Files\BraveSoftware\Brave-Browser\Application\brave.exe"
        else:
            raise OSError("不支持的操作系统")

        # 通用参数
        options.add_argument("--no-sandbox")
        options.add_argument("--disable-dev-shm-usage")
        options.add_argument("--disable-gpu")  # 减少 GPU 开销
        options.add_argument("--headless=new")  # 新版无头模式

        # 创建独立用户数据目录，避免缓存污染
        user_data_dir = os.path.join(os.getcwd(), "brave_user_data")
        options.add_argument(f"--user-data-dir={user_data_dir}")

        # 启动浏览器
        self.driver = self.get_new_driver(browser="chrome", options=options)
        super().setUp()

    def tearDown(self):
        self.driver.quit()
        super().tearDown()

使用时，业务测试类只需继承BraveBaseCase：

class TestMySite(BraveBaseCase):
    def test_homepage(self):
        self.open("https://ippipp.com")
        self.assert_element("h1")
        self.assert_text("个人站长网", "title")

这样，所有测试用例都自动使用 Brave 浏览器，且路径和参数集中管理，便于维护。

3.2 用户数据目录的隔离

在多用例并行执行时，不同用例之间可能会互相干扰，比如登录态、Cookie、LocalStorage 等。通过--user-data-dir为每个测试进程指定独立的用户数据目录，可以有效隔离环境。上述代码中我们将目录设为项目根目录下的brave_user_data，实际生产中可以结合 pytest 的tmpdirfixture 生成临时目录，避免残留文件。

3.3 广告拦截的影响

Brave 默认开启了内置的广告拦截和跟踪防护，这在日常浏览中是优点，但在自动化测试中可能带来副作用。例如，某些网站的统计脚本（如 Google Analytics）会被拦截，导致页面元素加载不全或 JavaScript 执行异常。如果你的测试需要验证这些脚本的存在，可以考虑关闭 Brave 的盾牌功能。通过options.add_argument("--disable-brave-shields")可以禁用全局盾牌，但更精细的做法是通过--brave-shields-disabled-for-urls参数指定例外 URL。

四、常见坑与排查思路

4.1 驱动找不到浏览器

最常见的错误是session not created或unknown error: cannot find Brave binary。排查步骤：

1. 确认binary_location指向的路径真实存在，并且文件有可执行权限（Linux 下使用ls -l检查）。
2. 检查 Brave 是否安装在默认位置。有些 Linux 发行版通过 Snap 安装，路径可能是/snap/bin/brave，此时需要相应修改。
3. 在代码中打印options.binary_location确认没有被其他配置覆盖。

4.2 版本不匹配

ChromeDriver 与 Brave 的内核版本必须匹配。如果 Brave 版本较新而 ChromeDriver 较旧，会抛出类似This version of ChromeDriver only supports Chrome version XX的错误。解决方案：

• 使用 SeleniumBase 自带的驱动管理功能：seleniumbase install chromedriver可以自动下载与当前系统 Chrome 版本匹配的驱动。但注意，它检测的是 Chrome 而非 Brave，所以需要手动指定版本。
• 手动下载与 Brave 对应的 Chromium 大版本的 ChromeDriver。下表是常见的对应关系：

可以通过brave --version查看 Brave 版本，然后去ChromeDriver 下载页找到对应版本。

4.3 沙箱与共享内存问题

在 Docker 或 CI 环境中，如果遇到浏览器启动后立刻闪退，多半是沙箱问题。除了添加--no-sandbox和--disable-dev-shm-usage，还可以尝试设置环境变量CHROME_FLAGS。如果仍然失败，启用日志输出：

options.add_argument("--enable-logging")
options.add_argument("--v=1")

然后观察控制台输出，通常会给出明确的错误原因，比如缺少某个系统库。

五、性能优化与扩展建议

5.1 关闭不必要的隐私保护

Brave 的指纹随机化和跟踪防护会增加页面加载时间，尤其是在大量页面跳转的爬虫场景中。如果测试不关心隐私保护，可以通过以下参数关闭大部分功能：

options.add_argument("--disable-brave-update")          # 禁用更新检查
options.add_argument("--disable-background-networking") # 禁用后台网络请求
options.add_argument("--disable-component-update")      # 禁用组件更新
options.add_argument("--disable-sync")                  # 禁用同步

注意，过度禁用可能导致某些网站的功能异常，建议根据目标网站的特性逐步调整。

5.2 缓存与磁盘管理

长时间运行的自动化任务会产生大量浏览器缓存，如果不加限制，可能会占满磁盘。通过--disk-cache-size可以限制缓存大小（单位字节），例如--disk-cache-size=104857600限制为 100MB。同时，配合--user-data-dir使用独立的缓存目录，便于定期清理。

5.3 反检测模式的取舍

SeleniumBase 提供了uc=True参数来启用反检测模式，它会修改 WebDriver 的特征，降低被网站识别为机器人的概率。但这个模式主要针对 Chrome 设计，对 Brave 的效果有限，甚至可能因为修改了某些 Brave 特有的属性而导致异常。因此，除非遇到严重的反爬问题，否则不建议开启。如果确实需要，可以先在有头模式下测试，确认无误后再切换到无头模式。

六、总结

驱动 Brave 浏览器的核心思想很简单：把它当作一个定制版的 Chrome，通过指定binary_location让 ChromeDriver 找到正确的可执行文件。SeleniumBase 为我们提供了便捷的封装，使得配置过程更加优雅。在实际项目中，建议通过 conftest.py 统一管理浏览器路径和参数，并为每个测试用例隔离用户数据目录，避免状态污染。同时，留意版本匹配、沙箱问题和隐私保护带来的影响，就能充分发挥 Brave 在隐私和性能方面的优势。

希望本文能帮助你顺利地在自动化测试或爬虫项目中接入 Brave 浏览器，享受更干净、更高效的自动化体验。

SeleniumBaseBrave_browserautomation_testing修改时间：2026-08-21 07:35:24