# Appium 连接操作指南

**适用于 macOS 和 Windows**

从 MoreLogin 客户端获取 ADB 信息，在本机验证云手机连接，再安装 Appium Server 和 UiAutomator2，最后通过 Inspector 查看设备画面和元素。已经安装 MoreLogin 和 Inspector 桌面版的读者可直接打开这两个应用，仍需准备本机 Appium Server。

本指南适用于所有支持 ADB、且 Android 版本符合 [UiAutomator2 驱动要求](https://github.com/appium/appium-uiautomator2-driver#requirements)的 MoreLogin 云手机机型。本文以 Android 15 演示直连和连接码认证，以 Android 15A 演示 SSH 隧道连接。端到端验证覆盖了 Windows 上的 Android 15 和 macOS 上的 Android 15A。其他机型请参照 [ADB 连接指南](/zh/api-reference/cloud-phone/adb)选择连接方式，ADB 连通后可按本文配置 Appium Inspector。

开始前，请确认账号可操作目标云手机的 ADB，并在**同一台电脑**上运行 ADB、Appium Server 和 Appium Inspector。若本机已连上目标云手机，运行 `adb devices -l` 并用 `adb -s "设备标识" shell getprop ro.build.version.release` 确认能读取版本，即可跳到第 7 节。已安装 Appium 3 和 UiAutomator2 的读者可直接从第 8 节开始。

## 1 在 MoreLogin 客户端开启 ADB

macOS 和 Windows 的客户端操作相同。打开「环境 → 云手机」，找到目标设备，在「安卓版本」或机型信息中确认设备的 Android 版本。点击该行「启动」，等云手机进入运行状态。

![图 1  MoreLogin 官方客户端截图：在云手机列表启动单台设备](/assets/phone-start.95b9bc79db700227426c4d3cf1987712c72020e63892286f9a4c05375c5c34de.f59a5fd3.png)

点击该行「启动」或「停止」旁边的 ⋯，选择「开启ADB」。如果菜单显示「关闭ADB」，说明已开启。然后把鼠标移到「ADB」列的绿色「已开启」上，读取浮层里的连接信息。

找不到「ADB」列时，使用列表右侧的字段设置显示该列。菜单里没有「开启ADB」时，检查设备支持情况与当前账号的 ADB 操作权限。

![图 2  MoreLogin macOS 实截图：右侧 ⋯ 菜单中的 Enable ADB（开启ADB）](/assets/ml-enable.f15fca406b0642892c6d64f82f8293ff2ea998b2247fd5f57ae4c359796fc524.f59a5fd3.png)

## 2 识别连接信息并选择连接方式

按「已开启」浮层显示的字段选择一种连接方式：

| 浮层显示 | 下一步 |
|  --- | --- |
| **连接地址**和**连接码** | 按第 5 节直连并认证 |
| **ssh连接**、**ssh密码**和**连接地址** | 按第 6 节先建立 SSH 隧道，再连接 ADB |


设备关机后连接会断开。再次启动后，重新查看客户端浮层，使用当前会话的地址和凭据。

列表较宽时，将底部横向滚动条拉到右端，找到 ADB 列。在英文客户端，开启状态显示为 Enabled。

![图 3  MoreLogin macOS 实截图：Android 15 显示 Connection Address 和 Connection Code，值已遮盖](/assets/ml-popup15.59c6a444c67e1d0293f95d90a2b9076847bc6d300dd700dba298dba5ccc639df.f59a5fd3.png)

![图 4  MoreLogin macOS 实截图：Android 15A 显示 SSH Connection、SSH Password、Connection Address 和 Expiry，值已遮盖](/assets/ml-popup15a.d5026fe728e2d59573d8d7fe1a88187425b447cf3ff9047fbf2b85311195f787.f59a5fd3.png)

## 3 macOS 安装 Android SDK JDK 和 Node.js

安装 Android Studio，打开 SDK Manager。在 SDK Platforms 安装目标 Android 版本，本例使用 Android 15（API 35），在 SDK Tools 安装 Android SDK Platform-Tools，并记录顶部的 Android SDK Location。安装 JDK 17 和 Node.js 24 LTS。已有 Node 24 的 nvm 用户可在终端执行 nvm use 24。

在将要运行 adb 和 Appium 的终端设置环境变量。SDK 路径与下例不同时，改成 SDK Manager 中显示的路径。新开窗口如需运行这些工具，请重新设置，或把 export 行加入自己的 shell 配置。

```bash
export ANDROID_HOME="$HOME/Library/Android/sdk"
export JAVA_HOME="$(/usr/libexec/java_home -v 17)"
export PATH="$ANDROID_HOME/platform-tools:$JAVA_HOME/bin:$PATH"
adb version
java -version
node -v
npm -v
```

确认 adb、Java、Node 和 npm 都能输出版本。Appium 3 需要 npm 10 或更新版本。用 command -v adb 核对 adb 指向 SDK 下的 platform-tools。

MoreLogin ADB 连接指南 [https://guide.morelogin.com/zh/api-reference/cloud-phone/adb](https://guide.morelogin.com/zh/api-reference/cloud-phone/adb)

MoreLogin 云手机管理 [https://support.morelogin.com/en/articles/10204299-cloud-phone-management](https://support.morelogin.com/en/articles/10204299-cloud-phone-management)

## 4 Windows 安装 Android SDK JDK 和 Node.js

安装 Android Studio、Windows 版 JDK 17 和 Node.js 24 LTS 的 MSI 安装包。打开 Android Studio → SDK Manager，安装匹配目标 Android 版本的 Android SDK Platform（本例为 Android 15 / API 35）和 Android SDK Platform-Tools，复制顶部的 Android SDK Location。

按 Win 键搜索「编辑帐户的环境变量」。也可从「运行」执行 systempropertiesadvanced.exe，再点「环境变量」。在「用户变量」中新建 ANDROID_HOME，值填 SDK 根目录，例如 C:\Users\你的账号\AppData\Local\Android\Sdk。新建 JAVA_HOME，值填 JDK 根目录。编辑用户 Path，添加 %ANDROID_HOME%\platform-tools 和 %JAVA_HOME%\bin。

![图 5  Windows 实截图：在上半区编辑用户变量，现有变量已遮盖](/assets/win-env-real.b4f615444872b9fb36ddf6803328d025a9fb183851a98e1e3d29eb3c2f30775f.f59a5fd3.png)

关闭已打开的 PowerShell，再打开新的 PowerShell。下列命令使用 npm.cmd，Appium 步骤使用 appium.cmd，可直接运行 npm 安装生成的命令入口。

```powershell
adb version
java -version
node -v
npm.cmd -v
Get-Command adb
```

如果已经有 `adb.exe`，先运行 `(Get-Command adb).Source` 确认位置。`ANDROID_HOME` 应指向包含 `platform-tools` 的 **SDK 根目录**。即使 `adb version` 能运行，UiAutomator2 仍需要从该目录找到 ADB。若 `java -version` 仍显示旧版 Java，请检查 `JAVA_HOME` 是否指向 JDK 17 根目录，并让 JDK 17 的 `bin` 在 Path 中排在旧版 Java 之前。设置用户变量后重新打开 PowerShell，再运行 Doctor 和启动 Appium。

也可以先在**启动 Appium 的同一个 PowerShell 窗口**里临时设置，路径按本机实际安装位置替换：

```powershell
$env:ANDROID_HOME = 'C:\Android\Sdk'
$env:JAVA_HOME = 'C:\Program Files\Java\jdk-17'
$env:Path = "$env:JAVA_HOME\bin;$env:ANDROID_HOME\platform-tools;$env:Path"
java -version
adb version
```

通过 SSH 隧道连接的机型还需要 OpenSSH Client。运行 ssh -V。若命令不可用，在 Windows 设置搜索「可选功能」→「查看功能」→ 安装 OpenSSH Client，再重新打开 PowerShell。

Windows OpenSSH Client [https://learn.microsoft.com/windows-server/administration/openssh/openssh_install_firstuse](https://learn.microsoft.com/windows-server/administration/openssh/openssh_install_firstuse)

## 5 直连 ADB 并认证（以 Android 15 为例）

选用对应系统的命令，将示例值替换成 MoreLogin 显示的「连接地址」和「连接码」。

### macOS 终端

```bash
ADDR='203.0.113.10:20448'
CODE='替换成客户端连接码'
adb connect "$ADDR"
adb -s "$ADDR" shell "$CODE"
```

### Windows PowerShell

```powershell
$addr = '203.0.113.10:20448'
$code = '替换成客户端连接码'
adb connect $addr
adb -s $addr shell $code
```

`adb connect` 显示 `connected to` 或设备列表显示 `device` 时，还需要执行上面的连接码认证。输入客户端当前显示的连接码，保留大小写。认证可能显示 `OK! Login successful.` 并直接返回本机，也可能进入设备 shell。如果进入设备 shell，输入 `exit` 回到本机命令行。然后在原窗口执行对应的验证命令。

macOS 终端：

```bash
adb devices -l
adb -s "$ADDR" shell getprop ro.build.version.release
```

Windows PowerShell：

```powershell
adb devices -l
adb -s $addr shell getprop ro.build.version.release
```

目标行状态应为 device，getprop 应返回系统版本。复制设备列表第一列，稍后作为 appium:udid。示例地址 203.0.113.10:20448 仅用于展示格式。

## 6 通过 SSH 隧道连接 ADB（以 Android 15A 为例）

两个平台均需打开两个窗口。窗口 A 执行客户端提供的完整「ssh连接」命令，按提示输入「ssh密码」。输入密码时终端通常不会回显字符。

macOS 可直接执行客户端提供的命令。如果命令带 -Nf，成功后 SSH 会在后台维持隧道。Windows 在 PowerShell 中执行同一条命令。若 Windows 客户端的 ssh 不支持后台参数，把结尾的 -Nf 改成 -N，并保持窗口 A 开着。保留客户端提供的用户名、SSH 主机、SSH 端口及 -L 远端目标。

在窗口 B 先替换变量中的地址，再执行命令。后续截图里的 `9897` 是示例端口。实测 MoreLogin 下发了其他动态端口，请原样复制浮层 Connection Address，或查看 SSH 命令的 -L 本地监听端口。

macOS 终端：

```bash
ADDR='替换为浮层里的连接地址'
adb connect "$ADDR"
adb devices -l
adb -s "$ADDR" shell getprop ro.build.version.release
```

Windows PowerShell：

```powershell
$addr = '替换为浮层里的连接地址'
adb connect $addr
adb devices -l
adb -s $addr shell getprop ro.build.version.release
```

目标行状态应为 device，getprop 应返回系统版本。复制设备列表第一列作为 `appium:udid`。保留列表显示的主机名和端口，包括 `localhost` 或 `127.0.0.1` 的写法。

实测 SSH 命令使用 -Nf，返回终端提示符后隧道仍在运行。实际设备在 ADB 中成功上线，读取到 Android 15 和 API 35。Windows 若改为 -N，窗口持续占用是预期行为。

如果 adb connect 失败，先看窗口 A 有无登录失败或端口占用提示。云手机重启、隧道退出或连接信息过期时，先恢复 SSH 隧道，再重新 adb connect。

## 7 安装 Appium Server 和 UiAutomator2

在已有 SDK、JDK 和 Node.js 的系统上执行。安装驱动前，如果 Appium 已运行，在其终端按 Ctrl+C 停止。已有 Appium 3 或已装好 UiAutomator2 时，跳过对应的安装命令。驱动安装完后，确认 installed 列表出现 uiautomator2，再运行 Doctor 检查必需依赖。

### macOS 终端

```bash
npm install -g appium@3
appium --version
appium driver install uiautomator2
appium driver list --installed
appium driver doctor uiautomator2
```

### Windows PowerShell

```powershell
npm.cmd install -g appium@3
appium.cmd --version
appium.cmd driver install uiautomator2
appium.cmd driver list --installed
appium.cmd driver doctor uiautomator2
```

![图 6  macOS 实测安装输出节选，Doctor 命令见上方](/assets/install-log.a5decf383b0ae35b7d1f11c15de8362ece67ea6a1d6e1d15dfb36730eef6d022.f59a5fd3.png)

安装时如果日志提示正在寻找兼容驱动版本，等到出现安装成功提示，并用 `appium driver list --installed` 确认。Windows 使用 `appium.cmd`。

Doctor 若提示找不到 ADB 或 Java，请先修正 SDK 和 JDK 路径。若 Doctor 已找到 `adb.exe` 和 `java.exe`，而唯一的必需项提示是找不到 `emulator`，连接已在 ADB 列表中上线的 MoreLogin 云手机时可以继续。远程云手机验证无需启动本地 Android 模拟器。若 Windows 找不到 appium.cmd，运行 npm.cmd prefix -g，将返回的目录加入用户 Path，并重开 PowerShell。

Appium Server 安装 [https://appium.io/docs/en/3.2/quickstart/install/](https://appium.io/docs/en/3.2/quickstart/install/)

UiAutomator2 安装 [https://appium.io/docs/en/latest/quickstart/uiauto2-driver/](https://appium.io/docs/en/latest/quickstart/uiauto2-driver/)

## 8 启动并验证本机 Appium Server

保持云手机 ADB 在线。在本机终端启动 Appium Server，启动后保持窗口开着。每次使用 Inspector 都需要有可用的 Appium Server。

### macOS 终端

```bash
appium --address 127.0.0.1 --port 4723 --base-path /
```

### Windows PowerShell

```powershell
appium.cmd --address 127.0.0.1 --port 4723 --base-path /
```

![图 7  macOS 本机 4723 端口的 /status 实测输出节选](/assets/server-log.72468e1bd9a90ce054f6d5b556223b5be44dfe88c90d28ab8869b21b975ec3f5.f59a5fd3.png)

另开一个窗口测试 /status。收到 JSON 且 value.ready 为 true，再打开 Inspector。Windows 使用 curl.exe。

macOS 终端：

```bash
curl --max-time 5 http://127.0.0.1:4723/status
```

Windows PowerShell：

```powershell
curl.exe --max-time 5 http://127.0.0.1:4723/status
```

日志出现 EADDRINUSE 时，先确认 4723 是否已运行预期的 Appium Server。macOS 用 lsof -nP -iTCP:4723 -sTCP:LISTEN，Windows 用 Get-NetTCPConnection -LocalPort 4723 -State Listen。

## 9 安装并打开 Appium Inspector

已经装好 Inspector 桌面版时，直接打开现有应用。首次安装时，从 Appium Inspector 官方 GitHub Releases 展开 Assets，按操作系统和 CPU 架构选择安装包。

### macOS

Apple Silicon 选 arm64 的 .dmg，Intel Mac 选 x64 的 .dmg。打开安装包，将 Appium Inspector 拖到 Applications，然后从 Finder 的「应用程序」打开。

![图 8  Appium Inspector 官方 macOS 截图：从 Finder 打开应用](/assets/mac-install.bba082b5fdb191344cf028f57b93134dd85b0e82cdc9ae1f9b7cadfa956d6cb0.f59a5fd3.png)

### Windows

在「设置 → 系统 → 系统信息」查看系统类型。下载官方发布的 Windows .exe 安装程序。若当前版本按架构分列，再根据系统类型选 x64 或 arm64。运行官方安装包，按安装界面完成，再从「开始」菜单打开 Appium Inspector。若系统阻止打开，按企业设备策略处理。

![图 9  Windows Chrome 实截图：展开 Assets 后选择 win.exe，版本号随发布变化](/assets/win-assets.b5266f65e64f3ce6db8c0056baddf305df0162d56df807c11460d2746fbf2597.f59a5fd3.png)

官方下载：[https://github.com/appium/appium-inspector/releases](https://github.com/appium/appium-inspector/releases)

## Windows 安装向导

下载完成后双击安装程序。选择「仅为我安装」，点击「下一步」。保留默认安装位置或选择自己的目录，然后点击「安装」。

*画面文字已译为英文*

![图 10  Windows 实截图：选择安装范围和安装位置，用户名和路径已遮盖 (画面文字已译为英文)](/assets/win-setup-steps.1d5d82f64c8166a167cba488022ac777eaafafbce700516aed6ec330180376dd.f59a5fd3.png)

等待文件安装完成。勾选「运行 Appium Inspector」，点击「完成」打开应用。以后可从「开始」菜单启动。

![图 11  Windows 实截图：安装成功后的完成页 (画面文字已译为英文)](/assets/win-finish.cd7d1848bbff51814fc0a58112d0a52be56099e1e63272c0f1f420bcef51e69b.f59a5fd3.png)

Appium Inspector 安装 [https://appium.github.io/appium-inspector/2026.11/getting-started/](https://appium.github.io/appium-inspector/2026.11/getting-started/)

## 10 在 Inspector 创建 Android 会话

macOS 与 Windows 填法相同。在 Appium Server 页签，把 Remote Host 填成 127.0.0.1，Remote Port 填 4723，Remote Path 填 /。保持 SSL 和 Use Proxy 未勾选。

**`127.0.0.1:4723` 是 Appium Server 地址。** 云手机的直连地址或 SSH 转发后的本机 ADB 地址用于识别设备，填写在 `appium:udid`。

在 Capability Builder 中点击 JSON Representation 旁的铅笔，粘贴下面的 JSON 并保存。把 appium:udid 改成 adb devices -l 中目标行的第一列。Android 15 通常填写云手机直连地址，Android 15A 填写本机 ADB 转发地址。

```json
{
  "platformName": "Android",
  "appium:automationName": "UiAutomator2",
  "appium:udid": "localhost:9897",
  "appium:noReset": true
}
```

![图 12  macOS Inspector 实截图：Android 15A 的 UiAutomator2 会话参数和 Start Session，实际端口已遮盖。](/assets/ins-live-config-clean.0a96592d5cad6efac039cb0d3c3f74ac79119260a81498ca76468c6acc9f2da0.f59a5fd3.png)

点击右下角 Start Session。首次会话可能需要安装并启动设备端 UiAutomator2 组件，等待 Appium 终端给出结果。

## Windows Inspector 配置实图

Windows 安装完成打开 Inspector 后，Server 地址同样填 127.0.0.1、4723 和 /，保持 SSL 关闭。Remote Path 如已显示默认 /，可以直接使用。启动会话前，确认 Appium Server 和 ADB 都在运行 Windows Inspector 的同一台电脑上。

![图 13  Windows 实截图：本机服务器和 Android UiAutomator2 参数。9897 仅用于示例。](/assets/win-config.2d5344fa51514e241c2ec951a9df46ae0e952fbc67d78b74f68840f653f211c8.f59a5fd3.png)

图中通过 Capability Builder 添加 udid 和布尔型 noReset，并保留自动补充 Appium 参数前缀的勾选。也可点击铅笔，用第 10 节的完整 JSON 一次填写四项，包括 appium:noReset。将示例值换成设备列表第一列，再点 Start Session。

图中是 Windows 配置示例。实际会话以设备画面和元素树加载成功为准。

## 11 确认连接和定位故障

![图 14  Windows 实测：Android 15 直连后在 Inspector 中显示设备画面和 App Source](/assets/win-android15-session.c59074d8c5ae9c482ba5ae6a7b0e274bfb54fdbbdc8da8221fe1b6c2aad33564.f59a5fd3.png)

Windows 实测使用 Appium 3.9.1、UiAutomator2 8.7.3 和 JDK 17。直连认证成功后，ADB 读到 Android 15 和 API 35。Appium 的 `/status` 返回 `ready: true`，Inspector 的 `Start Session` 成功显示画面和元素树。

![图 15  macOS 实测：Android 15A 在 Inspector 显示设备画面和 App Source](/assets/ins-live-session.5ddc67ab553c8e01fff640fcadcaf3101e727d67d6a1218b8c6a5f2f37fb5d07.f59a5fd3.png)

本次已在 macOS 用 Inspector 的 Start Session 实测 Android 15A，取得设备画面和元素树。打开目标 App 后，点击 Inspector 的刷新按钮获取最新画面。结束时关闭 Inspector 会话。无需继续调试时，可用 adb disconnect 加设备标识断开对应设备，并关闭为该设备建立的 SSH 隧道。

![图 16  macOS Inspector 实截图：本机 Appium Server 连接失败提示](/assets/inspector-error.c92fcbb330e6febf3dc20cb6837233fafe583a8968173fb722d902fc7de9da60.f59a5fd3.png)

Inspector 提示 Could not connect to Appium server URL：先执行第 8 节的 /status 检查。若失败，检查 Appium 进程、监听端口、Remote Path 和 SSL。若 /status 正常，查看点击 Start Session 后的服务日志。

直连时看到 `Access denied! Invalid password.`：即使设备处于 `device` 状态，仍需使用客户端当前显示的连接码执行认证。认证后重新检查 `getprop`。如果当前连接的地址或连接码已刷新，重新获取两者并重连。

日志提示找不到设备：在启动 Appium 的同一台电脑运行 adb devices -l，确保状态为 device 且 UDID 与第一列完全相同。使用直连的设备检查连接码认证，使用 SSH 的设备检查隧道和有效期。设备显示 `offline` 或 `unauthorized` 时，先恢复 ADB 连接和认证，再重试 `Start Session`。

日志提示找不到 UiAutomator2：在运行服务的同一账户和 Node 环境下检查 appium driver list --installed，补装后重启服务。