入门

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

即复即用的 CLI 食谱, 从基本启动到使用指纹配置文件的多实例生产部署。

文档中心

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

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

打开对应文档浏览 入门

简介

BotBrowser 的 CLI 标志提供了对指纹配置文件、代理路由、区域设置、渲染配置和自动化行为的精细控制。面对数十个可用标志，了解在特定场景下如何组合使用它们可以大幅节省配置时间。

本文汇集了常见用例的即用食谱。每个食谱包含完整命令、每个标志的用途说明，以及使用或修改的注意事项。所有食谱假设你已经拥有 BotBrowser 二进制文件和来自 GitHub releases 的 .enc 配置文件。

为什么 CLI 食谱很重要

BotBrowser 的配置系统在设计上具有很高的灵活性。你可以在运行时覆盖几乎任何配置文件设置、通过嵌入凭证的代理路由流量、控制渲染行为，并从命令行管理多个实例。这种灵活性意味着存在许多有效的配置方案，而找到适合你场景的正确组合可能需要通读完整的 CLI Flags 参考文档。

食谱弥补了理解单个标志与有效组合它们之间的差距。它们编码了经过测试的配置，处理了常见的边界情况，例如确保每个并发实例拥有自己的用户数据目录，或将代理设置与正确的区域覆盖配对。

配置优先级系统使 CLI 食谱特别强大。CLI --bot-config-* 标志具有最高优先级，可以在不修改加密配置文件的情况下覆盖配置文件设置。这意味着你可以维护一小组基础配置文件，并在启动时针对不同场景进行定制。

技术背景

标志类别

BotBrowser 标志分为几个类别：

核心标志 (--bot-profile, --bot-profile-dir) 控制加载哪个指纹配置文件。每个 BotBrowser 会话都以其中一个标志开始。

代理标志 (--proxy-server, --proxy-ip, --proxy-bypass-rgx) 控制网络路由。BotBrowser 扩展了标准 Chromium 代理标志，支持在 URL 中嵌入凭证。

配置覆盖标志 (--bot-config-*) 覆盖已加载配置文件中的特定值。时区、区域、语言、浏览器品牌、屏幕尺寸和渲染设置都可以配置。

行为开关 (--bot-disable-debugger, --bot-always-active, --bot-inject-random-history 等) 控制不与特定配置文件值绑定的运行时行为。

自定义标志 (--bot-title, --bot-cookies, --bot-bookmarks, --bot-script) 添加会话特定的数据或自动化脚本。

自动检测

BotBrowser 会自动从你的代理 IP 推导时区、区域和语言设置。在大多数食谱中，你不需要手动指定这些值。仅在需要与 IP 推导结果不同的配置时才进行覆盖。

标准 Chromium 标志

BotBrowser 还支持所有标准 Chromium 标志。常用的包括 --headless、--user-data-dir、--remote-debugging-port 和 --window-size。这些标志记录在 Chromium 命令行参考 中。

食谱

食谱 1: 最小启动

最简单的 BotBrowser 配置：

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --headless

这将加载配置文件并以 headless 模式运行。时区、区域和语言会从你机器的 IP 自动检测。适用于本地测试和开发。

食谱 2: 搭配代理的生产启动

chromium-browser \
  --bot-profile="/opt/profiles/windows-chrome-131.enc" \
  --proxy-server=socks5://user:pass@proxy.example.com:1080 \
  --user-data-dir="/tmp/bb-session-$(date +%s)" \
  --remote-debugging-port=9222 \
  --headless

代理处理地理路由，同时 BotBrowser 从代理的出口 IP 自动推导时区和区域。唯一的 --user-data-dir 防止与其他实例冲突。调试端口允许通过 CDP 进行程序化控制。

食谱 3: 显式区域和时区

当你需要特定的区域设置而不考虑代理位置时：

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --proxy-server=socks5://user:pass@proxy.example.com:1080 \
  --bot-config-timezone="Europe/Berlin" \
  --bot-config-locale="de-DE" \
  --bot-config-languages="de-DE,de,en-US" \
  --bot-config-location="52.5200,13.4050" \
  --headless

这将用显式的德国配置覆盖自动检测的值。当你的代理 IP 无法准确反映所需区域时很有用。

