浏览器自动化 CLI 启动示例：实用命令参考

一次 BotBrowser 启动，就是在 Chromium 命令行上加入几个 --bot-* 标志。这些标志决定加载哪个指纹配置文件、流量如何路由、会话报告哪些区域值，以及同一台机器上的多个浏览器进程如何并存。下面的示例是可以直接复制的启动命令，并说明每个标志的作用，也给出逐个添加标志的方法，避免从一条没人记得来历的长命令开始。

每个示例都假设你已有来自 GitHub releases 的 BotBrowser 二进制文件，以及主版本与该二进制文件一致的配置文件。示例中的代理地址、凭证、Cookie 值和文件路径都是占位符。请换成你自己的内容，并把每个示例当作需要调整的起点，而不是在不同平台、配置文件版本、代理或目标网站上结果一致的保证。

摘要

BotBrowser CLI 示例把启动标志叠加到 profile 设置和默认值之上。用 --bot-profile、--proxy-server、--bot-noise-seed 分别指定 profile、路由和可重复比较；未授权标志不会生效，示例也不能保证代理质量。

目录

• 为你的场景选择最小的示例
• CLI 标志与配置文件的值如何相互作用
• 启动示例
• 并行运行多个实例
• 依赖示例之前先验证
• 许可证层级、冲突与限制

为你的场景选择最小的示例

添加标志前先写清必需输入：最小启动需要 --bot-profile，路由会话增加 --proxy-server，可重复比较增加 --bot-noise-seed。把所选 profile 的 major 与二进制文件的 major 一并记录；省略这些输入的命令不能作为可比较的示例。

从场景出发，而不是从标志列表出发。如果只需要本地测试，最小启动就够了。如果会话需要从特定线路出口，就加上代理示例。如果需要与该线路不同的区域值，就在其上添加覆盖项。如果同一台机器上运行多个浏览器进程，请先阅读并行实例一节再扩大规模。每一步都在前一步的基础上添加标志，所以你总能撤销最后一次添加，回到已经信任的配置。

• 本地测试或开发：最小 headless 启动。
• 服务器上的路由会话：代理、独立数据目录和调试端口。
• 与出口地址不同的区域值：时区、区域设置、语言和位置覆盖。
• 同一台机器上的多个浏览器进程：各自独立的数据目录、各自独立的端口，以及各自的标题。
• 可重复的对比运行：为噪声和时序固定种子。
• 会话准备：Cookie、书签、历史记录和自定义请求头。
• 诊断：Canvas 录制和 Chromium 日志。

命令越短越容易维护。每多一个标志，就多一项在配置文件或二进制文件更新后需要复查的内容，所以只保留能说清楚用途的标志。

CLI 标志与配置文件的值如何相互作用

配置文件带有一整套默认值。它还可以包含一个 configs 块来覆盖这些默认值，而命令行可以同时覆盖两者。根据配置文件管理文档，优先级从高到低依次是：CLI 的 --bot-* 标志、配置文件的 configs 块、配置文件的默认值。

这个顺序让示例变得实用。你保留一个基础配置文件，在启动时调整代理、区域设置、种子和窗口，而不必编辑配置文件本身。一个示例就是一小段易读的标志列表，而不是配置文件的修改副本。

使用旧写法 --bot-config-* 的现有命令仍然受支持。在同一条启动命令中，每个选项只使用一种写法，结果会更容易阅读。

标志类别

示例中用到的标志可以分为几组。

• 核心标志（--bot-profile、--bot-profile-dir）选择加载哪个指纹配置文件。每个 BotBrowser 会话都从其中之一开始。
• 代理标志（--proxy-server、--proxy-ip）控制路由。BotBrowser 扩展了 Chromium 标准的 --proxy-server 标志，使凭证可以嵌入 URL。
• 配置覆盖标志（--bot-timezone、--bot-locale、--bot-languages、--bot-window、--bot-screen、--bot-browser-brand）替换已加载配置文件中的特定值。
• 行为开关（--bot-always-active、--bot-port-protection、--bot-local-dns）改变与单个配置文件值无关的运行时行为。
• 自定义标志（--bot-title、--bot-cookies、--bot-bookmarks、--bot-script、--bot-custom-headers）添加会话专属的数据或启动脚本。

来自出口地址的区域值

默认情况下，BotBrowser 根据会话访问互联网所用的 IP 地址推导时区、区域设置、语言和位置。使用代理时，就是代理的出口地址。在大多数示例中，你不需要指定这些值。只有当你需要与地址所暗示的配置不同的设置时才进行覆盖，并请记住，这些覆盖项取决于你的许可证层级。

