飞跨浏览器 WebDriver 接入教程—Window版-帮助中心-飞跨浏览器

WebDriver是一种用于自动化Web浏览器操作的工具，广泛应用于Web应用程序的测试、爬虫、数据抓取等场景。它通过模拟真实用户与浏览器的交互（如点击、输入、页面跳转等），实现对网页的自动化控制。

本教程面向需要使用 Selenium、ChromeDriver 或其他 WebDriver 工具控制飞跨浏览器店铺环境的用户。按本文步骤完成后，你的自动化脚本可以启动指定店铺，接入浏览器实例，并在任务结束后释放资源。当前Window接入WebDriver需要更新飞跨浏览器至V7.1.7版本。

## 1. 概述

启动飞跨浏览器并完成登录后，飞跨会在本机自动开放一个 HTTP 控制接口。你的自动化脚本通过这个接口查询店铺、启动店铺浏览器，并在任务结束后关闭店铺。

脚本主要使用 3 个接口完成接入：

- 查询店铺  ：获取当前登录账号下可用的店铺列表，以及每个店铺当前是否正在运行。
- 启动店铺  ：打开指定店铺的浏览器实例，并返回 WebDriver 接入所需的调试端口和浏览器内核版本。
- 关闭店铺  ：任务完成后关闭指定店铺，释放本机浏览器进程和相关资源。

本文中的 WebDriver 接入，是指使用 Selenium 或兼容 WebDriver 的工具，通过飞跨返回的 `debugger_port` 附加到已启动的 Chromium 实例。

### 1.1 整体流程

1. 用户启动飞跨浏览器，并像平时一样登录账号。
2. 飞跨在后台自动启动本机 HTTP 服务，监听 `127.0.0.1` 上的服务端口。
3. 自动化脚本调用店铺列表接口，获取当前账号下的 `shop_id`。
4. 脚本调用启动接口，传入目标 `shop_id`，让飞跨打开对应店铺浏览器。
5. 脚本从启动响应中读取 `debugger_port` 和 `core_version`。
6. 脚本把 `core_version` 交给 Selenium Manager，由其自动匹配、下载并缓存 ChromeDriver。
7. Selenium 通过 `debugger_port` 附加到已启动的店铺浏览器并进行控制。
8. 任务完成后，脚本调用关闭接口，关闭店铺并释放资源。

为方便理解，可以把这 3 个动作理解为：获取店铺、打开店铺、关闭店铺。实际可调用接口路径请以本文"接口详情"为准。

## 2. 准备工作

注意：必须先完成登录，否则接口无法获取你的店铺数据，也无法启动店铺浏览器。

1.双击启动飞跨浏览器客户端。

2.使用你的飞跨账号完成登录。

3.确认飞跨主界面可以看到店铺列表，表示账号已登录并同步成功。

完成以上步骤后，飞跨会在后台自动启动本机 HTTP 服务。你不需要手动打开额外服务，也不需要单独配置 WebDriver 插件。

### 2.1 本机服务信息
| 项目 | 说明 |
| ------------ | ------------------------------------------------------------ |
| 监听地址 | `127.0.0.1`，仅本机访问。 |
| 默认端口 | `10039`。 |
| 备用端口规则 | 如果端口被占用，飞跨会按固定步长 `+13` 继续尝试： `10039`、`10052`、`10065`、`10078`、`10091`、`10104`，依此类推，直到可用端口。 默认配置下，候选端口会一直尝试到 `10988`；如果 `10988` 也被占用，当前实现还会再尝试一次 `11001`。 接入脚本中的 `BASE_URL` 必须填写飞跨实际监听的端口。 |
| 协议 | `HTTP` |
| 默认基础地址 | `http://127.0.0.1:10039` |
完整 HTTP 候选端口列表

### 2.2 开发环境与依赖

| 项目 | 建议 |
| --------------- | ------------------------------------------------------------ |
| 编程语言 | 不限。只要能发起 HTTP 请求，并能使用 WebDriver 即可。本文示例使用 Python。 |
| 推荐自动化框架 | Selenium WebDriver。 |
| HTTP 客户端超时 | 启动店铺建议不少于 `90` 秒；查询和关闭接口建议 `30` 秒以上。 |
| Python 依赖 | `requests`、较新版本的 `selenium`。建议安装或升级到最新稳定版本。 |
| ChromeDriver | 无需手动下载或配置路径。Selenium Manager 会根据接口返回的 `core_version` 自动匹配、下载并缓存。 |
```
python -m pip install --upgrade requests selenium
```