食谱 4: 多实例部署

#!/bin/bash
PROFILES_DIR="/opt/profiles/windows-chrome"
BASE_PORT=9222

for i in $(seq 1 5); do
  chromium-browser \
    --bot-profile-dir="${PROFILES_DIR}" \
    --bot-title="Worker ${i}" \
    --user-data-dir="/tmp/bb-worker-${i}" \
    --remote-debugging-port=$((BASE_PORT + i)) \
    --proxy-server=socks5://user:pass@proxy.example.com:1080 \
    --headless &
done

每个实例从目录中获取一个随机配置文件、拥有自己的用户数据目录、唯一的调试端口和一个描述性标题用于识别。--bot-title 显示在窗口标题和任务栏中，方便识别特定实例。

食谱 5: 浏览器品牌切换

呈现为 Microsoft Edge 而非 Chrome：

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --bot-config-browser-brand="edge" \
  --headless

可用的品牌值：chrome、chromium、edge、brave、opera、webview。BotBrowser 会调整 User-Agent、Client Hints 头和相关 API 值以匹配所选品牌。

用会话数据预填充浏览器：

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --bot-cookies='[{"name":"session_id","value":"abc123","domain":".example.com"},{"name":"pref","value":"dark","domain":".example.com"}]' \
  --bot-bookmarks='[{"title":"Dashboard","type":"url","url":"https://example.com/dashboard"}]' \
  --bot-inject-random-history \
  --bot-always-active \
  --user-data-dir="/data/persistent-session" \
  --headless

--bot-cookies 设置初始 Cookie。--bot-bookmarks 添加书签条目。--bot-inject-random-history 创建合成浏览历史以增强会话真实性。--bot-always-active 即使在失焦时也保持窗口活跃。

对于大量 Cookie，可以从 JSON 文件加载：

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --bot-cookies="@/opt/data/cookies.json" \
  --headless

@ 前缀告诉 BotBrowser 从指定文件路径读取 Cookie，而不是将值解析为内联 JSON。

食谱 8: 用于可重现性的确定性噪声

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --bot-noise-seed=42 \
  --bot-time-seed=42 \
  --bot-time-scale=0.92 \
  --headless

--bot-noise-seed 使 Canvas、WebGL、音频、文本度量和 ClientRect 噪声变为确定性。相同的种子每次产生相同的指纹哈希。--bot-time-seed 为浏览器操作提供确定性的执行时序多样性。--bot-time-scale 压缩 performance.now() 间隔以减少基于时序的追踪信号。

食谱 9: 用于分析的 Canvas 录制

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --bot-canvas-record-file="/tmp/canvas-capture.jsonl" \
  --bot-noise-seed=12345 \
  --headless

将所有 Canvas 2D、WebGL 和 WebGL2 API 调用记录到 JSONL 文件。噪声种子固定，因此录制的输出可复现。用于取证分析和调试 Canvas 相关的指纹行为。

食谱 10: 无框架自动化

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --bot-script="/opt/scripts/automation.js" \
  --bot-disable-debugger \
  --bot-disable-console-message \
  --headless

运行一个具有直接 chrome.debugger CDP 访问权限的 JavaScript 文件。无需 Node.js 或 npm。--bot-disable-debugger 防止页面使用 debugger 语句暂停执行。--bot-disable-console-message 抑制控制台输出通过 CDP 暴露。

食谱 11: 指定窗口大小的 Headless

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --bot-config-window="1920x1080" \
  --bot-config-screen="2560x1440" \
  --window-size=1920,1080 \
  --headless

同时设置配置文件级别的窗口/屏幕尺寸和 Chromium 窗口大小。--bot-config-window 和 --bot-config-screen 标志控制 JavaScript API 报告的值，而 --window-size 设置实际视口。

食谱 12: 自定义 STUN 的 WebRTC 隐私

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --proxy-server=socks5://user:pass@proxy.example.com:1080 \
  --bot-webrtc-ice="google" \
  --bot-local-dns \
  --headless

--bot-webrtc-ice 控制通过 WebRTC 暴露的 STUN/TURN 端点，防止本地 IP 泄漏。--bot-local-dns 保持本地 DNS 解析，而不依赖代理提供商的 DNS。

