Appium连接华为鸿蒙真机：环境配置与ADB调试全指南

上个月我接了一个自动化需求要在华为鸿蒙手机上跑Appium实现点击通知栏消息后跳转到App内指定页面。本来以为鸿蒙兼容Android环境配置就是“标准动作”结果我在环境准备阶段就折腾了整整两天。网上的教程大多停留在“Appium 安卓模拟器”或者“Appium 小米/三星真机”轮到鸿蒙手机时很多细节都对不上USB调试连不上、ADB识别为unauthorized、Appium Inspector黑屏、刚装好的uiautomator2驱动找不到设备……这篇文章就是我那两天的浓缩版。我会从鸿蒙系统和Appium的底层关系讲起逐步拆解电脑端环境、手机端设置、首次连机和踩坑排查帮你把“appium华为鸿蒙手机自动化环境配置”这件事完整跑通。无论你是刚接触Appium还是已经会跑Android自动化但第一次接鸿蒙真机这篇都值得照着操作一遍。1. 先搞懂鸿蒙手机和Appium的关系再动手装环境很多人一上来就闷头装JDK、装Node、装Appium结果到了最后一步连不上手机才开始怀疑人生。我在第一次配置鸿蒙环境时就吃过这个亏所以我建议你先花十分钟搞清楚底层逻辑后面会顺很多。1.1 鸿蒙系统对ADB的支持程度华为鸿蒙HarmonyOS虽然有自己的微内核架构和分布式能力但在智能手机这个形态上它依然保留了Android应用兼容层也保留了ADB调试通道。也就是说Appium通过ADB连接华为鸿蒙手机和连接一台Android真机在底层路径上是走得通的。ADB这个工具是Android SDK platform-tools里的核心组件鸿蒙手机开启开发者选项里的“USB调试”后系统会对外提供ADB接口。你在电脑上敲adb devices能看到设备adb shell能进到手机系统这些都是Appium能工作的前提。不过这里有个容易忽略的点华为部分机型在鸿蒙系统下默认只允许“传输文件”模式下走ADB如果你选的是“仅充电”可能就连不上。这个细节后面章节会详细说。1.2 APK和HAP的区别决定了Appium能测什么鸿蒙手机上能安装两种应用一种是Android安装包APK比如从应用市场下载的绝大部分App它们以兼容模式运行另一种是鸿蒙原生应用HAP使用ArkUI/ArkTS开发打包格式和应用框架跟Android完全不同。Appium经典的UiAutomator2驱动原理是在设备端注入Java层的自动化测试服务因此它只能作用于Android运行时环境。换句话说对于鸿蒙手机上的APK应用Appium可以完成绝大多数自动化操作对于HAP鸿蒙原生应用Appium没法像操作Android原生控件一样去解析元素需要另找工具。我当时要测的通知栏跳转场景通知本身由APK里的业务模块发送所以Appium完全能处理。如果你要测的是纯鸿蒙原生应用那这篇文章的环境配置逻辑可以参考但自动化方案要换成华为官方测试框架或其他方案。1.3 环境配置总体思路电脑端和手机端两条线搞清楚上面两点整个环境配置的路径就很清晰了其实就是两条线并行端侧需要准备的东西角色说明电脑端JDK、Android SDK platform-tools、Node.js、Appium服务端、uiautomator2驱动、Appium Inspector提供运行环境和调试桥手机端开发者模式、USB调试、ADB授权、正确的USB连接模式提供可被自动化的设备后面所有步骤本质上都是把这两条线分别打通再在Appium Server这一层汇合。2. 电脑端五件套JDK、Android SDK、Node.js、Appium、Appium Inspector电脑端环境配置是最大的坑区尤其是各软件版本之间互相影响。下面是我的推荐方案和具体配置过程。2.1 JDK版本选择与JAVA_HOME配置Appium的UiAutomator2驱动会在设备端编译和运行测试代码内部依赖Java环境所以电脑上必须装JDK。这里建议装JDK 11或JDK 17不要用太老的JDK 8也不要一上来装最新的JDK 21因为部分Appium插件和新版JDK存在兼容问题。安装完成后必须配置两个环境变量JAVA_HOME指向JDK安装目录例如C:\Program Files\Java\jdk-17Path追加%JAVA_HOME%\bin配置完以后打开命令行工具输入java -version验证能正常输出版本号说明成功。很多人在这一步跳过验证直接往后装结果后面Appium Inspector启动时一直报“Java environment not found”又回头排查浪费时间。2.2 Android SDK与platform-tools让ADB命令先跑通Appium连接鸿蒙手机需要调用ADBADB来自Android SDK的platform-tools。你可以只装platform-tools但建议直接装Android SDK因为后面Appium Inspector往往需要读取SDK路径。安装方式有两种下载Android Studio用SDK Manager安装platform-tools和build-tools去Android官方仓库下载commandlinetools用sdkmanager命令行安装。装好后配置环境变量ANDROID_HOME指向SDK根目录例如D:\Android\SdkPath追加%ANDROID_HOME%\platform-tools和%ANDROID_HOME%\build-tools\...对应版本目录验证方式先adb version再连接手机后adb devices能列出设备就说明ADB这层通了。2.3 Node.js安装与Appium服务端、驱动安装Appium服务端本身是Node.js程序所以Node.js是必须的。推荐安装LTS版本比如Node.js 16或18。安装时保持默认选项即可记得勾选“Add to PATH”。装完后用npm全局安装Appiumnpm install -g appium安装完成后查看版本appium --versionAppium 2.x版本把驱动拆成了独立模块所以还需要单独安装UiAutomator2驱动appium driver install uiautomator2这一步很容易被忽略。我第一次装完Appium 2.0后没装驱动运行脚本时一直报“Could not load a driver for platformName Android”当时还以为是环境变量的问题排查了很久。安装驱动时需要联网如果你网络访问外网速度不太稳建议使用国内可访问的镜像源或者多试几次。注意这里只涉及工具下载不需要任何特殊软件。2.4 Appium Inspector的下载与连接参数Appium Inspector是元素定位工具就是我们常说的“看控件树”的界面。旧版Appium Desktop已经停止维护现在建议下载独立的Appium Inspector。下载后第一次打开界面会让你填连接参数这也是最容易搞混淆的地方。以连接本地Appium Server为例{ appium:automationName: UiAutomator2, appium:platformName: Android, appium:platformVersion: 13.0, appium:deviceName: HUAWEI Mate 40 Pro, appium:appPackage: com.example.app, appium:appActivity: .MainActivity, appium:noReset: true }需要注意的是platformVersion不是指鸿蒙版本号而是指Android API对应的版本。你可以在手机上通过“设置-关于手机”查看Android版本也可以在电脑上执行adb shell getprop ro.build.version.release拿到。appPackage和appActivity可以先写一个占位值等到后续用adb shell dumpsys window查询真实值。环境验证阶段更重要的是前面几个参数只要它们正确Inspector就能连接并展示界面。2.5 环境变量检查清单配置这么多环境变量最容易出现的问题就是漏配置或配错路径。下面是我整理的检查清单建议全部核对一遍环境变量目的检查命令JAVA_HOMEAppium依赖Javajava -versionANDROID_HOMEAppium查找ADB和SDKecho %ANDROID_HOME%Path含platform-tools让ADB命令全局可用adb versionNode.jsAppium服务端运行环境node -vnpm -vAppium全局路径启动服务端appium --version如果检查完发现某个命令不可用先重新打开命令行窗口再试因为环境变量修改后不会自动刷新到已打开的终端里。3. 华为鸿蒙手机端的开发者模式与连接验证电脑端软件装完只是成功了一半。另一半在手机端而且鸿蒙手机比普通Android真机多了一些专属设置。3.1 开启开发者模式和USB调试的完整路径鸿蒙手机开启开发者模式的方式和Android一致进入“设置 关于手机”找到“版本号”连续点击7次。系统会提示输入锁屏密码然后自动进入开发者模式。接着返回“设置 系统与更新 开发人员选项”在开发者选项中找到“USB调试”打开它。这个过程看起来很简单但我遇到过一个问题部分鸿蒙手机在打开了“USB调试”之后还必须打开“仅充电模式下允许ADB调试”否则手机插上电脑后即使选了“仅充电”adb devices依然看不到设备。“仅充电模式下允许ADB调试”这个选项是华为手机特有的普通Android手机没有。它的存在是为了安全考虑防止恶意软件通过USB在锁屏状态下调试手机。对自动化测试来说我们通常需要手机插着USB线保持充电状态调试所以这个开关一定要打开。3.2 鸿蒙手机连接电脑的USB模式选择连接电脑时手机会弹出USB连接方式选项常见的有“仅充电”“传输文件”“传输照片”“MIDI”等。Appium连接阶段建议选择“传输文件”模式不要选“仅充电”因为部分鸿蒙机型在“仅充电”模式下不暴露ADB接口。这里有一个非常隐蔽的坑有些教程说“只要打开了仅充电模式下允许ADB调试即使选仅充电也能连”。我在鸿蒙3.0上实测这句话不完全成立。有的机型确实可以有的机型还是会掉线。最稳妥的方法就是直接选“传输文件”模式然后保持开启“仅充电模式下允许ADB调试”作为兜底。手机连接后第一次执行adb devices手机会弹出“允许USB调试吗”的对话框需要勾选“始终允许使用这台计算机进行调试”然后点允许。如果错过这个弹窗设备列表会显示unauthorized后面再排查是很浪费时间的。3.3 用adb devices和adb shell验证连接完成以上步骤后在电脑命令行执行adb devices正常情况下列表里有一个设备状态是device例如List of devices attached 7YHDU19228001238 device如果列表里啥都没有先执行adb kill-server和adb start-server重启ADB服务再看一遍。这一步能解决大部分“明明插了线但没发现设备”的问题。拿到设备后执行adb shell getprop ro.product.model如果输出的是手机型号比如HUAWEI Mate 40 Pro说明ADB通道完全打通Appium的基础依赖已经就位。3.4 USB驱动问题和无线调试备选方案Windows电脑连接华为手机时偶尔会出现“设备管理器中显示未知设备”或“ADB devices为空”的情况。这通常是缺少USB驱动导致的。解决办法是安装华为手机助手或者单独安装华为USB驱动。如果身边没有USB线或者USB口不稳定可以用无线调试。鸿蒙手机进入开发者选项打开“无线调试”然后执行adb pair 192.168.x.x:port adb connect 192.168.x.x:port无线调试需要手机和电脑在同一局域网内。第一次配对时手机会显示六位配对码输入即可。无线调试的好处是摆脱线缆束缚但缺点是没有有线稳定长时间跑自动化时偶尔会断连。我的建议是环境配置阶段用有线先把基础跑通之后再切换无线。4. 第一次启动Appium Server并完成设备识别电脑端和手机端都准备完毕后就到了“会师”环节让Appium服务端真正识别到鸿蒙手机并用Appium Inspector看到手机界面。4.1 启动Appium服务与初始化uiautomator2驱动在命令行执行appium --address 127.0.0.1 --port 4723看到Appium REST http interface listener started on 127.0.0.1:4723之类的日志说明服务端已经启动。这个命令行窗口不要关闭关了Appium服务就停了。第一次使用UiAutomator2驱动连接设备时Appium会在设备端安装io.appium.uiautomator2.server和io.appium.uiautomator2.server.test这两个APK。这个过程不需要额外操作但需要等待几十秒手机端可能会有安装授权弹窗要允许安装。如果你发现设备端一直提示“安装来源不允许”需要去手机设置里允许通过USB安装应用。这也是鸿蒙手机上比较常见的额外步骤。4.2 通过Appium Inspector连接鸿蒙手机打开Appium Inspector在Remote Path处填写/wd/hubAppium 2.x默认是/wd/hub然后填入之前说的JSON配置。点击“Start Session”按钮如果一切正常Inspector左侧会显示当前手机屏幕快照右侧显示控件层级树。这一步是最激动人心的时刻也是最容易出问题的时候。如果Inspector一直转圈大概率是三种原因appPackage或appActivity错误导致驱动找不到目标App手机锁屏导致UiAutomator2无法截图platformVersion填错导致驱动用错误的Android API级别初始化。我的建议是先用系统桌面或设置App作为目标把appPackage和appActivity写成系统信息应用adb shell dumpsys window | grep -E mCurrentFocus|mFocusedApp这个命令可以查到当前前台界面的包名和Activity直接把输出值填到配置里能避免“找不到Activity”的问题。4.3 实战场景通知栏消息点击的环境验证前面提到我最初的需求是点击通知栏消息后跳转到App内页面。环境验证阶段我并没有直接打开业务App而是做了这样的链路验证先在手机上随便用某个App发一条通知或者用ADB命令模拟一个通知然后用Appium Inspector切换到“更多操作”或“获取通知栏状态”找到通知栏消息对应的控件也可以直接使用ADB下拉通知栏并截图查看。实际上Appium里操作通知栏有几种方式但环境配置阶段我们只需要验证一件事Inspector能否定位到通知栏消息的控件。如果能定位到说明后续编写driver.findElement(...).click()跳转脚本就有了数据基础。后面真正写自动化用例时可以通过adb shell cmd statusbar expand-notifications展开通知栏或者通过Appium的mobile: expandNotifications指令实现但这是后话。环境配置做到这一步已经算是“物理上跑通”了。5. 配置阶段最常见的五个坑以及排查链路这部分我把自己和同事踩过的坑整理出来按“现象、原因、解决方案”三层写你可以直接对标排查。5.1 坑一adb devices有设备但显示unauthorized现象adb devices能看到设备编码状态是unauthorized。原因手机端USB调试授权弹窗没有被点“允许”或者误点了“取消”。排查链路拔掉USB线重插让手机重新弹出授权框如果还是没弹窗执行adb kill-server再adb start-server去手机开发者选项里找到“撤销USB调试授权”撤销后再重新连接。这个坑的频率极高十次里有八次是因为第一次连接时手速太快没看弹窗。5.2 坑二Appium Inspector一直转圈连不上现象点击Start Session后Inspector持续加载界面没有任何输出。原因Appium服务端没有启动或者驱动没有安装或者驱动和Appium版本不兼容。排查链路先看Appium命令行窗口有没有报错日志没有日志就先执行appium driver list确认uiautomator2驱动状态检查Inspector里Remote Path是不是/wd/hub把appium:automationName和appium:platformName都明确写成UiAutomator2和Android不要留空。这四步能解决绝大多数“转圈”问题。5.3 坑三运行脚本报“Activity不存在”现象用Appium Inspector或代码启动App时报错提示无法找到Activity或者提示Activity used to start app doesnt exist or cannot be launched。原因appPackage和appActivity配置不正确。鸿蒙手机上不是所有应用的入口Activity都能从Manifest里直接预览到特别是经过混淆或动态加载的App。排查方法adb shell dumpsys package 包名 | grep -A 1 android.intent.action.MAIN adb shell dumpsys window | grep mCurrentFocus第一行可以列出应用的主Activity第二行可以获取当前前台窗口。两个命令结合基本能定位到正确入口。另外一个常见原因App还没启动完成驱动就尝试找Activity。可以临时把appium:waitForIdleTimeout调大比如5000毫秒避免误报。5.4 坑四环境变量配置后终端不生效现象刚配置完JAVA_HOME或ANDROID_HOME重新打开命令行执行java -version提示找不到命令。原因Windows会缓存旧的环境变量新设置的变量不会自动加载到已打开的终端窗口甚至可能因为系统环境变量和用户环境变量冲突导致路径不对。排查链路关闭所有命令行窗口重新打开一个新的窗口执行echo %JAVA_HOME%和echo %ANDROID_HOME%看路径是否和实际目录一致检查Path变量里是否有重复或错误的条目。这一步虽然基础但我见过很多人在这个坑里绕圈子明明装对了就是执行不了。5.5 坑五鸿蒙原生应用HAP没法用Appium自动化现象Appium连接成功Inspector也正常打开了手机界面但某个鸿蒙原生应用页面里的元素全部无法识别控件树是一片空或者只有很少的节点。原因HAP应用使用ArkUI渲染很多控件不是原生Android ViewUiAutomator2无法获取其内部控件树。解决方案如果业务App同时提供APK版本优先测试APK版本如果必须测HAP需要引导团队决策是否需要换用华为官方测试框架如DevEco Testing或者通过图像识别脚本辅助定位。这个坑属于“能力边界”问题不是环境配置能解决的。提前了解清楚可以避免后续大规模返工。6. 环境配置完成后的验收清单与我的建议环境配置到这一步已经可以进入实际脚本编写阶段了。但在正式写用例之前我建议你用一张清单做最终验收避免后续莫名奇妙地翻车。6.1 验收清单从头到尾再走一遍检查项操作期望结果Java环境java -version输出JDK版本号Node环境node -v、npm -v输出对应版本号ADB环境adb devices设备状态为deviceAppium服务端命令行启动后显示监听日志端口监听正常Appium驱动appium driver listuiautomator2驱动显示installedInspector连接填入配置后Start Session能看到手机界面和控件树基础控制通过Inspector点击某个坐标或元素手机界面有响应全部通过说明“appium华为鸿蒙手机自动化”的基础环境已经彻底打通接下来不管是写脚本、跑用例还是接入CI都不会再被环境问题卡住。6.2 下一步可以做什么环境通了之后你可以在以下方向继续深入用Appium Inspector获取通知栏、弹窗、悬浮窗等特殊控件的resource-id为点击通知栏跳转场景准备元素定位信息编写Python或Java测试脚本封装启动App、点击通知栏、断言页面跳转这类用例把Capability配置做成公共配置类方便切换不同鸿蒙设备引入Page Object模式把控件定位和业务逻辑分层提高用例的可维护性。我自己的习惯是每次配置完新设备都会保留一份完整的Capability JSON模板和README记录设备型号、鸿蒙版本、Android版本、驱动版本。因为环境升级或换新手机后这些信息能帮你快速定位是版本不兼容还是配置漂移。6.3 一点个人经验最后说一句实在话Appium 华为鸿蒙手机的环境配置放在2025年回头看并没有想象中那么玄乎。只要抓住ADB通、驱动通、参数通这三条主线大部分问题都能在十分钟内定位。真正让我折腾两天的主要原因反而是没有先理解鸿蒙和Android的关系就直接开干导致每次报错都在瞎猜。建议你在操作时也保持这种心态不要一遇到报错就开始百度先想清楚这一层依赖是什么、这个命令在验证什么。把每个环节的验证命令当成“探针”顺着探针的输出一步步缩小范围比乱试一堆教程要高效得多。