browser-docs-archive/repos/skill-hub/skills/ziniao-webdriver-doc/reference/prerequisites.md

前置条件与排障

本文件是 ziniao-webdriver-doc 的 Level 2 参考文档。 仅在需要了解权限开通、账号配置、常见问题排查时加载。

概述

使用紫鸟 WebDriver 前需完成权限开通和环境准备。本文档覆盖权限申请、账号配置和常见问题排查。

1. 开通 WebDriver 权限

首次使用 WebDriver 时，需先在紫鸟开放平台开通权限。

详细步骤见官方文档：如何开通webdriver权限

2. 客户端版本要求

操作系统	最低版本
Windows	紫鸟 V5 (5.X.X.X) 或 V6 (6.16.0.126+)
macOS	紫鸟 V6 (6.15.0.44+)
Linux	紫鸟 V6 (6.25.3.3+)

3. 环境准备清单

3.1 关闭主进程

启动 WebDriver 前务必确保紫鸟浏览器主进程已完全关闭，避免端口占用或冲突。

3.2 清理残留进程

紫鸟启动失败或异常退出后，可能残留多个子进程（主进程 + 内核进程），不清理直接重启会导致端口占用、反复失败。每次启动前和失败后重试前，都必须执行清理。

已知的紫鸟相关进程名：ziniao、ZiNiao、ziniao.exe、ZiNiaoBrowser 等（不同版本命名可能不同，建议用模糊匹配）。

清理命令：

# Windows (PowerShell)
Get-Process | Where-Object { $_.ProcessName -match 'ziniao|ZiNiao' } | Stop-Process -Force

# macOS / Linux
pkill -f ziniao || true

验证清理结果：

# Windows (PowerShell) — 应无输出
Get-Process | Where-Object { $_.ProcessName -match 'ziniao|ZiNiao' }

# macOS / Linux — 应无输出
pgrep -f ziniao

3.3 创建自动化专用账号

• 创建专用的自动化成员账号（命名建议：自动化_Robot）
• 正式使用前验证该账号能否正常登录紫鸟浏览器客户端

3.4 配置账号权限

问题场景：自动化账号登录后无法获取店铺列表。

解决方案：

1. 登录企业管理后台
2. 检查该账号的权限配置
3. 授予查看对应账号/店铺的权限
4. 建议新建包含此权限的自定义角色并分配给自动化账号

3.5 超时设置

将所有 HTTP 请求的超时时间设为 120 秒或以上，因为启动店铺环境可能耗时较长。

3.6 系统资源管理

• 启动店铺窗口 CPU 消耗较大
• 根据设备配置合理控制并发启动数量
• 建议错开各任务的启动时间，避免瞬时负载过高

3.7 ChromeDriver 版本管理

关键：紫鸟内核版本 ≠ 系统 Chrome 版本。 必须根据 startBrowser 返回的 core_version 匹配 ChromeDriver，不能使用系统 Chrome 对应的版本。

匹配规则：

• core_version 格式为 X.Y.Z.W（如 119.1.0.16），取第一段 X 作为大版本号
• 下载该大版本号对应的 ChromeDriver（如大版本 119 → ChromeDriver 119.x）

下载地址：

• Chrome for Testing：https://googlechromelabs.github.io/chrome-for-testing/
• JSON API（便于自动化脚本解析）：https://googlechromelabs.github.io/chrome-for-testing/known-good-versions-with-downloads.json

本地缓存建议：

chromedriver_cache/
├── 119/
│   └── chromedriver.exe    # 对应 core_version 119.x
├── 120/
│   └── chromedriver.exe    # 对应 core_version 120.x
└── ...

自动化脚本应实现以下逻辑：

1. 从 startBrowser 响应中提取 core_version 大版本号
2. 检查缓存目录 chromedriver_cache/{major_version}/ 是否存在
3. 若不存在，从 Chrome for Testing 下载对应版本并解压到缓存目录
4. 使用缓存中的 ChromeDriver 路径连接 Selenium

4. 通信注意事项

1. 请求/响应均为 JSON 格式，收发消息统一 UTF-8 编码
2. HTTP 模式下超时时长必须 ≥120 秒
3. 调用任何接口后务必检查 statusCode（0 表示成功），出错时优先读取 err 字段获取中文错误描述，这是最有价值的排障信息
4. 启动后必须首先调用 updateCore 接口（需携带凭据），否则打开店铺可能出现内核缺失
5. 务必确保 HTTP 客户端以 UTF-8 解码响应体，否则 err 中的中文会乱码，严重影响错误定位（Python requests 库需设置 response.encoding = 'utf-8'）
6. 所有标记"需凭据"的接口（updateCore、getBrowserList、startBrowser、stopBrowser、ClearOnline）每次调用都必须携带 company/username/password

5. 常见问题

现象	可能原因	解决方案
连接接口失败	客户端未启动完成	轮询 updateCore 直到连接成功
getBrowserList 返回 -10003	未开通权限或未关闭登录验证	检查权限开通状态
getBrowserList 返回 -10013	新设备未授权	调用 applyAuth 进行设备授权
店铺列表为空	账号无店铺权限	在企业管理后台配置角色权限
startBrowser 返回 -10006	上次启动未完成	等待或调用 stopBrowser 后重试
startBrowser 返回 7	内核缺失	确保先调用 updateCore 等待成功
Selenium 连接失败	ChromeDriver 版本不匹配	根据 core_version 下载匹配版本
请求超时	超时设置过短	设置超时 ≥120 秒
多账号冲突	端口/缓存冲突	V5 使用 --multip + --enforce-cache-path
updateCore 返回错误	未携带凭据（company/username/password）	所有需凭据的接口必须携带完整凭据
err 字段内容乱码	HTTP 响应体未以 UTF-8 解码	设置 response.encoding = 'utf-8' 或用 response.content.decode('utf-8')
重启失败 / 端口占用	上次失败后残留紫鸟进程	清理所有紫鸟相关进程后重试（见§3.2）
Selenium 连接失败（版本不匹配）	使用了系统 Chrome 对应的 ChromeDriver	必须根据紫鸟 core_version 大版本号下载匹配的 ChromeDriver（见§3.7）

6. 技术支持

如在对接过程中遇到问题，可通过以下渠道获取支持：

• 微信添加紫鸟生态管家，备注 "紫鸟webdriver"
• 官方 FAQ：https://open.ziniao.com/docSupport?docId=257