Chromium 标准标志

BotBrowser 也接受 Chromium 标准标志，例如 --headless、--user-data-dir、--remote-debugging-port、--window-size 和 --enable-logging。它们的含义列在 Chromium 命令行开关参考中。如果不确定眼前是哪一类标志，--bot- 前缀是快速的判断方法，而 CLI Flags 参考文档是 BotBrowser 标志的权威来源。

每一项设置由哪一层决定

优先级顺序是固定的，但启动之后真正要问的是另一件事：会话实际应用了哪个值。下表列出五项设置的胜出层，以及从浏览器里而不是从输入的命令中读回结果的最省事方式。

设置	配置文件默认值	配置文件 configs	CLI 标志	在会话中读回
代理路由	直连，或配置文件里保存的路由	写在配置文件 configs 里的路由	--proxy-server	在会话中打开一个回显地址的页面，把出口地址与所设代理主机对比。
User agent	随配置文件捕获的字符串	写在配置文件 configs 里的字符串	--user-agent，或会重写它的品牌标志	在控制台读取 navigator.userAgent，与标志值对比，而不是与配置文件中的字符串对比。
时区	随配置文件捕获的时区	写在配置文件 configs 里的时区	--bot-timezone	在控制台读取 Intl.DateTimeFormat().resolvedOptions().timeZone。
区域设置与语言	随配置文件捕获的区域设置和语言列表	写在配置文件 configs 里的值	--bot-locale 和 --bot-languages	在控制台读取 navigator.language 和 navigator.languages。
屏幕与窗口	随配置文件捕获的屏幕和窗口尺寸	写在配置文件 configs 里的尺寸	--bot-screen 和 --bot-window	在控制台读取 screen.width 和 window.devicePixelRatio。

如果最后一列的值与你传入的标志不一致，说明该标志没有生效。常见原因是名称拼错、许可证层级不覆盖该标志，或同一条命令后面又用另一种写法写了同一选项。

会互相覆盖却不报错的标志组合

有些组合不会报错。其中一个输入胜出，另一个消失，而命令看起来依然正确。

• --bot-profile 与 --bot-profile-dir 同时出现：目录胜出，单个文件被忽略，于是本意是固定一个配置文件的启动，会在每次启动之间悄悄变化。
• --bot-screen 或 --bot-window 与 --window-size 同时出现：两者描述不同的表面，报告的屏幕可能仍是配置文件的值，而真实窗口跟随 Chromium 标志。
• --proxy-ip 与一条已经改变的路由同时出现：会话继续报告你写下的地址，于是更换供应商后旧值仍然存活。
• --bot-timezone 与 --bot-locale、--bot-languages 或 --bot-location 同时出现：各自独立生效，与出口地址矛盾的组合会被接受而不报错。
• 品牌标志与显式的 --user-agent 字符串同时出现：两者可能描述不同产品，并且通过不同表面到达页面。
• socks5 与 --bot-local-dns 同时出现：域名解析发生的位置与 socks5h 不同，路由可能解析出代理根本看不到的域名。

这些都要从浏览器里发现，而不是从命令里发现。把回显页面显示的出口地址与会话报告的地址对比，在 Network 面板里把 navigator.userAgent 与 client hints 的值一起读，再在控制台读取时区、区域设置和屏幕值。如果其中两项不一致，说明命令行是对的，会话不是。

命令启动正常但页面报告本机值的示例

浏览器启动，页面加载，区域值却返回本机的时区和区域设置，而不是出口地址。命令以零状态退出，所以唯一的证据就是页面读到的值。请按顺序走完这些检查。

1. 先确认路由。打开回显地址的页面，把出口地址与代理主机对比。路由不通时，所有区域值都由本机地址推导。
2. 读取会话报告的值，而不是你传入的值，这样在改动之前就能知道两者中哪个是错的。
3. 找找是否有意要求本机的覆盖项。--bot-timezone=real，或配置文件 configs 里保存的同一值，会把设置恢复为本机值。
4. 检查每个区域标志的拼写和许可证层级。这些示例中的覆盖项属于 ENT Tier1，缺少层级的标志会让推导值原样保留。
5. 在命令里搜索同一选项的两种写法，例如旧的 --bot-config-* 与当前名称同时出现。
6. 先不带区域标志运行一次，看清哪些值来自出口地址，然后每次只加一个覆盖项并读回结果。

启动示例

