Appium Inspector连接Flutter应用失败：无法连接Dart Observatory URL

问题场景 #

你配置的Appium Capabilities如下：

{
  "appium:automationName": "Flutter",
  "appium:platformName": "Android",
  "appium:deviceName": "emulator-5554",
  "appium:app": "app-base-debug.apk",
  "appium:appPackage": "com.app.example",
  "appium:appActivity": "com.app.example.MainActivity"
}

创建会话时触发错误：

Failed to create session. An unknown server-side error occurred while processing the command. Original error: Cannot connect to the Dart Observatory URL ws://127.0.0.1:39199/r5EjPR0pGpc=/ws. Check the server log for more details

已安装的驱动列表：

• uiautomator2@3.9.3 [installed (npm)]
• flutter@2.11.0 [installed (npm)]
• xcuitest@7.34.1 [installed (npm)]

使用wscat -c ws://127.0.0.1:39199测试返回error: socket hang up，iOS平台存在相同问题，但将automationName改为UiAutomator2可正常创建会话。

核心原因 #

Dart Observatory是Flutter应用的调试服务，Appium Flutter驱动依赖它实现元素识别与操作。连接失败通常源于调试服务未正确启动、端口映射异常，或应用未以调试模式运行。

解决步骤 #

1. 确保应用为Debug编译产物 #

Flutter仅在Debug版本中开启Dart Observatory：

• 重新编译Debug包：flutter build apk --debug
• 确认编译过程未手动关闭调试模式（Flutter默认Debug包自动开启）

2. 手动启动应用并固定Observatory端口 #

通过adb强制指定端口，避免随机端口的映射问题：

1. 卸载设备上的旧应用：adb uninstall com.app.example
2. 安装Debug包：adb install app-base-debug.apk
3. 启动应用并指定端口：adb shell am start -n com.app.example/com.app.example.MainActivity --enable-debugging --observatory-port=8181
4. 映射端口到本地：adb forward tcp:8181 tcp:8181
5. 验证连接：wscat -c ws://127.0.0.1:8181/ws，能成功连接则说明服务正常

3. 修改Appium Capabilities配置 #

添加固定端口参数，让Appium直接连接指定端口：

{
  "appium:automationName": "Flutter",
  "appium:platformName": "Android",
  "appium:deviceName": "emulator-5554",
  "appium:app": "app-base-debug.apk",
  "appium:appPackage": "com.app.example",
  "appium:appActivity": "com.app.example.MainActivity",
  "appium:flutterObservatoryPort": "8181"
}

4. 对齐Flutter驱动与SDK版本 #

当前flutter@2.11.0驱动可能与本地Flutter SDK版本不兼容：

• 查看本地Flutter版本：flutter --version
• 升级/降级驱动到匹配版本：
  • 升级：appium driver update flutter
  • 指定版本安装：appium driver install flutter@<匹配版本号>

5. 排查端口占用与adb连接 #

• 检查目标端口是否被占用：
  • Windows：netstat -ano | findstr :8181
  • macOS/Linux：lsof -i :8181
• 确保adb连接正常：adb devices，若设备状态异常，重启adb服务：adb kill-server && adb start-server

6. iOS平台额外处理 #

iOS需额外完成以下操作：

• 确保应用为Debug签名，且在Xcode中开启调试权限
• 执行端口转发：ideviceforwarder --forward 8181:8181（需先安装libimobiledevice）

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