在成功订购云手机实例资源后，你可以利用 Android Debug Bridge (ADB) 连接云手机实例进行远程调试。此方法允许开发者或测试人员在本地环境中直观地与云手机交互，进行应用测试、性能分析和问题排查，特别适用于验证应用兼容性、模拟用户操作及进行深度调试的场景。
本文详细介绍如何使用 ADB 和 scrcpy 工具从个人电脑（PC）远程访问和调试云手机实例。

1. 云手机实例的 ADB 连接功能目前仅对认证用户开放。如需使用，请先联系火山引擎云手机技术支持开通功能。
2. 通过 ADB 连接云手机实例的功能仅供调试目的使用，强烈不建议将其用于生产环境或线上业务。
3. 单次 ADB 连接的默认有效时长为 24h，到期请重新连接。

在开始连接和调试云手机之前，请确保完成以下准备工作。

一、开通云手机服务并获取实例

1. 确保你已成功申请并开通云手机服务。
2. 根据你的需求订购云手机实例资源。
   1. 云盘存储方案请参考：资源管理 和 实例管理
   2. 本地存储方案请参考：云机资源管理 和 实例管理

二、在 PC 端安装 ADB

ADB 工具是连接云手机的基础，你需要在 PC 上安装该工具。本章节分别介绍 ADB 在 Windows 和 macOS 系统中的安装方法。

Windows 环境

1. 下载 ADB 工具
   访问 Android SDK Platform-Tools 官方下载页面，下载适用于 Windows 的 platform-tools 压缩包。
   
2. 解压 ADB 工具
   将下载的 platform-tools-rXX.X.X-windows.zip 文件解压至选定目录（例如：D:\Demo\platform-tools）。后续操作将需要在此目录下执行命令。

macOS 环境

方式一：下载离线 zip 包安装

1. 下载 ADB 工具
   访问 Android SDK Platform-Tools 官方下载页面，下载适用于 macOS 的 platform-tools 压缩包。
   
2. 解压 ADB 工具并配置环境变量

   1. 将下载的 platform-tools-rXX.X.X-darwin.zip 文件解压。建议将解压后的 platform-tools 文件夹放置到一个固定、不常改动的目录下，避免误删（例如：~/Downloads/platform-tools 或 ~/Library/Android/sdk/platform-tools）。

   2. 打开终端（Terminal），编辑你的 shell 配置文件（如 ~/.zshrc 或 ~/.bash_profile，取决于你使用的 shell），添加以下命令行，将<platform-tools解压路径> 替换为实际路径：

      # 解压路径以 ~/Downloads/platform-tools 为例
      export PATH="$PATH:~/Downloads/platform-tools"
      

   3. 保存文件后，执行 source ~/.zshrc (或 source ~/.bash_profile) 或重启终端使配置生效。

   4. 执行 adb version 验证 ADB 是否配置成功。如果看到版本信息，则表示配置成功。
      

方式二：使用 Homebrew 包管理工具安装

使用 Homebrew 安装能够自动处理 PATH 环境变量，且可与其他通过 Homebrew 安装的工具管理方式一致。使用前提：请确保你已经安装了 Homebrew，可在终端（Terminal）中输入 brew --version 命令验证。

1. 打开终端（Terminal）。

2. （可选但推荐）执行 brew update 更新 Homebrew。

3. 执行以下命令安装 android-platform-tools。
   Homebrew 会自动下载 android-platform-tools（其中包含 adb 等工具）并将其安装到正确的位置。同时，它会自动创建符号链接，使得这些命令可以在任何路径下直接运行。

   brew install android-platform-tools
   

4. 执行以下命令验证是否安装成功。

   adb version
   

三、在 PC 安装 scrcpy

在 PC 端安装并配置 scrcpy 开源工具， 用于将云手机屏幕投射到 PC 并进行控制。本章节分别介绍 scrcpy 在 Windows 和 macOS 系统中的安装方法。

Windows 环境

1. 下载 scrcpy
   访问 scrcpy 的 GitHub Releases ，找到 Windows 环境下获取应用的入口并下载。

