ziniao-webdriver-doc（紫鸟 WebDriver 文档）

何时使用 / 不使用

Level 0：定位与边界

是什么

紫鸟浏览器 WebDriver 是紫鸟浏览器提供的本地自动化控制接口。通过命令行参数启动紫鸟浏览器进入 WebDriver 模式后，浏览器在本地开启 HTTP 服务，开发者可通过 JSON API 管理店铺窗口，并使用 Selenium / Puppeteer / Playwright / DrissionPage 等框架对接调试端口，实现对店铺浏览器的自动化控制。

能力概览

不做什么（边界）

• - 不是通用浏览器自动化方案——仅适用于紫鸟浏览器客户端
• 不提供 WebDriver 驱动本身——需根据返回的 coreversion 自行下载匹配版本的 ChromeDriver
• 不处理电商平台业务逻辑——仅提供浏览器窗口控制能力
• 不提供云端部署——仅支持本地运行（通过 --listenip 可开放远程控制）

Level 1：架构与流程

核心概念

WebDriver 模式：通过 --runtype=webdriver 参数启动紫鸟浏览器，使其进入自动化控制模式。此模式下浏览器在本地指定端口开启 HTTP 服务，接受 JSON 格式的 API 调用。启动前必须关闭紫鸟主进程。

HTTP IPC 通信：所有 API 均为 POST 请求，JSON 格式，UTF-8 编码。通过 --port 参数指定通信端口，地址为 http://127.0.0.1:{port}。每个请求需携带 action 字段标识操作类型、requestId 做全局唯一标识。超时建议 120 秒以上。

店铺窗口（browserOauth / browserId）：紫鸟以店铺为最小管理单位。调用 getBrowserList 获取店铺列表及加密 ID（browserOauth），然后通过 startBrowser 启动指定店铺窗口，返回 debuggingPort 用于自动化框架连接。若直接使用 getBrowserList 返回值打开店铺，只需传 browserOauth；仅当需要以明文店铺 ID 打开时才赋值 browserId。

内核版本匹配：startBrowser 返回 coretype（如 Chromium）和 coreversion（如 119.1.0.16），开发者必须使用对应大版本号的 ChromeDriver（如 119.x）连接，否则自动化将失败。

流程全景

mermaid
graph LR
A[申请权限] --> B[启动客户端
(先清理残留进程)]
B --> C[updateCore
检测内核
⚠ 需凭据]
C --> D[getBrowserList
获取店铺列表
⚠ 需凭据]
D --> E[startBrowser
启动店铺窗口
⚠ 需凭据]
E --> F[下载匹配的
ChromeDriver]
F --> G[连接自动化框架
Selenium等]
G --> H[执行自动化操作]
H --> I[stopBrowser
关闭店铺
⚠ 需凭据]
I --> J[exit
退出客户端]

1. 1. 申请权限：在紫鸟开放平台开通 WebDriver 权限
2. 启动客户端：先清理残留进程（见§关键陷阱），再命令行启动紫鸟浏览器，必须参数：--runtype=webdriver --ipctype=http --port={端口}
3. updateCore：必须携带 company/username/password，轮询检测内核是否就绪（statusCode==0），缺失时自动下载
4. getBrowserList：传入 company/username/password，获取店铺列表
5. startBrowser：传入 company/username/password + browserOauth，返回 debuggingPort 和 coreversion
6. 下载 ChromeDriver：根据 core_version 大版本号下载匹配的 ChromeDriver（不是系统 Chrome 版本）
7. 连接框架：用 127.0.0.1:{debuggingPort} + 匹配版本的 ChromeDriver 连接 Selenium 等
8. 关闭：stopBrowser（需凭据）关闭店铺窗口，exit 退出客户端

能力摘要表

关键陷阱

以下均为实战中高频踩坑点，务必在编写自动化脚本时严格遵守。

陷阱 1：凭据一致性

所有标记需凭据的接口（updateCore、getBrowserList、startBrowser、stopBrowser、ClearOnline）每次调用都必须携带完整的 company/username/password，不只是登录类接口。updateCore 尤其容易遗漏——它看似只是内核检测，但紫鸟服务端需要凭据验证身份后才返回内核状态。

陷阱 2：错误信息处理

API 返回错误时，优先读取 err 字段的内容来定位问题，而非仅依赖 statusCode 数字。err 字段包含具体的中文错误描述，是最有价值的排障信息。

编码注意：err 中的中文可能因响应体未正确按 UTF-8 解码而出现乱码，导致无法定位根因。务必确保 HTTP 客户端以 UTF-8 解码响应体（Python requests 库需设置 response.encoding = utf-8，或使用 response.content.decode(utf-8)）。

陷阱 3：进程残留清理

紫鸟启动失败或异常退出后，可能残留多个子进程（主进程 + 内核进程），如果不清理就重启会导致端口占用、反复失败。每次启动前和失败后重试前，必须确保所有紫鸟相关进程已终止。

清理命令：

bash

Windows (PowerShell)

macOS / Linux

陷阱 4：ChromeDriver 版本必须匹配紫鸟内核

紫鸟浏览器的内核版本（coreversion）与系统安装的 Chrome 浏览器版本无关。必须根据 startBrowser 返回的 coreversion 提取大版本号（如 119.1.0.16 → 119），下载对应版本的 ChromeDriver。

建议策略：

1. 1. 首次获取 core_version 后，检查本地缓存目录是否已有