# 蓝叠模拟器 ADB 端口与连接设置（BlueStacks）
> 在 BlueStacks 5 中开启 ADB，找到蓝叠模拟器 ADB 端口，连接 Macro Automation Studio，并解决 Windows 和 Mac 上找不到设备与设备离线的错误。
Source: https://automationmacro.com/zh-CN/docs/bluestacks-setup-guide (设备, updated 2026-09-05)
这篇指南介绍如何通过 ADB 把 BlueStacks（蓝叠模拟器）连接到 Macro Automation Studio（MAS）：开启 ADB、找到蓝叠模拟器 ADB 端口，并把实例添加为设备。内容覆盖 Windows 上的 BlueStacks 5 和面向 Apple Silicon Mac 的 BlueStacks 版本，最后列出大家最常遇到的错误。
## 开始之前
- 已在 Windows 10 或 11，或 Apple Silicon Mac 上安装并登录 MAS。试用期内 MAS 可免费下载；从[下载页](/download)获取。
- 已从 [bluestacks.com](https://www.bluestacks.com/) 安装 BlueStacks 并至少启动过一次。
- 实例已完全启动到安卓主屏幕。
- 要自动化的应用已在 BlueStacks 中安装并登录。
## 1. 安装 BlueStacks
1. 从官方网站下载 BlueStacks 5 并运行安装包。
2. 启动 BlueStacks，等待主屏幕出现。
3. 在把设备添加到 MAS 之前，先安装并登录要自动化的应用。
1. 从 [bluestacks.com/mac](https://www.bluestacks.com/mac) 下载 Apple Silicon 版本 BlueStacks Air。
2. 打开 DMG，把 **BlueStacks** 拖到**应用程序**。
3. 从应用程序启动它，等待主屏幕出现。
安装当前的 BlueStacks 5 版本，让它完成首次启动。
## 2. 推荐设置
MAS 逐像素匹配模板图片，所以截取模板之后显示设置不能再变。从侧边工具栏的齿轮图标打开**设置**，按下表设定：
| 标签页 | 设置项 | 取值 |
|---|---|---|
| **性能** | CPU 分配 | 2 核；开发期间给更多也可以 |
| **性能** | 内存分配 | 4 GB 或更多（如果有） |
| **显示** | 分辨率 | 竖屏，540 x 960 |
| **显示** | 像素密度 | 240 DPI |
点击**保存更改**，BlueStacks 要求时重启实例。按 MAS 基准编写的宏预期 **540x960**、**240 DPI**；你自己写的宏预期的是你在 Asset Lab 中截取时的分辨率。如果运行卡顿，关闭后台应用，给实例分配更多核心和内存。
让 MAS 实例保持稳定的性能和显示设置。
> [!WARNING]
> 截取模板之后再改分辨率或 DPI，每个匹配都会偏移，点击会落到错误的位置。显示设置选定一次，之后保持不变。
## 3. 在 BlueStacks 5 中开启 ADB
BlueStacks 出厂时 ADB 是关闭的。MAS 需要它打开。
1. 点击侧边工具栏的齿轮图标打开**设置**。
2. 点击**高级**标签页。
3. 打开 **Android Debug Bridge**（安卓调试桥）。
4. 点击**保存更改**。
5. 记下开关下方显示的地址，例如 `127.0.0.1:5555`。冒号后面的数字就是 ADB 端口。第一个实例通常得到 5555；下面的截图显示的是 5625。
1. 从侧边工具栏的齿轮图标或顶栏的菜单图标打开**设置**。
2. 查找 Android Debug Bridge 选项。官方的 BlueStacks Air 设置指南列出了性能、显示、图形、偏好设置和关于，没有 ADB 开关。较早的 macOS 版 BlueStacks 在偏好设置中有这个开关。
3. 如果你的版本有这个选项，打开它，保存，并记下 `127.0.0.1` 后面的端口。
4. 如果没有，MAS 无法连接这个版本。请改用在 Mac 上暴露 ADB 的其他模拟器，或使用[云设备](/docs/cloud-devices)。
已打开 Android Debug Bridge 的高级标签页。这里的端口是 5625。
## 4. 蓝叠模拟器 ADB 端口与 MAS 的扫描方式
MAS 不通过运行 `adb devices` 来发现模拟器。它扫描运行中的进程，只有满足以下全部条件时才保留端口：
- 进程名包含 `hd-player` 或 `bluestacks`。
- 端口在 5555 到 8500 之间。
- 套接字监听在 `127.0.0.1`、`0.0.0.0` 或所有网卡上。
匹配的端口会出现在**添加新设备**对话框中，标注为 `Bluestacks`，例如 `5555 - Bluestacks`。MAS 在你打开设备组时以及每次点击**刷新**时扫描。每个 BlueStacks 实例监听自己的端口，所以两个实例会给出两项。
## 5. 在 MAS 中通过 ADB 连接 BlueStacks
1. 在侧边栏打开**设备组**，打开一个组，或新建一个。
2. 点击**添加设备**。
3. 输入不超过 50 个字符的**设备名称**。
4. 在**端口**中选择这个实例对应的 `Bluestacks` 项。列表为空时点击**刷新**。
5. 如果 BlueStacks 显示的端口 MAS 没有列出，选择**自定义端口**并输入。MAS 接受 1024 到 65535。
6. 可选：选择一个**启动宏**。
7. 点击**添加设备**，然后在设备卡片上点击**启动**。
卡片会显示**连接中**，然后是**运行中**。MAS 启动自己的 adb 服务器，移除 `127.0.0.1:` 的任何过期条目，然后对它运行 `adb connect`。
## BlueStacks 上的宏
BlueStacks 自带的宏录制器按固定坐标重放点击。MAS 宏是一段先看屏幕的 Python 脚本：模板匹配找到按钮，OCR 读取文字，重试机制吸收加载缓慢或弹窗。[快速开始](/docs/getting-started)运行你的第一个宏，[图像识别宏](/docs/guides/image-recognition-macros)把录制的流程重建为会看屏幕的宏，[定时任务](/docs/scheduler)让它每天、每周或每月运行。
> [!NOTE]
> 在 MAS 中启动设备之前，先停掉 BlueStacks 的录制器。两者都向同一个屏幕发送输入，会互相干扰。
## 多个 BlueStacks 实例
在**多开管理器**中创建的每个实例都监听自己的 ADB 端口。把每个实例作为单独的设备添加到同一个设备组，给每个指定宏和设置方案，然后在组上使用**全部启动**和**全部停止**。按设备设置参数和代理，参见[设备组](/docs/device-groups)。
## 故障排查
### 在 BlueStacks 5 中开启 ADB
MAS 中的**端口**列表为空，`adb connect 127.0.0.1:5555` 返回 "cannot connect" 或 "connection refused"。ADB 是关闭的。打开**设置**，点击**高级**，打开 **Android Debug Bridge**，点击**保存更改**，重启实例，然后在**添加新设备**中点击**刷新**。如果**高级**标签页没有这个开关，从官方网站安装当前的 BlueStacks 5。
### 查找或更改 ADB 端口
端口显示在 **Android Debug Bridge** 开关下方，形式为 `127.0.0.1:`。BlueStacks 在启动时分配端口，5555 被占用时会换到其他端口，所以创建、克隆或删除实例之后端口可能改变；官方 ADB 指南没有提供手动设定端口的选项。端口变化时，在 MAS 的卡片上点击**编辑设备**并选择新端口。按相同顺序启动实例可以让端口保持稳定。
### ADB 找不到设备
卡片以**错误**结束并显示 "Failed to start device"，日志写着 "unable to connect to device"，或者脚本抛出 `DeviceNotConnectedError`。
- 实例还在启动。等主屏幕出现后再点击**启动**。
- 卡片上的端口不是 BlueStacks 显示的端口。用**编辑设备**修正。
- 一次更新又把 ADB 关掉了。检查**高级**标签页。
- 在终端运行 `adb connect 127.0.0.1:`。返回 "connected to" 就说明 MAS 也能连上。
### 设备显示 offline
`adb devices` 列出 `127.0.0.1: offline`，命令卡住。实例内的 adb 守护进程停止响应了，通常发生在休眠、更新或机器上出现第二个 adb 服务器之后。在卡片上点击**停止**，重启实例，关闭其他运行自带 adb 服务器的工具，然后点击**启动**；MAS 会从头重新连接。仍然离线时，重启 MAS 让它的 adb 服务器干净地启动。更多修复方法见 [ADB 故障排查](/docs/adb-troubleshooting)。
### Mac 上的 BlueStacks ADB
Mac 上有两点不同。第一，MAS 需要一个 adb 可执行文件：它先在应用包内查找，然后是你的 PATH，最后是 Homebrew 的目录。如果 MAS 提示 "ADB executable not found. Please install ADB using your package manager"，用 Homebrew 安装 adb 后重启 MAS：
```bash
brew install android-platform-tools
```
第二，MAS 始终连接 `127.0.0.1`，所以 BlueStacks 必须运行在同一台 Mac 上并暴露 ADB。BlueStacks Air 是 Apple Silicon 上唯一的版本，它的文档所列设置中没有 ADB 开关；没有这个开关，MAS 就无法驱动它。
## 用 Python 控制它
卡片处于**运行中**时，宏的 `src/app.py` 通过 `mas` 包驱动 BlueStacks。端口由 MAS 选择，所以脚本从不引用它。
```python
import mas
size = mas.get_screen_size()
mas.log(f"BlueStacks screen is {size.width}x{size.height}")
match = mas.find_object_retry(1234, total_tries=3, time_sleep=2.0)
if match:
mas.click(match.x, match.y)
```
各命名空间见 [SDK 概览](/docs/sdk)；完整的第一个脚本见[用 Python 控制安卓模拟器](/docs/guides/control-an-emulator-from-python)。