做移动端自动化测试的朋友应该都有过这样的经历电脑上装好了Appium跑安卓模拟器跑得飞起结果拿到一台华为鸿蒙手机一连接就各种报错。要么是设备列表里看不到手机要么是Appium Inspector死活拉不起应用要么是跑脚本的时候一直超时。我以前也以为鸿蒙和安卓差不多直接照着安卓的配置来就行结果踩了一堆坑。后来我专门花了一个下午从零开始把Appium针对华为鸿蒙手机的自动化测试环境完整配了一遍把中间的弯路、报错、驱动冲突都记录了下来。这篇文章就是给你梳理一份可以直接照着做的完整配置指南涵盖基础软件准备、hdc工具链、鸿蒙应用的元素定位、以及几个高频疑难问题的处理思路。不管你是刚接触鸿蒙自动化还是已经在安卓环境上吃了很多年经验、现在想扩展鸿蒙设备都能在这篇文章里找到你需要的答案。1. 项目核心需求解析与环境规划1.1 先搞明白鸿蒙设备的自动化到底是怎么回事在动手配置之前有个概念必须得梳理清楚。很多人一上来就搜“鸿蒙自动化”搜出一堆开源鸿蒙OpenHarmony的测试框架然后就开始安装各种包最后发现和自己手上的华为手机完全对不上。问题出在手机上的HarmonyOS和开源鸿蒙系统并不是一回事。目前市面上能买到的华为手机、平板搭载的是HarmonyOS。其中早期的HarmonyOS 2/3/4版本底层保留了对安卓应用兼容的能力也就是说即使系统是鸿蒙它依然可以安装和运行APK格式的安卓应用。这类设备Appium在原理上依然是通过安卓的调试通道ADB来驱动的只是华为在设备连接和权限细节上加入了自己的实现所以需要额外的工具链支持。而最新的HarmonyOS NEXT也就是常说的“纯血鸿蒙”砍掉了安卓兼容层只能安装HAP格式的原生鸿蒙应用。这类设备传统Appium加安卓驱动的方案是跑不通的需要走华为官方提供的测试框架和Appium扩展。所以在配置环境之前你第一件事应该是确认你手上的设备型号和系统版本。举个例子华为Mate 40 Pro设置里显示HarmonyOS 4.0说明是可兼容安卓应用的鸿蒙设备。华为Pura 70系列如果升级到了HarmonyOS NEXT那就是纯血鸿蒙设备。对于绝大多数还在搞自动化测试的朋友来说手上的鸿蒙设备往往还是兼容安卓应用的版本这种场景下用Appium比较顺手也是这篇文章重点讲的环境配置方案。如果你公司有专门的鸿蒙原生测试团队那需要对接的是华为的CloudDevEco测试服务配置路径完全不同就不在这篇文章里展开了。1.2 明确技术选型为什么选择Appium作为自动化框架Appium本身是一个跨平台的自动化测试框架它通过WebDriver协议向下屏蔽了不同平台的差异向上给测试代码提供了一套统一的API。无论你是用Java写、Python写还是用JavaScript写都可以通过这套API控制手机上的应用做点击、滑动、输入等操作。鸿蒙手机在兼容安卓应用的前提下Appium会自动走Android的自动化驱动这一点极大降低了上手门槛。从测试工程的角度选型Appium还有几个实在的好处社区活跃度足够高网上随手就能搜到各种问题的解决方案不像某些商业测试框架出了问题只能提工单。支持的语言多样团队里不管谁会哪种语言都能很快写出测试脚本。它本身是C/S架构测试脚本在电脑上跑手机只负责接收指令执行不会像某些框架那样需要在手机上装一个臃肿的Agent。当然Appium也不是没有缺点。最大的问题就在于环境配置比较繁琐尤其是国内网络环境下下载依赖、安装驱动、连接设备都可能出幺蛾子。这篇文章存在的意义就是把这些坑提前帮你踩一遍。1.3 环境规划的整体思维导图按我这个思路你整个环境配置过程可以拆成这么几层基础运行时Java和Node.js。Appium是Node.js服务而安卓驱动工具链依赖Java。设备连接层华为hdc工具相当于安卓的adb用于电脑和鸿蒙手机通信。自动化服务层Appium Server及Appium Inspector。测试代码层一个简单的Python示例脚本用于验证整个链路通不通。理解这个分层逻辑之后你配置的时候就不会慌了。每一步解决一层问题遇到报错时你能快速定位是哪个环节出了问题而不至于把所有锅都甩给Appium。2. 环境配置前的准备与版本选型2.1 基础软件安装Java与Node.js的环境要求Appium从2.0版本开始对Node.js的版本要求比较严格。我最初用的是Node.js 12的老版本安装Appium的时候直接提示“当前Node版本不受支持”后来换成了Node.js 16 LTS版本才顺利通过。这里建议你装Node.js 16或18的稳定版具体版本号不用太纠结LTS就行。安装的时候注意勾选“Add to PATH”选项不然后面在命令行里执行node命令会提示找不到。Java这边要装JDK版本建议8以上。华为hdc工具本身不强制要求Java但Appium的安卓驱动在解析应用信息、生成测试报告时可能会用到Java相关工具链。更关键的是如果你后面要接华为的调试服务或者使用某些自动化辅助工具没有Java环境会寸步难行。我装的是JDK 8碰到的问题最少。有人用JDK 17也跑通了但如果你的项目里没有其他强制要求JDK 8够用且稳定。安装完成后老规矩在终端里验证一下node -v java -version如果命令能正常输出版本号说明基础环境没问题可以进行下一步。2.2 华为hdc工具链的全流程安装这是鸿蒙设备配置过程中最容易有陌生感的地方。hdc全称是HarmonyOS Device Connector是华为为鸿蒙设备提供的调试工具类似安卓的adb。Appium要控制华为手机底层必须通过这个工具跟设备建立连接。hdc工具一般有两个来源一是安装了DevEco Studio之后在它的SDK目录里能找到二是从华为开发者官网的“命令行工具”页面下载独立版本。如果你只是做Appium测试不需要写鸿蒙应用那没有必要装几个G的DevEco Studio直接下载独立版hdc就够了。下载之后是个压缩包解压到你想要的目录比如D:\hdc-tool。然后把该目录路径加到系统的PATH环境变量里。这一步很多人会忘记导致后面执行hdc命令时提示“无法识别”。配置好PATH后打开命令行窗口输入hdc -v能输出版本号说明工具安装成功。鸿蒙手机上需要先开启“开发者模式”连续点击“关于手机”里的软件版本号7次然后在“系统和更新”里找到“开发人员选项”把“USB调试”开关打开。这里有个华为特有的细节在开发人员选项里还有一个“仅充电模式下允许ADB调试”的选项如果这个不打开手机连上电脑后只显示充电无法进行自动化调试。不同型号、不同系统的设置位置可能有差异但你按这个思路找基本不会差太远。2.3 手机连接前的准备工作手机连接电脑这个环节建议你提前做好三件事能省去后面一堆麻烦确认USB数据线是支持数据传输的而不是那种只能充电的线。很多初学者找了半天原因最后发现是线不行。手机插上电脑后下拉通知栏把USB连接模式从“仅充电”改成“传输文件”。如果不改某些系统版本下hdc会识别不到设备。如果之前连接过其他设备最好先重启一下手机和电脑的调试服务清理端口占用。现在的华为手机插上数据线后一般会自动安装驱动。如果你的电脑第一次连华为手机且一直提示驱动安装失败可以去华为官网下载华为手机助手或者Hisuite安装过程中会自动把手机驱动一并装上。3. Appium服务端与驱动的安装3.1 全局安装Appium 2.0Appium从2.0版本开始架构上做了比较大的调整原来的安卓驱动UIAutomator2不再默认包含在Appium里而是需要单独安装。这算是个好事因为它让Appium的核心变得更轻量但也意味着你装完Appium之后还要多执行一条命令来装驱动。我用npm全局安装Appiumnpm install -g appium2安装完之后验证一下版本appium -v能输出2.x的版本号就OK。接着安装安卓驱动appium driver install uiautomator2这个命令会从远程仓库下载UIAutomator2驱动及相关依赖。如果你在下载过程中卡住或者一直超时那大概率是网络问题。可以换成国内镜像源后再试一次。npm镜像切换的方法如下npm config set registry https://registry.npmmirror.com切换完镜像重新安装即可。驱动安装成功后可以用下面的命令查看已安装的驱动列表appium driver list3.2 在桌面端启动Appium服务Appium安装好之后有两种方式启动服务。一种是直接在命令行启动输入appium然后回车服务就会默认在4723端口开启。另一种是在测试代码里通过代码方式动态启动服务适合后面做CI集成。我个人习惯是先用命令行方式启动因为这样日志输出比较直观。启动成功之后你会看到类似这样的输出[Appium] Welcome to Appium v2.x.x [Appium] Appium REST http interface listener started on 0.0.0.0:4723这个信息说明Appium服务已经正常启动等待测试代码来连接了。3.3 配置Appium Inspector进行元素定位Appium Inspector是Appium生态里的元素检查工具能帮你在手机上实时查看当前界面的布局结构、控件属性是写自动化脚本的利器。鸿蒙手机上因为走的是安卓兼容层所以Inspectgor的用法和安卓设备几乎一模一样。Inspector现在不需要单独下载安装包它是通过桌面应用方式运行的。你可以在Appium官网下载对应的桌面版本也可以直接通过npm安装。用Inspector连接鸿蒙手机时需要在“Remote Path”里填上/wd/hub端口是4723Desired Capabilities里填上之前准备好的设备参数。连接成功后你会看到手机屏幕的实时截图左侧是界面结构树右侧是控件属性列表。用这个工具我可以快速获取任意控件的resource-idtextclass等属性然后直接填到测试脚本里作为定位依据。这是我每次做App自动化测试都会用到的功能没有它纯粹靠猜测元素属性写脚本效率会低很多。3.4 鸿蒙系统版本与Appium驱动的兼容性问题华为鸿蒙系统在持续迭代过程中对安卓调试协议的兼容性也发生了一些变化。早期HarmonyOS 2.0阶段hdc和adb的指令兼容做得比较好直接用adb命令也能控制设备。到了HarmonyOS 3.0之后华为逐渐弱化了adb通道更加推崇使用hdc导致一些老版本Appium驱动在鸿蒙设备上失效。我实际遇到的情况是在HarmonyOS 4.0的设备上UIAutomator2驱动如果版本过低启动应用时会报io.appium.settings无法安装的错误。解决方法是把驱动升级到最新版本appium driver update uiautomator2如果升级驱动之后问题依然存在还给华为设备的开发者选项里把“USB调试安全设置”也打开允许通过USB调试修改权限或模拟点击。这个选项在部分华为手机上默认是关闭的如果不打开自动化脚本执行到一半可能会因为权限不足而中断。4. 鸿蒙手机与Appium的连接配置实操4.1 使用hdc确认设备连接状态设备连接是整个链路里最容易出问题的一环所以我建议你在启动Appium之前先用hdc确认设备列表明确设备已经正常连接hdc list targets如果输出结果里有一串设备序列号说明设备已被识别。如果提示“Empty”那说明手机和电脑之间还没有建立连接需要检查USB线、调试模式是否打开。如果有多台设备连接后面配置Capabilities时要指定具体的udid否则Appium会报“多个设备无法选择”的错误。连接正常之后还可以用它获取手机的型号和鸿蒙系统版本方便后面填参数。除了通过USB连接hdc还支持WiFi无线连接。对有无线调试需求的朋友这点也值得了解一下因为在实际测试过程中经常需要同时在多台设备上跑测试这时候全部靠数据线连接就不太方便了。hdc无线连接的方式我是通过先USB连接设备然后执行以下命令开启无线调试端口之后再拔掉数据线用网络连接来调试设备。具体的hdc命令你可以在命令行输入hdc help查阅。4.2 获取鸿蒙手机的应用包名与主Activity配置Desired Capabilities的时候需要指定应用包名appPackage和主ActivityappActivity。在鸿蒙手机上获取这两个参数的方式和安卓设备基本一致。我经常用的有两种方式第一种通过hdc命令直接查看当前正在运行的应用包名hdc shell param get const.product.software.version这个命令能获取系统版本。获取前台应用包名可以执行hdc shell uiautomator dump然后查看生成的XML文件。第二种安装应用后用Appium Inspector直接连接并检查先把appPackage填成目标应用的包名appActivity留空连接成功之后Appium会自动解析当前界面的Activity名称。这个方法不用记命令对初学者比较友好。如果你的应用是APK格式还可以用aapt工具快速获取包名和Activity信息。hdc工具包里自带了一个类似功能的工具名字叫aa。在命令行里执行hdc shell aa dump -l能列出当前系统的Activity栈信息。4.3 配置Desired Capabilities参数Appium连接设备时通过Desired Capabilities来声明期望的能力。针对鸿蒙手机我这里提供一个我实测过的推荐配置模板{ platformName: Android, deviceName: HuaweiMate40Pro, platformVersion: 12, appPackage: com.example.app, appActivity: .MainActivity, noReset: true, unicodeKeyboard: true, resetKeyboard: true, automationName: UiAutomator2, udid: 你的设备序列号 }有几个参数需要注意platformName填Android不要填HarmonyOS。因为Appium目前没有单独的HarmonyOS平台定义在兼容安卓应用的鸿蒙设备上填Android才能正确走安卓驱动通道。填HarmonyOS的话Appium会找不到对应的驱动直接报错。automationName填UiAutomator2代表使用UIAutomator2驱动。noReset设为true避免每次跑测试都重置应用数据。如果要做干净的测试环境再改成false。unicodeKeyboard和resetKeyboard建议都设为true避免中文输入时遇到键盘弹不出来的问题。4.4 在测试代码里启动Appium会话配置好Capabilities之后就可以写测试代码来验证连接了。我用Python写的验证脚本代码很简单from appium import webdriver desired_caps { platformName: Android, deviceName: HuaweiMate40Pro, appPackage: com.example.app, appActivity: .MainActivity, noReset: True, automationName: UiAutomator2, udid: 你的设备序列号 } driver webdriver.Remote(http://127.0.0.1:4723/wd/hub, desired_caps) print(driver.current_package) print(driver.current_activity) driver.quit()如果你能看到终端输出了软件包名和Activity名说明Appium连接鸿蒙手机成功自动化环境已经全面打通。5. 常见问题与排查技巧实录5.1 设备识别不了或连接不稳定鸿蒙手机无法被电脑识别是最常见的初级问题。排查顺序我建议如下换一根确认可以传数据的USB线。打开手机开发者选项关掉“仅充电模式下允许ADB调试”开关。重启hdc服务执行hdc kill和hdc start。检查设备管理器里有没有识别到“Android Composite ADB Interface”如果没有说明驱动没装好需要手动更新驱动。我遇到过一个比较隐蔽的问题笔记本电脑的USB口供电不足导致手机连接上后反复断开重连。后来换了一个USB口问题立刻消失。5.2 Appium Inspector无法连接到设备Inspector连接手机失败通常有两种情况。一种是Appium服务没有启动启动着的话Inspector的“Start Session”按钮就不会生效。另一种是Capabilities参数不对尤其是platformName填了HarmonyOS或者udid填错了。还有一种特殊情况如果手机锁屏了或者屏幕熄灭了Inspector连接时可能拿不到界面信息。建议在开发者选项里打开“屏幕常亮”功能或者连接前手动唤醒手机屏幕并解锁。5.3 脚本执行时报错找不到元素Appium脚本跑起来后报“An element could not be located”这类问题大多数情况下不是环境问题而是元素定位策略不对。鸿蒙手机上有一些应用是基于自研UI框架开发的控件属性可能没有标准的resource-id导致用id定位不到。这种情况下我的建议是优先用text文本定位对中文应用支持比较稳定。使用XPath定位但要写相对简洁的表达式避免复杂层级导致性能问题。查看界面结构树确认元素在当前的层级中是否可见。有些元素需要滚动才能显示。5.4 应用启动后立即闪退应用闪退的原因很多最常见的是appActivity配置不对导致应用启动后找不到指定的Activity。建议先手动打开应用然后用hdc命令查询当前的Activity名再填到配置里。也有可能是应用本身就存在启动崩溃的问题这和自动化环境无关需要开发人员处理。5.5 多个设备同时连接时的干扰问题测试机多的时候一台电脑同时控制多台鸿蒙手机是常事。这种情况下如果每台设备上的Appium配置都是一样的执行脚本时会相互干扰。解决方法有两个一是在Capabilities里指定不同的udid二是在启动Appium时使用不同的端口号。我一般是每台设备配一套Appium服务所有设备用同一个脚本分别跑测试效率能提高不少。5.6 常见问题速查表问题现象可能原因解决方案hdc list targets为空USB调试未开启或驱动问题检查开发者选项重装驱动换USB口Inspector无法连接Appium服务未启动或Capabilities错误确认Appium在4723端口监听检查参数配置Appium启动会话超时UIAutomator2驱动版本太低执行appium driver update uiautomator2中文输入失败键盘设置不对配置unicodeKeyboard和resetKeyboard为true应用闪退appActivity配置错误查询真实Activity注意大小写和前缀设备断连USB线通讯不稳定换线、换口或用hdc无线连接5.7 端口占用问题Appium默认监听4723端口如果这个端口被其他程序占用了启动服务时会报错“端口被占用”。在Windows上你可以用以下命令查看端口占用情况netstat -ano | findstr 4723找到占用进程的PID然后在任务管理器里结束对应进程或者直接换一个端口启动Appiumappium -p 4724如果用了非默认端口意味着你的测试代码里远程连接地址也要改成对应的端口号。6. 实操验证与效果测试6.1 跑通第一个鸿蒙设备上的自动化脚本环境配置完成之后我习惯先跑一个最简单的脚本验证全链路。下面是一个示例实现打开一个应用然后等待几秒钟后关闭它import time from appium import webdriver desired_caps { platformName: Android, deviceName: HuaweiP40, appPackage: com.huawei.camera, appActivity: .Camera, noReset: True, automationName: UiAutomator2 } driver webdriver.Remote(http://127.0.0.1:4723/wd/hub, desired_caps) time.sleep(5) driver.quit()这个脚本如果能在真实设备上正常打开相机应用说明环境配置没有问题后续的测试脚本都可以基于这套环境来扩展了。6.2 实战中的性能调优建议环境通了之后如果你想把这套方案真正用到实际项目中有几个性能调优的点值得一提Appium服务启动参数加上--relaxed-security可以在某些场景下减少安全校验导致的延迟。脚本中使用显式等待代替固定延时比如WebDriverWait配合expected_conditions能显著提高脚本稳定性。如果测试用例多建议用pytest或TestNG做用例管理不要全都写在同一个脚本文件里。尽量减少在测试脚本里做大量数据计算这些操作放在服务端执行能够降低手机端的功耗和响应延迟。6.3 集成到CI流水线中的环境准备如果说你不想只在本地跑脚本还想把这套环境配置用到公司的持续集成流水线上那还需要考虑几个额外的问题。第一CI机器上的Node.js、Java、hdc等工具需要提前安装好或者使用Docker容器把环境打包起来。第二CI机器通常是无界面的跑测试时手机通过USB连接到机器上需要保证设备权限对执行用户开放。第三测试脚本里不要写死本机路径尽量使用相对路径这样换环境之后不用改脚本就能跑。我见过不少测试工程本地环境怎么配都正常一上CI就跑挂排查来排查去发现都是因为CI机器上少了某个环境变量或者驱动版本不对。建议你在配置CI环境时先用一个最简脚本验证全链路确认没有问题之后再接入完整测试套件。7. 一些做事的心得体会整套环境配置下来我自己最大的感受是鸿蒙设备的自动化环境搭建难度其实不在于某一个单独步骤有多复杂而在于工具链版本之间的搭配。很多人失败就是因为用了老版本的Appium搭配新版本的鸿蒙系统或者用了不兼容的Java版本导致问题层出不穷。我个人比较推荐的做法是一次性把工具链全部更新到较新的稳定版本宁可花点时间装新版也尽量不要在排错上浪费更多时间。再就是对于华为鸿蒙设备hdc工具链一定要用对它是连接的核心不需要依赖adb但理解adb的人可以很快上手hdc两者在命令行使用习惯上非常接近。最后再分享一个小技巧配置过程中如果报错不要只看报错信息最后一行要把整个错误日志从头到尾扫一遍。很多时候关键信息都藏在中间部分比如UIAutomator2驱动安装失败的具体原因、手机端某个服务崩溃的日志上下文。培养这个习惯你能避免很多“照着网上的教程改了参数却依然失败”的尴尬情况。