每个示例先给出命令，再解释关键标志。二进制名称 chromium-browser 是 Ubuntu 上的名称。在 Windows 上使用 chrome.exe 或解压后二进制文件的完整路径，在 macOS 上使用 Chromium 应用包内的路径。示例中的 .enc 文件名是占位符，请换成你自己的配置文件。

最小 headless 启动

最小的可用配置：

chromium-browser \
  --bot-profile="profiles/profile.enc" \
  --user-data-dir="$(mktemp -d)" \
  --headless

这条命令加载配置文件，并以 headless 模式配合一次性数据目录运行。时区、区域设置和语言根据机器所用的 IP 地址推导。适用于本地测试和开发。

带独立数据目录的路由会话

添加代理、仅属于本次运行的数据目录和调试端口：

chromium-browser \
  --bot-profile="profiles/profile.enc" \
  --proxy-server=socks5://user:[email protected]:1080 \
  --user-data-dir="/tmp/bb-session-$(date +%s)" \
  --remote-debugging-port=9222 \
  --headless

代理决定出口地址，BotBrowser 据此推导时区、区域设置和语言。唯一的 --user-data-dir 让存储和会话状态独立于其他进程。调试端口让 Playwright 或 Puppeteer 这类框架能够连接到正在运行的浏览器。除非你传入 --remote-debugging-address，否则 Chromium 会把该端口绑定在本机，所以在共享机器上请保留默认值。

已知出口地址

如果你已经知道代理的公网出口地址，可以直接提供：

chromium-browser \
  --bot-profile="profiles/profile.enc" \
  --proxy-server=socks5://user:[email protected]:1080 \
  --proxy-ip="203.0.113.1" \
  --user-data-dir="$(mktemp -d)" \
  --headless

--proxy-ip 会跳过每个页面的 IP 查询，从而加快导航。它接受一个 IPv4 地址、一个 IPv6 地址，或用逗号分隔的一对地址。这是 ENT Tier1 标志，依赖它之前请先确认你的层级。

显式时区、区域设置和位置

当出口地址无法描述你想要的区域时，使用显式的区域值：

chromium-browser \
  --bot-profile="profiles/profile.enc" \
  --proxy-server=socks5://user:[email protected]:1080 \
  --bot-timezone="Europe/Berlin" \
  --bot-locale="de-DE" \
  --bot-languages="de-DE,de,en-US" \
  --bot-location="52.5200,13.4050" \
  --user-data-dir="$(mktemp -d)" \
  --headless

这四个覆盖项会替换由出口地址推导的值，且四个都属于 ENT Tier1。时区必须是 Europe/Berlin 这样的 IANA 名称，而不是 EST 这样的缩写。请让语言、区域设置、时区和坐标彼此保持一致，因为它们之间的不一致需要你自己发现。

对齐浏览器品牌

选择配置文件应当报告的品牌：

chromium-browser \
  --bot-profile="profiles/profile.enc" \
  --bot-browser-brand="edge" \
  --user-data-dir="$(mktemp -d)" \
  --headless

可接受的值是 chrome、chromium、edge、brave、opera 和 webview。设置品牌后，BotBrowser 会调整 User-Agent 字符串、Client Hints 头和相关值，使其与该品牌一致。品牌切换需要 ENT Tier2，webview 需要 ENT Tier3。请选择与所加载配置文件的平台和版本相符的品牌。

启动时带上 Cookie、书签和历史记录

准备一个启动时就带有数据的会话：

chromium-browser \
  --bot-profile="profiles/profile.enc" \
  --bot-cookies='[{"url":"https://example.com","name":"session_id","value":"abc123","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。每个 Cookie 对象都需要 url 字段，缺少该字段的 Cookie 会被静默跳过。--bot-bookmarks 添加书签。--bot-inject-random-history 添加浏览历史，默认是少量随机条目，传入数字则为精确条数。--bot-always-active 让窗口和标签页在失去焦点时保持活跃。Cookie、历史记录和常驻活跃开关属于 PRO 功能，持久的 --user-data-dir 会在多次运行之间保留结果。

从文件加载 Cookie

对于较大的 Cookie 集合，从 JSON 文件读取：

chromium-browser \
  --bot-profile="profiles/profile.enc" \
  --bot-cookies="@/opt/data/cookies.json" \
  --user-data-dir="$(mktemp -d)" \
  --headless

@ 前缀告诉 BotBrowser 从文件读取 Cookie，而不是把值当作内联 JSON 解析。文件更便于审查，也避免了 shell 引号问题。请把它当作凭证对待：限制可读取它的人，并让它保持在版本控制之外。

为可重复运行固定种子

当需要两次运行可以对比时，固定种子：

