Appium UIAutomator2创建会话报socket hang up错误问题排查

问题表现 #

使用Appium开展Android端UI自动化测试时，创建测试会话阶段POST /wd/hub/session接口返回500状态码，无法正常建立测试连接，核心报错日志如下：

[debug] [W3C] Encountered internal error running command: UnknownError: An unknown server-side error occurred while processing the command. Original error: Could not proxy command to the remote server. Original error: socket hang up
[debug] [W3C]     at UIA2Proxy.command (C:\Users\aarif\AppData\Roaming\npm\node_modules\appium\node_modules\appium-base-driver\lib\jsonwp-proxy\proxy.js:274:13)
[debug] [W3C]     at processTicksAndRejections (node:internal/process/task_queues:96:5)
[debug] [W3C]     at AndroidUiautomator2Driver.commands.getDevicePixelRatio (C:\Users\aarif\AppData\Roaming\npm\node_modules\appium\node_modules\appium-uiautomator2-driver\lib\commands\viewport.js:14:10)
[debug] [W3C]     at AndroidUiautomator2Driver.fillDeviceDetails (C:\Users\aarif\AppData\Roaming\npm\node_modules\appium\node_modules\appium-uiautomator2-driver\lib\driver.js:244:28)
[debug] [W3C]     at AndroidUiautomator2Driver.createSession (C:\Users\aarif\AppData\Roaming\npm\node_modules\appium\node_modules\appium-uiautomator2-driver\lib\driver.js:230:7)
[debug] [W3C]     at AppiumDriver.createSession (C:\Users\aarif\AppData\Roaming\npm\node_modules\appium\lib\appium.js:387:35)
[HTTP] <-- POST /wd/hub/session 500 12195 ms - 1315
[debug] [Instrumentation] io.appium.uiautomator2.server.test.AppiumUiAutomator2Server:
Test case skipped
Test case skipped
Test case skipped

===============================================
Suite
Total tests run: 3, Passes: 0, Failures: 0, Skips: 3
Configuration Failures: 1, Skips: 5
===============================================

从日志可以定位到，错误发生在UiAutomator2驱动初始化、拉取设备像素比的阶段，Appium无法将命令代理到设备端运行的UiAutomator2服务，且设备端instrumentation测试套件启动时出现配置失败，所有测试用例被跳过，最终触发socket连接断开报错。

常见触发原因 #

• 设备连接异常，或设备端残留旧的UiAutomator2进程，导致新服务无法正常启动
• Appium、UiAutomator2驱动版本与设备Android版本不兼容，高版本Android使用过旧的Appium 1.x版本时极易出现该问题
• 设备端UiAutomator2服务APK版本与本地驱动版本不匹配，或安装时权限不足
• 国产定制系统默认拦截ADB启动instrumentation、安装应用的操作，未开放对应开发者权限
• 设备端VPN/代理软件占用端口，或ADB端口转发规则异常，导致Appium与设备端服务通信链路中断
• 初始化capabilities配置存在冲突参数，导致服务启动流程被打断

排查修复步骤 #

按优先级从高到低依次排查：

• 基础连接状态校验
  执行adb devices确认设备状态为device，不存在offline、unauthorized的情况，模拟器需等待完全加载进入系统桌面后再发起会话请求；执行以下命令清理设备端残留的UiAutomator2进程，重启Appium后重试：

  adb shell pkill io.appium.uiautomator2.server
  

• 版本与安装包校验
  Android 12及以上版本必须使用Appium 2.0+搭配最新版UiAutomator2驱动，旧版Appium 1.x无高版本Android适配，直接更换版本即可解决；卸载设备上残留的旧版UiAutomator2服务APK，重启Appium后会自动推送匹配版本的安装包：

  adb uninstall io.appium.uiautomator2.server
  adb uninstall io.appium.uiautomator2.server.test
  

• 系统权限与拦截校验
  进入设备开发者选项，手动开启「USB安装」「USB调试（安全设置）」权限，关闭「监控ADB安装应用」类拦截开关，MIUI、ColorOS、鸿蒙等定制系统必须手动配置该类权限，否则会直接拦截instrumentation启动；关闭设备上运行的所有VPN、代理、抓包类软件，这类软件会拦截本地端口通信，导致Appium无法连接设备端服务。
• 配置与链路校验
  先使用最小化capability配置验证会话是否能正常创建，排除参数冲突问题：

  {
    "platformName": "Android",
    "deviceName": "test_device",
    "automationName": "UiAutomator2"
  }
  

  若使用远程设备/云真机，手动执行adb forward tcp:6790 tcp:6790配置端口转发，验证6790端口（UiAutomator2默认服务端口）连通性正常。

内容的提问来源于stack exchange，提问作者Aarif