环境搭建与 ApiServer 配置

Playwright 在候鸟的接入中支持三种语言，您可以根据团队习惯选择其中一种。每种语言的安装步骤略有不同，本章分别列出，请按需阅读。

---

选择您的语言

TIP

• JavaScript（Node.js）：与 Puppeteer 习惯相近，脚本简洁，推荐前端开发者
• Python：数据分析/爬虫背景开发者首选，候鸟已帮您管理虚拟环境
• Java：企业级项目或团队已有 Java 技术栈，可无缝接入

---

一、JavaScript / TypeScript 环境

1. 安装 Node.js

前往 Node.js 官网 下载 LTS 版本（如 Node.js 20.x）。

验证安装：

node -v   # 应输出 v20.x.x 或更高
npm -v

2. 新建项目并安装 Playwright

# 新建项目文件夹
mkdir mb-playwright && cd mb-playwright

# 初始化 npm 项目（一路回车即可）
npm init -y

# 安装 Playwright（只安装核心库，不需要内置浏览器，用候鸟的）
npm install playwright

NOTE

安装时 Playwright 会尝试下载浏览器文件，因为我们使用候鸟的浏览器，可以设置环境变量跳过：

set PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1
npm install playwright

3. 安装 axios（用于调用候鸟 ApiServer）

npm install axios

4. 创建主脚本文件

# 创建脚本文件
echo. > start.js

---

二、Python 环境

1. 安装 Python

前往 Python 官网 下载 3.8+ 版本。

安装时勾选：✅ Add Python to PATH

验证安装：

python --version
pip --version

2. 候鸟 Playwright Python 虚拟环境说明

IMPORTANT

候鸟内置了 Playwright Python 的独立虚拟环境，路径为候鸟安装目录下的 python\Playwright\。

在候鸟客户端的自动化脚本管理器内运行时，候鸟会自动激活此虚拟环境。

如果您希望在外部命令行独立调试，请先手动激活：

# 进入候鸟安装目录下的 python 目录
cd "C:\Program Files (x86)\Mbbrowser_v7.10.20.219\python"
# 激活虚拟环境
Playwright\Scripts\activate
# 现在可以正常使用 pip 安装或运行 playwright 相关命令

3. 安装 Playwright Python 库

在激活虚拟环境后（或者在全局环境中独立测试时）：

pip install playwright requests

NOTE

playwright 库会附带安装所需的依赖，但不需要执行 playwright install（安装浏览器），因为我们使用候鸟的浏览器。

---

三、Java 环境

1. 安装 JDK

前往 Adoptium 下载 JDK 11 或 17（推荐 17 LTS）。

验证安装：

java -version

2. 候鸟 Playwright Java 驱动说明

IMPORTANT

候鸟已将 Playwright Java 所需的 JAR 包打包在安装目录中：

候鸟安装目录\
└── lib\
    ├── playwright-1.48.0.jar
    ├── driver-bundle-1.48.0.jar
    └── gson-2.x.jar

当您通过候鸟客户端的脚本管理器运行 Java Playwright 脚本时，会自动提取 driver-bundle 并配置好环境，无需手动操作。

3. Maven / Gradle 项目引入

如果您用 Maven：

<dependency>
  <groupId>com.microsoft.playwright</groupId>
  <artifactId>playwright</artifactId>
  <version>1.50.0</version>
</dependency>

---

四、开启候鸟 ApiServer（所有语言通用）

IMPORTANT

无论您选择哪种语言，都必须先启动 ApiServer 才能让脚本与候鸟通信！

获取 App 鉴权信息

1. 打开候鸟客户端，确保已登录
2. 菜单 → 个人中心 → API 设置
3. 获取（或点击生成）您的 APP_ID 和 APP_KEY

启动 ApiServer

用管理员权限打开 CMD，进入候鸟安装目录：

apiserver.exe --port=8186 --app_id=YOUR_APP_ID --app_key=YOUR_APP_KEY --hide=off

参数	说明	推荐值
--port	监听端口	8186（默认）
--app_id	鉴权 ID	从候鸟个人中心获取
--app_key	鉴权密钥	从候鸟个人中心获取
--hide	浏览器是否隐藏	off（调试阶段建议可见）

启动成功后终端会显示：

ApiServer started at http://127.0.0.1:8186

在浏览器访问 http://127.0.0.1:8186/ 可查看所有可用接口。

---

五、获取环境 Session_ID

在候鸟主面板中，找到您要操作的环境：

• 右键点击 → 复制环境 ID（Session_ID）
• Session_ID 格式：32 位十六进制字符串，如 373808cb37bd63f5f7d92415e736e85f

此 ID 是接下来代码中的核心参数。

---

六、了解 ApiServer 的 ws 返回字段

调用 /api/v1/browser/start 后，候鸟返回的数据结构如下：

{
  "code": 0,
  "message": "success",
  "data": {
    "http": "127.0.0.1:9222",
    "ws": "ws://127.0.0.1:9222/devtools/browser/YOUR-BROWSER-ID"
  }
}

字段	含义	Playwright 使用
data.http	HTTP 形式的调试地址	Selenium 使用此字段
data.ws	WebSocket 形式的 CDP 地址	Playwright 使用此字段 ✅

---

七、环境搭建自检清单

进入下一章前，确保以下全部就绪：

• [ ] 已选定语言（JS / Python / Java），对应运行时已安装
• [ ] playwright 库已安装（JS: npm install playwright；Python: pip install playwright）
• [ ] 候鸟 ApiServer 已启动，浏览器能访问 http://127.0.0.1:8186/
• [ ] 已获取目标环境的 Session_ID
• [ ] 已理解 data.ws 字段是 Playwright 需要的 WebSocket 地址

---

TIP

全部准备完毕？下一章 快速上手：接管候鸟环境 提供三种语言的完整可运行脚本。