Selenium Manager 随 Selenium 一起提供，不需要单独安装。第一次使用某个浏览器内核版本时需要联网下载匹配的 ChromeDriver；下载完成后会写入本机缓存，后续店铺使用相同版本时会直接复用。由于飞跨浏览器不是系统默认安装的 Chrome，Selenium Manager 在无法从本机识别目标版本时，也可能额外下载对应版本的 Chrome for Testing 用于版本解析；实际自动化仍会通过调试端口附加到飞跨启动的店铺浏览器。

## 3. 接口详情

以下示例均假设飞跨本机服务地址为 `http://127.0.0.1:10039`。如果你的实际端口不同，请替换为真实端口。

### 3.1 获取店铺列表

```
GET /api/external/webdriver/stores
```

用于获取当前登录账号下可用的店铺。

```
curl http://127.0.0.1:10039/api/external/webdriver/stores
```

响应示例：

```
{
  "code": 0,
  "msg": "success",
  "data": {
    "stores": [
      {
        "shop_id": "f1171820491",
        "shop_name": "TK代填测试",
        "status": "idle"
      }
    ]
  }
}
```

| 字段 | 说明 |
| ------------------------------------------------------------ | ------------------------------------------------------------ |
| `shop_id` | 店铺 ID。后续启动和关闭店铺都需要使用这个值。 |
| `shop_name` | 店铺名称，方便用户识别。 |
| `status` | `idle` 表示未运行；`running` 表示正在启动或已经运行。 |

### 3.2 启动店铺并获取 WebDriver 调试端口

```
POST /api/external/webdriver/stores/start
Content-Type: application/json

{
  "shop_id": "f1171820491"
}
```

调用后，飞跨会启动该店铺对应的浏览器实例，并开放一个本机调试端口给 WebDriver 使用。

```
curl -X POST http://127.0.0.1:10039/api/external/webdriver/stores/start ^
  -H "Content-Type: application/json" ^
  -d "{\"shop_id\":\"f1171820491\"}"
```

成功响应示例：

```
{
  "code": 0,
  "msg": "success",
  "data": {
    "shop_id": "f1171820491",
    "pid": 30080,
    "debugger_port": 55020,
    "core_version": "140.0.7339.207"
  }
}
```

| 字段 | 说明 |
| ------------------------------------------------------------ | ------------------------------------------------------------ |
| `pid` | 飞跨启动的浏览器进程 ID。 |
| `debugger_port` | Chrome DevTools Protocol 调试端口。Selenium 需要通过这个端口附加到浏览器。 |
| `core_version` | 浏览器内核版本。示例代码会把它设置到 `options.browser_version`，供 Selenium Manager 自动匹配 ChromeDriver。 |

启动接口会等待浏览器调试端口可用后再返回。由于店铺环境、插件和内核启动需要时间，建议 HTTP 超时时间设置为`90` 秒或更长。

### 3.3 关闭店铺

```
POST /api/external/webdriver/stores/stop
Content-Type: application/json

{
  "shop_id": "f1171820491"
}
curl -X POST http://127.0.0.1:10039/api/external/webdriver/stores/stop ^
  -H "Content-Type: application/json" ^
  -d "{\"shop_id\":\"f1171820491\"}"
```

成功响应示例：

```
{
  "code": 0,
  "msg": "success",
  "data": {
    "shop_id": "f1171820491"
  }
}
```

如果店铺本来就没有运行，接口也会返回 `code = 0`，并提示 `shop is not running`。

## 4. 完整接入示例

下面是一个最小可用的 Python 示例。它会获取店铺列表，选择第一个空闲店铺，启动浏览器，让 Selenium Manager 根据内核版本自动准备 ChromeDriver，再附加到飞跨打开的 Chromium 实例，访问一个网页，最后关闭店铺。

无需预先下载 `chromedriver.exe`，也无需配置 Driver 路径。接口返回的 `core_version` 已足够用于自动匹配不同店铺的浏览器版本。

请不要给 `webdriver.Chrome` 传入手动配置的 `Service(chromedriver_path)`，否则 Selenium 会优先使用指定的 Driver，不再由 Selenium Manager 自动管理。