chromium-browser \
  --bot-profile="profiles/profile.enc" \
  --bot-noise-seed=42 \
  --bot-time-seed=42 \
  --bot-time-scale=0.92 \
  --user-data-dir="$(mktemp -d)" \
  --headless

--bot-noise-seed 让 Canvas、WebGL、WebGPU、文本、ClientRect 和音频保护可重现：相同的种子在多次运行中给出相同的结果，0 则保留配置文件默认值。--bot-time-seed 让执行时序策略可重现，--bot-time-scale 接受小于 1.0 的浮点数，用于时间缩放策略。三者都属于 ENT Tier2。当你对比两个构建或两种配置，并希望唯一的差异就是你所做的改动时，请使用固定种子。

录制 Canvas 调用用于诊断

当你需要查看页面请求了什么时，把 Canvas 调用写入文件：

chromium-browser \
  --bot-profile="profiles/profile.enc" \
  --bot-canvas-record-file="/tmp/canvas-capture.jsonl" \
  --user-data-dir="$(mktemp -d)" \
  --headless

--bot-canvas-record-file 把 Canvas 2D、WebGL、WebGL2 和 WebGPU 的 API 调用记录到 JSONL 文件。录制期间噪声变化被关闭，因此捕获结果是确定的。这是诊断流程，文档中介绍的 CanvasLab 工具可以回放该文件。日常运行时请保持关闭。

用 bot 脚本实现无框架自动化

在启动时运行一个 JavaScript 文件，无需单独的自动化框架：

chromium-browser \
  --bot-profile="profiles/profile.enc" \
  --bot-script="/opt/scripts/automation.js" \
  --user-data-dir="$(mktemp -d)" \
  --headless

--bot-script 在 BotBrowser 启动后立即对每个浏览器进程执行一次该文件，因此不需要 Node.js 项目。创建新的浏览器上下文不会重新运行脚本，需要自己启动逻辑的上下文应通过自己的启动选项接收该标志。Bot Script 自动化指南展示了这类脚本能做什么。

窗口和屏幕尺寸

同时设置会话报告的尺寸和实际窗口大小：

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

--bot-window 和 --bot-screen 设置会话报告的窗口和屏幕尺寸，接受 WxH 值、profile 或 real。--window-size 是 Chromium 标准标志，用于实际窗口。桌面配置文件在有界面模式下默认使用 real，所以如果希望有界面运行时采用配置文件的尺寸，请同时传入 --bot-window=profile 和 --bot-screen=profile。

WebRTC 端点和本地 DNS

控制暴露哪些 WebRTC 端点，以及在哪里解析域名：

chromium-browser \
  --bot-profile="profiles/profile.enc" \
  --proxy-server=socks5://user:[email protected]:1080 \
  --bot-webrtc-ice="google" \
  --bot-local-dns \
  --headless

--bot-webrtc-ice 选择 WebRTC 暴露的 STUN 和 TURN 端点，可使用 google 预设或 custom:stun:...,turn:... 列表。--bot-local-dns 在本地解析代理目标，而不是依赖代理提供商的 DNS 行为。两者都属于 ENT Tier1。

自定义请求头

为每个出站 HTTP 请求添加请求头：

chromium-browser \
  --bot-profile="profiles/profile.enc" \
  --bot-custom-headers='{"X-Request-Source":"internal-tool","X-Team":"research"}' \
  --headless

--bot-custom-headers 接受一个 JSON 对象，并把这些请求头添加到所有出站请求。在 JavaScript 启动代码中，不要给值额外加引号，因为为 Bash 展示的单引号会变成值的一部分。把它用于你自己的服务所需要的请求头，并且不要把真实密钥放进机器上其他用户可以读取的命令行。这是 PRO 标志。

端口保护

让本地服务不被页面探测：

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

--bot-port-protection 通过覆盖常被探测的本地端口，例如开发服务器和远程桌面工具使用的端口，阻止远程页面检测 localhost 上运行着哪些服务。在同时承载本地服务的机器上启用它。这是 PRO 标志。

用于排错的 Chromium 日志

把 Chromium 的日志输出发送到标准错误：

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

--enable-logging=stderr 是 Chromium 标准标志。当某个标志似乎没有效果时，先检查它的拼写、许可证层级和优先级顺序，再去读日志。日常运行时请关闭详细日志。

并行运行多个实例

配置文件可以复用。它可以启动多个浏览器进程，因此一个配置文件并不绑定一个浏览器。进程之间必须不同的是存储和控制端口。