食谱 13: 自定义 HTTP 头

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --bot-custom-headers='{"X-Requested-With":"com.example.app","X-Custom-Auth":"token123"}' \
  --headless

将自定义头注入所有发出的 HTTP 请求。适用于 API 认证和请求路由。

食谱 14: 端口保护

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --bot-port-protection \
  --headless

通过阻止对常见开发和远程访问端口的端口扫描，防止远程页面检测 localhost 上运行的服务。

食谱 15: 调试与故障排除

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --bot-internal --v=1 \
  --enable-logging=stderr \
  --headless

启用 BotBrowser 的内部日志 (--bot-internal --v=1) 和 Chromium 的 stderr 日志输出，用于详细的诊断输出。在排查配置问题时使用。

验证

应用任何食谱后，通过导航到指纹测试工具来验证结果：

# 使用测试 URL 快速验证
chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --proxy-server=socks5://user:pass@proxy.example.com:1080 \
  --bot-noise-seed=42 \
  --remote-debugging-port=9222 \
  --headless

然后通过 CDP 连接并导航到 CreepJS 或 BrowserLeaks 以确认你的配置产生了一致、真实的指纹。详细的测试方法请参阅 如何验证你的浏览器指纹保护。

最佳实践

从最小配置开始，按需添加标志。 从食谱 1 开始，只在有具体需求时才添加标志。不必要的标志增加复杂性而无益处。

让自动检测发挥作用。 如果你使用代理，BotBrowser 会自动处理时区、区域和语言。仅在自动检测的值不符合需求时才进行覆盖。

为每个并发实例使用 --user-data-dir。 没有独立的数据目录，实例会共享 Cookie、缓存和配置文件数据，导致不可预测的行为。

使用 --bot-title 进行识别。 运行多个实例时，标题使得在日志和进程列表中轻松识别哪个实例是哪个。

优先使用 --bot-config-* 而非编辑配置文件。 CLI 标志具有最高优先级，不需要修改加密文件。

在开发中记录所有日志。 在开发和测试期间使用 --bot-internal --v=1。在生产环境中禁用详细日志以提高性能。

常见问题

可以同时使用 --bot-profile 和 --bot-profile-dir 吗？

不可以。如果同时指定，--bot-profile-dir 优先。使用 --bot-profile 维持持久身份，使用 --bot-profile-dir 进行随机轮换。

如果指定了冲突的标志会怎样？

CLI 标志具有最高优先级。如果标志与配置文件值矛盾，标志胜出。如果两个标志互相冲突，通常最后指定的那个生效。

如何知道我的许可证层级支持哪些标志？

需要特定层级的标志在 CLI Flags 参考文档 中用 (PRO)、(ENT Tier1)、(ENT Tier2) 等标签注明。使用没有所需层级的标志不会产生效果。

可以将标志组合保存到文件中吗？

可以。创建一个 shell 脚本或配置文件来存储标志组合。对于 Playwright/Puppeteer，在共享配置模块中定义 args 数组。

最多可以使用多少个标志？

标志数量没有实际限制。但请保持配置尽可能简单。每个不必要的标志都是调试时的潜在混淆点。

如何重置为默认行为？

不使用任何 --bot-config-* 标志启动即可使用配置文件的默认值。不使用 --bot-profile 启动则以原版 Chromium 运行。

这些食谱跨平台通用吗？

是的。相同的标志在 Windows、macOS 和 Linux 上通用。根据你的平台调整二进制文件名 (chromium-browser、chrome、chrome.exe) 和路径格式。

总结

这些食谱涵盖了最常见的 BotBrowser 配置，从最小化的开发启动到生产环境的多实例部署。从满足你需求的最简单食谱开始，随着需求增长逐步添加标志。

如需深入了解特定主题，请参阅 配置文件管理 了解配置文件组织、Headless 服务器设置 了解 Ubuntu 服务器配置、Docker 部署指南 了解容器化部署，以及 Bot Script 自动化 了解无框架自动化。

#Cli#Recipes#Flags#Configuration#快速开始

相关文章

入门

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

入门

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

入门

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

让 BotBrowser 从研究走向生产

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

查看方案探索功能