2. 解压 scrcpy
   将下载的 zip 文件解压至选定的目录（例如：D:\Demo\scrcpy）。scrcpy.exe 位于此目录中。

macOS 环境

安装 scrcpy

1. 访问 scrcpy 的 GitHub Releases 页面 ，找到 macOS 环境下获取应用的入口并点击进入。
   
2. 按照页面执行步骤使用 Homebrew 进行安装。
   
3. 安装完成后，你可以通过 scrcpy --version 命令验证 scrcpy 是否成功安装。

完成环境准备后，按照以下步骤连接并调试你的云手机实例。

一、创建认证密钥对

为保障连接安全，ADB 远程连接云手机采用了非对称加密技术建立信任关系，确保只有你授权的电脑（PC）才能访问云手机实例。其核心为由一个公钥（Public Key）和一个私钥（Private Key）组成的密钥对，私钥存放至本地，公钥上传至云手机服务端。认证流程如下：

1. 当 PC 尝试通过 ADB 连接云手机时，会用本地的私钥对连接请求进行签名。
2. 云手机服务端收到请求后，会用预存公钥验证该签名。
3. 签名验证成功，则证明 PC 持有正确的私钥，连接被允许。如果验证失败，连接将被拒绝。

你可以通过以下两种方式创建和配置密钥对，其主要区别在于密钥对的生成位置和流向：

• 导入已有公钥：密钥对在 PC 本地生成，将公钥从本地 PC 上传至云手机控制台。
• 自动创建密钥对：密钥对在火山引擎云手机平台的服务器上生成，私钥从云手机控制台下载至本地 PC。

两种方式的安全等级完全相同，你可以根据自己的偏好任选其一。

方式一：导入已有公钥

若选择本方式，你需先在本地生成密钥对，然后将公钥上传至控制台。

1. 生成 ADB 密钥对

• Windows
  1. 打开命令提示符（CMD）或 PowerShell。
  2. 使用 cd 命令切换至解压 platform-tools 的目录，例如：cd D:\Demo\platform-tools。
  3. 执行 adb devices 命令。如果系统中没有 ADB 密钥对，此命令会自动在 C:\Users\<你的用户名>\.android 目录下生成 adbkey（私钥）和 adbkey.pub（公钥）文件。

  提示： 如果需要重新生成密钥对，可以先执行 adb kill-server，然后再执行 adb devices。
  

• macOS
  1. 打开终端（Terminal）。
  2. 切换到 platform-tools 目录下，执行 adb devices 命令。如果系统中没有 ADB 密钥对，此命令会自动在 ~/.android 目录下生成 adbkey（私钥）和 adbkey.pub（公钥）文件。

  提示： 如果需要重新生成密钥对，可以先执行 adb kill-server，然后再执行 adb devices。

2. 将公钥导入云手机控制台
   1. 使用文本编辑器打开上一步生成的 adbkey.pub 公钥文件，并复制其中全部内容。
   2. 打开火山引擎云手机控制台，进入目标业务的 ADB 密钥管理页面。
   3. 点击 创建密钥对。
   4. 选择 导入已有公钥 的创建方式。
   5. 将复制的公钥文件内容粘贴到公钥内容文本框中。
   6. 为密钥对命名，然后点击 确定 完成创建。
   7. 当通过 ADB 请求连接云手机时，系统将校验 PC 本地私钥是否与已导入的公钥相匹配，若公私密钥成功配对则允许建连。
      

方式二：自动创建密钥对

若未在本地生成密钥对，可选择系统自动创建密钥对。

1. 在云手机控制台生成密钥对
   1. 打开火山引擎云手机控制台，进入目标业务的 ADB 密钥管理页面。
   2. 点击 创建密钥对。
   3. 选择 自动创建密钥对 的创建方式。
   4. 为密钥对命名（以下以“adbkey”为例），然后点击 确定 完成创建。
   5. 此时会自动下载一份以密钥对名称命名的私钥文件至本地，公钥将保存在系统后台。