为每个浏览器进程指定各自的 --user-data-dir。没有独立的数据目录，进程会共享 Cookie、缓存和配置文件数据，导致不可预测的行为。同样要为每个进程指定各自的 --remote-debugging-port，因为两个进程不能监听同一个端口。再加上 --bot-title，让窗口标题或任务栏条目告诉你它属于哪个进程。

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

for i in $(seq 1 3); 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:[email protected]:1080 \
    --headless &
done
wait

使用 --bot-profile-dir 时，每次启动都会从目录中选择一个随机配置文件。目录标志不能与 --bot-profile 同时使用：如果两者都存在，以目录为准。当配置必须保持固定时使用 --bot-profile，当你希望每次启动有所变化时使用 --bot-profile-dir。

一台机器能承载多少个进程，取决于它的 CPU、内存和你加载的页面，所以在确定数量之前，请用自己的工作负载实测。上面的循环只是为了让示例简短而使用了较小的数字。

对于服务器，Headless 服务器设置指南介绍了这些命令所假设的 Ubuntu 环境。

依赖示例之前先验证

调整示例之后，确认会话实际报告的内容。启动它，打开一个公开的指纹测试页面，把看到的内容与你设置的内容对比：时区和语言对照出口地址或你的覆盖项，窗口大小对照 --bot-window，浏览器品牌对照该标志。

1. 用相同的标志和相同的种子运行命令两次，检查本应稳定的值确实稳定。
2. 换一个种子或配置文件运行一次，检查本应变化的值确实发生了变化。
3. 分别在使用和不使用代理的情况下打开测试页面，看看哪些区域值来自出口地址。
4. 在二进制文件、配置文件或标志每次更新之后，重复这项检查。

指纹测试页面只能说明配置在你的机器上是否内部一致。它们无法预测任何第三方网站会如何对待某个会话，因此不能替代用你实际使用的网站和工具对自己的工作流程进行试运行。如何验证你的浏览器指纹保护介绍了更完整的测试流程。

常见现象与首要检查

大多数意外都来自少数几个原因。请先检查这些：

• 某个标志没有效果：检查 --bot-* 名称的拼写，以及你的许可证层级是否覆盖该标志。
• 代理不工作：核对完整的 URL 形式 scheme://user:pass@host:port，并先单独测试代理。
• 时区看起来不对：给 --bot-timezone 传入有效的 IANA 名称，例如 America/New_York，而不是 EST。
• 有界面运行时窗口大小被忽略：桌面配置文件默认使用系统的真实尺寸，因此请设置 --bot-window=profile 和 --bot-screen=profile。
• JSON 值解析失败：检查引号。在 Windows CMD 中，外层字符串使用双引号，并对内层引号转义。

许可证层级、冲突与限制

部分标志需要特定的许可证层级。CLI Flags 参考文档用 PRO、ENT Tier1、ENT Tier2 等标签标注它们，没有所需层级而使用的标志不会生效。在这些示例中，区域覆盖项、--proxy-ip、--bot-webrtc-ice 和 --bot-local-dns 属于 ENT Tier1，品牌切换以及种子和时序标志属于 ENT Tier2，Cookie、历史记录、自定义请求头和端口保护属于 PRO。围绕某个标志做计划之前，请查阅你所用版本的参考文档，因为标注可能在版本之间变化。

当两个设置冲突时，由前面描述的顺序决定：CLI 标志优先于配置文件的 configs 块，而该块优先于配置文件默认值。不要在一条命令中重复同一个选项，并且每个选项只使用一种写法，这样命令才不会有歧义。

要回到配置文件的默认值，启动时去掉你添加的 --bot-* 标志即可。把标志组合保存在 shell 脚本中，或保存在为 Playwright 或 Puppeteer 提供参数数组的共享配置模块中，让示例像其他代码一样被审查和纳入版本管理。标志数量没有实际限制，但出现意外行为时，每一个标志都是需要检查的对象。

相同的标志在 Windows、macOS 和 Linux 上通用。请根据平台调整二进制名称和路径格式，并使用主版本与你的二进制文件一致的配置文件。配置文件管理说明了如何选择和组织配置文件。

BotBrowser 不能让标志在其许可证层级之外生效，不保证代理质量或出口 IP 的准确性，也不能替代用你自己的目标工作流程测试最终配置。

实践结论

让每条命令只包含能说清用途的要求，记录 profile 与二进制文件的 major，再在自己的工作流中验证路由。CLI 能选择文档化输入，但不能证明代理出口质量。

来源

• BotBrowser 发布页
• BotBrowser CLI Flags 参考文档
• Chromium 命令行开关
• BotBrowser 文档：配置文件管理
• BotBrowser 文档：CLI 示例