```
import time
import requests
from selenium import webdriver
from selenium.webdriver.chrome.options import Options

BASE_URL = "http://127.0.0.1:10039"
TARGET_URL = "https://www.baidu.com"

def api_get(path, timeout=30):
    resp = requests.get(BASE_URL + path, timeout=timeout)
    resp.raise_for_status()
    payload = resp.json()
    if payload.get("code") != 0:
        raise RuntimeError(payload)
    return payload["data"]

def api_post(path, data, timeout=90):
    resp = requests.post(BASE_URL + path, json=data, timeout=timeout)
    resp.raise_for_status()
    payload = resp.json()
    if payload.get("code") != 0:
        raise RuntimeError(payload)
    return payload["data"]

stores_data = api_get("/api/external/webdriver/stores")
stores = stores_data["stores"]

idle_stores = [store for store in stores if store["status"] == "idle"]
if not idle_stores:
    raise RuntimeError("没有可启动的空闲店铺")

shop_id = idle_stores[0]["shop_id"]
driver = None

try:
    start_data = api_post(
        "/api/external/webdriver/stores/start",
        {"shop_id": shop_id},
        timeout=90,
    )

debugger_port = start_data["debugger_port"]
    core_version = start_data["core_version"]
    print("店铺已启动:", shop_id)
    print("调试端口:", debugger_port)
    print("内核版本:", core_version)

options = Options()
    # 把当前店铺的内核版本交给 Selenium Manager。
    # 它会自动匹配、下载并缓存对应的 ChromeDriver。
    options.browser_version = core_version
    options.add_experimental_option(
        "debuggerAddress",
        f"127.0.0.1:{debugger_port}",
    )

# 不传入 Service 或 chromedriver 路径，启用 Selenium Manager。
    driver = webdriver.Chrome(options=options)

driver.get(TARGET_URL)
    time.sleep(2)
    print("当前页面:", driver.current_url)
    print("页面标题:", driver.title)

finally:
    if driver is not None:
        driver.quit()

api_post(
        "/api/external/webdriver/stores/stop",
        {"shop_id": shop_id},
        timeout=30,
    )
    print("店铺已关闭:", shop_id)
```

### 4.1 验证调试端口是否可用

启动接口返回后，你也可以直接访问 CDP 版本接口确认浏览器调试端口已经可用。下面的 `55020` 只是示例，请替换为启动接口返回的 `debugger_port`。

```
curl http://127.0.0.1:55020/json/version
```

如果返回内容中包含 `Browser` 字段，说明 CDP 端口可访问。

## 5. 常见问题

### 5.1 接入检查清单

如果接入失败，请按下面顺序检查，通常可以快速定位接入问题。

1. 飞跨浏览器已启动。
2. 账号已登录，主界面能看到店铺。
3. 脚本中的 `BASE_URL` 使用了真实本机服务端口。
4. 店铺列表接口返回了目标 `shop_id`。
5. 启动接口返回了 `debugger_port` 和 `core_version`。
6. 脚本已设置 `options.browser_version = core_version`。
7. 脚本没有手动指定 ChromeDriver 或传入 `Service(chromedriver_path)`。
8. 首次使用该内核版本时，运行环境可以联网下载 ChromeDriver。
9. Selenium 使用 `debuggerAddress=127.0.0.1:{debugger_port}` 附加浏览器。
10. 任务结束后调用关闭接口释放资源。

### 5.2 接口访问不到怎么办？

确认飞跨浏览器已经启动并完成登录。

确认实际 HTTP 端口是否仍为 `10039`。如果被占用，飞跨会依次尝试 `10052`、`10065`、`10078` 等备用端口。

确认你的脚本运行在同一台电脑上，因为接口只监听 `127.0.0.1`。

### 5.3 为什么启动店铺比较慢？

启动店铺需要准备浏览器内核、店铺环境、插件和调试端口。接口会等调试端口准备好后再返回，因此请把启动接口的 HTTP 超时时间设置得足够长。

### 5.4 需要为每个店铺手动下载 ChromeDriver 吗？

不需要。启动接口返回每个店铺实际使用的 `core_version`，示例代码把它传给 Selenium Manager。Selenium Manager 会自动匹配并缓存对应的 ChromeDriver。多个店铺内核版本不同时，会分别准备相应版本；已经下载过的版本会直接复用。

### 5.5 为什么第一次连接某个内核版本比较慢？

Selenium Manager 第一次遇到该版本时需要联网查询并下载匹配的 ChromeDriver；如果无法从本机识别目标浏览器版本，还可能额外下载对应的 Chrome for Testing。下载完成后会保存到本机缓存，后续使用同一版本通常不需要再次下载。如果运行环境不能访问下载源，请先配置可用的网络或代理。

### 5.6 为什么 Selenium 连接失败？

检查 `debugger_port` 是否使用了启动接口返回的值。

确认已把接口返回的 `core_version` 设置到 `options.browser_version`。

确认没有传入手动配置的 `Service(chromedriver_path)`。

首次使用该内核版本时，确认 Selenium Manager 可以联网下载 ChromeDriver。

建议执行 `python -m pip install --upgrade selenium` 升级到最新稳定版本后重试。

确认店铺浏览器进程没有被手动关闭。

### 5.7 同一个店铺可以同时启动多个实例吗？

不可以。同一店铺同一时间只允许一个运行实例。如果重复启动，接口会返回 HTTP 409，提示该店铺正在启动或已经运行。

### 5.8 脚本结束后一定要关闭店铺吗？

建议关闭。关闭店铺可以释放本机浏览器进程、调试端口和店铺运行资源，也能避免下次任务因为店铺仍在运行而启动失败。