2. 配置 ADB 认证密钥路径

   1. 将自动下载的私钥文件移至 ~/.android 目录下。

   2. 指定环境变量为私钥文件路径。

      export ADB_VENDOR_KEYS=$HOME/.android/adbkey
      

   3. 当通过 ADB 请求连接云手机时，系统将校验 PC 本地私钥是否与系统后台的公钥相匹配，若公私密钥成功配对则允许建连。

二、开启云手机实例的 ADB 连接功能

连接业务下已创建的云手机实例进行调试前，你需要启用目标实例的 ADB 连接功能，并获取其连接地址。

1. 进入云手机控制台的「实例列表」页面。
2. 找到需要调试的目标实例，在其操作列中点击 ... > 开启 ADB。系统将为该实例启用 ADB 连接。
   
3. 在实例列表中，可以看到目标实例当前的 ADB 状态、用于公网连接的 ADB 地址（包括 public_ip 和 public_port）以及当前的 ADB 的失效时间。
   

三、通过 ADB 连接云手机

创建密钥对并开启云手机实例的 ADB 连接功能后，你可以使用 PC 上的 ADB 工具与云手机实例建立远程连接。

1. 执行连接命令

   1. Windows: 打开命令提示符（CMD）或 PowerShell，并使用 cd 命令切换到你的 platform-tools 目录 (例如: cd D:\Demo\platform-tools)。
   2. macOS: 打开终端（Terminal）。由于 ADB 通常已配置到 PATH，无需切换目录。
   3. 执行以下命令，将 public_ip 和 public_port 替换为你在上一步获取到的实际 IP 地址和端口号：

   adb connect <public_ip>:<public_port>
   

2. 验证连接状态 执行 adb devices 命令。若连接成功，你将在设备列表中看到类似 118.190.XX.XX:5555 device 的条目。
   

四、使用 scrcpy 访问和控制云手机

一旦 ADB 连接成功建立，你就可以启动 scrcpy 来查看和操作云手机界面。

• Windows:
  • 打开命令提示符（CMD）或 PowerShell。
  • 使用 cd 命令切换到你解压 scrcpy 的目录 (例如: cd D:\Demo\scrcpy)。
  • 执行 scrcpy.exe。
  • 或者，你可以直接双击该目录下的 scrcpy.exe 文件。
• macOS:
  • 打开终端（Terminal）。
  • 直接执行命令：

    scrcpy
    

成功启动后，云手机的屏幕画面将显示在你的 PC 桌面上，你可以使用鼠标和键盘进行交互操作，如同操作本地 Android 设备一样。

1. 在 macOS 环境中使用 Homebrew 安装 scrcpy 时，出现 brew command not found after installing Homebrew ... warning 提示

可执行如下命令，更多详细信息可参考 https://superuser.com/questions/1621771/brew-command-not-found-after-installing-homebrew-on-an-arm-m1-mac。

eval $(/opt/homebrew/bin/brew shellenv)

2. scrcpy 启动后界面显示黑屏

某些云手机实例可能没有默认的 Launcher (桌面应用)。如果遇到黑屏，你可以尝试通过 ADB 安装一个自定义的 Launcher 应用（例如 Nova Launcher, Lawnchair 等的 APK 文件），然后通过 adb shell am start -n com.packagename/.ActivityName 命令（具体包名和活动名需查阅 Launcher 文档）或在 scrcpy 启动参数中指定 scrcpy --set-launcher com.packagename/.ActivityName 来启动该应用。

3. 云手机连接失败

请通过以下方式排障：

• 检查云手机实例的 ADB 功能是否已开启并且未过期。
• 确认 public_ip 和 public_port 是否正确。
• 检查你的 PC 防火墙或网络安全组策略是否允许到目标 IP 和端口的出站连接。
• 若创建密钥对时选择导入已有公钥，请确保你在云手机平台导入的公钥与你本地 ~/.android/adbkey.pub (macOS) 或 C:\Users\<username>\.android\adbkey.pub (Windows) 文件中的公钥完全一致。如果不确定，可以尝试重新生成本地密钥对并重新导入公钥到云手机控制台（记得重启已开启 ADB 的实例）。