简介面向移动应用自动化测试入门者和初中级测试工程师的 Appium 环境搭建完整笔记。文档从基础概念讲起以雷鸟模拟器与真实设备两条线路介绍 Appium 在移动应用自动化测试中的部署方式覆盖 JDK、Node.js、Android SDK、Appium Desktop、Appium-Python-Client 的下载安装及 ANDROID_HOME 环境变量配置并给出模拟器与真机两类案例演示。压缩包内为 1 个 docx 文档约 884KB目录按基础介绍、环境搭建、模拟器案例演示、真机演示四部分组织便于按需查阅。已有 973 人学习下载是一款聚焦环境准备与连通性调试的实操型资料。文档不仅讲清各组件的作用还通过实例展示如何获取设备参数、配置 Desired Capabilities、启动 APP能帮助读者避开常见配置坑快速搭建并验证可运行的 Appium 测试环境。 有一次给团队搭测试环境装完一堆软件后 Appium 会话死活起不来报错信息换着花样刷屏最后折腾到半夜才发现是电脑里多个 adb 版本在打架。后来带过几个新人发现大家踩的坑高度相似Appium app 自动化测试环境搭建这件事最难的根本不是某个组件装不上而是整套东西之间互相不认。这篇就把我反复重装、帮人排错之后沉淀下来的完整搭法讲清楚——先理解链路再动手装完马上跑通一个真实用例最后把高频报错的排查思路一并梳理完。1. 先看整条链路Appium 环境不是装软件而是组网1.1 一次自动化请求是怎么从电脑走到手机里的很多教程一上来就让你装 JDK、装 Node、装 Android SDK装完就完事。但你不知道这些组件各管哪一段出问题时连该看哪个进程都不知道。一个完整的 Appium 请求链路是这样的测试脚本Client先把操作翻译成 JSON 协议命令发给本机运行的 Appium ServerAppium Server 只是一个中转站它收到命令后转发给对应的 DriverDriver 再通过 adb 把指令送进手机里的自动化组件真正在设备上做点击、滑动、输入等操作然后把结果原路返回。打个比方这跟点外卖很像你测试脚本下单给平台Appium Server平台把订单派给餐厅Driver餐厅做完菜由骑手adb送到家里手机。任何一个环节掉链子饭都到不了嘴边。所以环境搭建的实质是把这条链路完整打通。1.2 各组件职责和它们的脾气给新手列一张组件对应表排查时对着看就知道问题出在哪一环。组件职责容易出错的地方Appium Client 库Python/Java/JS把测试代码转成协议命令版本和 Server 不匹配Appium Server监听端口、转发命令Node 版本过低、端口被占用Driveruiautomator2 / xcuitest驱动 Android/iOS 自动化Appium 2.x 下忘记单独安装adb / 手机端组件底层通信通道多个 adb 版本冲突、设备未授权被测 App接收自动化指令appPackage/appActivity 写错实际排错时先定位是 Server 层面报错、Driver 层面报错还是设备连接层面报错问题就好解决一大半。2. 基础依赖的安装与验证JDK、Node、Android SDK2.1 版本别追新JDK 和 Node 的取舍很多人装环境喜欢装最新版但在 Appium 生态里追新反而容易踩坑。目前最稳的版本组合是JDK 8 或 11Node 18 LTS 或 20 LTS。JDK 17 虽然现代但有些第三方库和旧用例并不会因为新 JDK 就跑得更快反而可能遇到兼容性问题。我见过一个同事直接装 JDK 21Appium 装好了uiautomator2 driver 构建时频繁报错换回 JDK 11 一次通过。装完先验证三件事java -version node -v npm -v注意每次改完环境变量一定要新开一个终端窗口再验证。环境变量是进程级的老窗口里读到的还是旧配置。这个细节我提醒过无数次仍然有人反复栽在上面。2.2 Android SDK不一定装 Android Studio但推荐装严格来说跑 Appium 只需要 Android SDK 里的 platform-tools里面装着 adb和构建工具。但纯命令行方式对新手不友好最省事的方式还是装 Android Studio然后在 SDK Manager 里勾选 Android SDK Platform-Tools。装完后需要配置两个环境变量ANDROID_HOME 指向 SDK 根目录PATH 里加上 platform-tools 和 tools 目录。macOS/Linux 下可以在~/.bashrc或~/.zshrc里加export ANDROID_HOME$HOME/Library/Android/sdk export PATH$PATH:$ANDROID_HOME/platform-tools:$ANDROID_HOME/toolsWindows 则在系统环境变量里新建 ANDROID_HOME并把platform-tools路径追加到 PATH。配好后新开终端运行adb version能输出版本号就说明 SDK 部分通了。2.3 最容易被忽略的 adb 版本冲突这里有个隐藏很深的坑电脑里可能同时存在多个 adb。Android Studio 自带一个 adbplatform-tools 里有一个 adb某些手机助手、模拟器也会带一个 adb。多个 adb 版本并存经常会出现 adb server version doesnt match this client 或者设备突然断开。排查方法很简单分别跑which adbWindows 用where adb看当前用的是哪一份然后把其他第三方工具自带的 adb 移除或改名确保 PATH 里只有一个 adb。我的习惯是统一用 platform-tools 里的 adb版本最干净和 Appium 配套问题最少。3. Appium Server 与 Appium Inspector桌面版退役后的新选择3.1 别再被老教程误导Appium Desktop 已经停更如果你搜索 Appium 环境搭建会看到大量老教程推荐安装 Appium Desktop然后打开那个带界面的服务器。这里要提醒一句Appium Desktop 已经停止维护内置的 Appium Server 停留在老版本跟现在 Appium 2.x 的 Client 库配合经常出问题。现在的推荐组合是命令行启动 Appium Server 独立的 Appium Inspector 做调试。Appium Inspector 专门用来查看页面元素和验证定位表达式类似 Web 开发里的浏览器开发者工具。3.2 安装 Appium 2.x 和 Driver直接通过 npm 全局安装npm install -g appium appium -vAppium 2.x 发生了一个重要变化Driver 不再内置。以前装完 Appium 就能直接用 uiautomator2现在必须手动安装appium driver install uiautomator2跑 Android 就装 uiautomator2跑 iOS 就装 xcuitest。装完后用appium driver list查看当前已安装的 Driver。很多人环境搭完报 The uiautomator2 driver is not installed就是漏了这一条命令。如果 npm 下载慢可以把 registry 换成国内镜像命令不变速度会快很多。3.3 Inspector 的用法比反复跑脚本省事得多先启动 Appium Serverappium默认监听 4723 端口。然后打开 Appium Inspector填好 Capabilities 配置后面会详细讲点连接。成功后会看到手机屏幕的实时快照和元素树点击某个控件就能看到它的 resource-id、text、class 等属性。写测试脚本时直接把这些属性拿过去用不用每次改一行代码就跑一次全脚本调试效率能翻倍。4. 设备连接与 Capabilities环境搭好之后的第一道坎4.1 真机连接从开发者模式到授权弹窗设备连接是新手最头痛的部分。Android 真机要开启开发者模式设置 → 关于手机 → 连点版本号7 次直到提示已进入开发者模式。然后进开发者选项打开USB 调试。连上电脑后手机屏幕会弹出允许 USB 调试吗的对话框这里必须点允许并且勾选始终允许。很多环境下 Session 建立失败就是因为这个弹窗没被处理或者手机锁屏导致弹窗根本看不见。接着在终端跑adb devices看到类似XXXXXX device的输出才算真正连上。如果显示unauthorized说明授权没通过如果显示空列表先检查数据线是不是只能充电不能传数据——这种线我见过太多人拿来调试了。部分国产手机还需要额外开启USB 安装USB 调试安全设置等选项否则自动化过程中安装 Appium Settings 辅助应用时会报错。每个品牌的入口不同但基本都在开发者选项里。4.2 模拟器连接新手的练习首选如果手头没有真机用 Android Studio 自带的 AVD 模拟器完全够用。创建模拟器后启动adb devices里会自动出现emulator-5554这样的设备直接就能用。模拟器调试的好处是重启快、不怕点坏适合初学者先从它练起。唯一要注意的是别同时开多个设备和模拟器否则自动化命令会不知道发给谁。不得已多设备连接时可以在 Capabilities 里通过udid指定或者命令后面加-s 设备序列号。4.3 Capabilities 参数详解Capabilities 是告诉 Appium我要在什么设备上、用什么方式、打开什么应用的配置。下面是 Android 真机/模拟器最常用的一组{ platformName: Android, platformVersion: 13.0, deviceName: emulator-5554, appPackage: com.android.settings, appActivity: .Settings, automationName: UiAutomator2, noReset: true }核心参数含义platformName平台类型Android 或 iOS。platformVersion系统版本可以写具体的版本号也可以省略让 Appium 自动识别。deviceName设备标识模拟器一般是 emulator-5554真机填 adb devices 里显示的序列号。appPackage / appActivity被测应用的包名和启动 Activity。拿到这两个值最简单的方法是先用adb shell dumpsys window | grep mCurrentFocus查当前前台应用的类和包名。automationNameAndroid 固定用 UiAutomator2这也是为什么要单独装这个 driver。noReset不重置应用数据调试阶段强烈建议设成 true否则每次启动用例都会清数据重新走安装流程。autoGrantPermissions如果被测应用启动时需要一堆权限弹窗设成 true 可以自动授权。5. 跑通首个自动化用例与高频报错排查链路5.1 一个可直接运行的 Python 示例先安装 Python 客户端库pip install Appium-Python-Client然后写一个最简单的脚本启动系统设置应用并读取当前包名from appium import webdriver desired_caps { platformName: Android, platformVersion: 13.0, deviceName: emulator-5554, automationName: UiAutomator2, appPackage: com.android.settings, appActivity: .Settings, noReset: True } driver webdriver.Remote(http://127.0.0.1:4723, desired_caps) print(driver.current_package()) driver.quit()运行前提是 Appium Server 已经在另一个终端跑着。看到控制台输出com.android.settings就说明从 Client 到 Server 到 Driver 再到设备的整条链路全部通了。此时恭喜你Appium 环境搭建的核心目标已经达成接下来可以往里面填各种业务操作了。5.2 高频报错的定位思路把我在实际调试中遇到最多、新人也最容易卡住的报错整理成一张表按这个顺序排查大部分 Session 建立失败的问题都能解决。报错关键词常见原因排查顺序Could not find a connected Android deviceadb 没识别到设备先跑 adb devices再检查授权和线材adb server version doesnt match this client多个 adb 版本冲突which adb 定位所有 adb统一版本uiautomator2 driver is not installedAppium 2.x 未装 driverappium driver install uiautomator2Failed to create session原因最杂看完整日志最后几行多半是 Capabilities 配置问题Settings App could not be launched权限弹窗未授权重新插拔 USB勾选始终允许An unknown server-side error occurred常跟 Activity 相关核对 appPackage/appActivity 是否真实存在有个经验值得单独说报错信息一定要看最后 20 行而不是开头那几行。Appium 日志是链式输出真正的根因通常藏在末尾的某个堆栈里。很多人一看到开头一个红字 Error 就慌其实是自乱了阵脚。5.3 一次完整的排查案例有次帮一个同事在 Windows 上排查环境日志一直报 io.appium.settings 启动失败。她以为是 Appium 装坏了重装了三遍问题还在。我过去看了一眼发现手机屏幕一直锁着那台手机 USB 调试授权弹窗被晾在一边Appium 根本没权限安装辅助应用。解决方法很简单手机解锁重新插一下 USB把允许 USB 调试和始终允许都确认一遍。这类问题跟技术无关却最容易把新手卡死所以遇到环境问题先确认设备层面再往上层查。还有一次是 Node 版本太旧Appium Server 启动后端口一直在监听但一转发起 Session 就崩。用appium --version看版本没问题查日志才发现某个依赖包在高版本 Node 下编译不过。换用 Node 18 LTS 后一切恢复。这就是为什么前面强调版本组合工具链的兼容性远比图新重要。根据我个人的搭环境经验第一次搭最好在自己经常用的电脑上完整跑通一次哪怕多花点时间也别着急换机器。跑通一次之后你对整套链路会有一个整体感知后面再换机器、换系统、帮别人排错心里都有底。如果你后续打算做 iOS 自动化那就在这个基础上再装 xcuitest driver原理是相通的只是设备侧的要求不一样。本文还有配套的精品资源点击获取 Appium自动化测试环境搭建全指南：从链路原理到报错排查
简介面向移动应用自动化测试入门者和初中级测试工程师的 Appium 环境搭建完整笔记。文档从基础概念讲起以雷鸟模拟器与真实设备两条线路介绍 Appium 在移动应用自动化测试中的部署方式覆盖 JDK、Node.js、Android SDK、Appium Desktop、Appium-Python-Client 的下载安装及 ANDROID_HOME 环境变量配置并给出模拟器与真机两类案例演示。压缩包内为 1 个 docx 文档约 884KB目录按基础介绍、环境搭建、模拟器案例演示、真机演示四部分组织便于按需查阅。已有 973 人学习下载是一款聚焦环境准备与连通性调试的实操型资料。文档不仅讲清各组件的作用还通过实例展示如何获取设备参数、配置 Desired Capabilities、启动 APP能帮助读者避开常见配置坑快速搭建并验证可运行的 Appium 测试环境。 有一次给团队搭测试环境装完一堆软件后 Appium 会话死活起不来报错信息换着花样刷屏最后折腾到半夜才发现是电脑里多个 adb 版本在打架。后来带过几个新人发现大家踩的坑高度相似Appium app 自动化测试环境搭建这件事最难的根本不是某个组件装不上而是整套东西之间互相不认。这篇就把我反复重装、帮人排错之后沉淀下来的完整搭法讲清楚——先理解链路再动手装完马上跑通一个真实用例最后把高频报错的排查思路一并梳理完。1. 先看整条链路Appium 环境不是装软件而是组网1.1 一次自动化请求是怎么从电脑走到手机里的很多教程一上来就让你装 JDK、装 Node、装 Android SDK装完就完事。但你不知道这些组件各管哪一段出问题时连该看哪个进程都不知道。一个完整的 Appium 请求链路是这样的测试脚本Client先把操作翻译成 JSON 协议命令发给本机运行的 Appium ServerAppium Server 只是一个中转站它收到命令后转发给对应的 DriverDriver 再通过 adb 把指令送进手机里的自动化组件真正在设备上做点击、滑动、输入等操作然后把结果原路返回。打个比方这跟点外卖很像你测试脚本下单给平台Appium Server平台把订单派给餐厅Driver餐厅做完菜由骑手adb送到家里手机。任何一个环节掉链子饭都到不了嘴边。所以环境搭建的实质是把这条链路完整打通。1.2 各组件职责和它们的脾气给新手列一张组件对应表排查时对着看就知道问题出在哪一环。组件职责容易出错的地方Appium Client 库Python/Java/JS把测试代码转成协议命令版本和 Server 不匹配Appium Server监听端口、转发命令Node 版本过低、端口被占用Driveruiautomator2 / xcuitest驱动 Android/iOS 自动化Appium 2.x 下忘记单独安装adb / 手机端组件底层通信通道多个 adb 版本冲突、设备未授权被测 App接收自动化指令appPackage/appActivity 写错实际排错时先定位是 Server 层面报错、Driver 层面报错还是设备连接层面报错问题就好解决一大半。2. 基础依赖的安装与验证JDK、Node、Android SDK2.1 版本别追新JDK 和 Node 的取舍很多人装环境喜欢装最新版但在 Appium 生态里追新反而容易踩坑。目前最稳的版本组合是JDK 8 或 11Node 18 LTS 或 20 LTS。JDK 17 虽然现代但有些第三方库和旧用例并不会因为新 JDK 就跑得更快反而可能遇到兼容性问题。我见过一个同事直接装 JDK 21Appium 装好了uiautomator2 driver 构建时频繁报错换回 JDK 11 一次通过。装完先验证三件事java -version node -v npm -v注意每次改完环境变量一定要新开一个终端窗口再验证。环境变量是进程级的老窗口里读到的还是旧配置。这个细节我提醒过无数次仍然有人反复栽在上面。2.2 Android SDK不一定装 Android Studio但推荐装严格来说跑 Appium 只需要 Android SDK 里的 platform-tools里面装着 adb和构建工具。但纯命令行方式对新手不友好最省事的方式还是装 Android Studio然后在 SDK Manager 里勾选 Android SDK Platform-Tools。装完后需要配置两个环境变量ANDROID_HOME 指向 SDK 根目录PATH 里加上 platform-tools 和 tools 目录。macOS/Linux 下可以在~/.bashrc或~/.zshrc里加export ANDROID_HOME$HOME/Library/Android/sdk export PATH$PATH:$ANDROID_HOME/platform-tools:$ANDROID_HOME/toolsWindows 则在系统环境变量里新建 ANDROID_HOME并把platform-tools路径追加到 PATH。配好后新开终端运行adb version能输出版本号就说明 SDK 部分通了。2.3 最容易被忽略的 adb 版本冲突这里有个隐藏很深的坑电脑里可能同时存在多个 adb。Android Studio 自带一个 adbplatform-tools 里有一个 adb某些手机助手、模拟器也会带一个 adb。多个 adb 版本并存经常会出现 adb server version doesnt match this client 或者设备突然断开。排查方法很简单分别跑which adbWindows 用where adb看当前用的是哪一份然后把其他第三方工具自带的 adb 移除或改名确保 PATH 里只有一个 adb。我的习惯是统一用 platform-tools 里的 adb版本最干净和 Appium 配套问题最少。3. Appium Server 与 Appium Inspector桌面版退役后的新选择3.1 别再被老教程误导Appium Desktop 已经停更如果你搜索 Appium 环境搭建会看到大量老教程推荐安装 Appium Desktop然后打开那个带界面的服务器。这里要提醒一句Appium Desktop 已经停止维护内置的 Appium Server 停留在老版本跟现在 Appium 2.x 的 Client 库配合经常出问题。现在的推荐组合是命令行启动 Appium Server 独立的 Appium Inspector 做调试。Appium Inspector 专门用来查看页面元素和验证定位表达式类似 Web 开发里的浏览器开发者工具。3.2 安装 Appium 2.x 和 Driver直接通过 npm 全局安装npm install -g appium appium -vAppium 2.x 发生了一个重要变化Driver 不再内置。以前装完 Appium 就能直接用 uiautomator2现在必须手动安装appium driver install uiautomator2跑 Android 就装 uiautomator2跑 iOS 就装 xcuitest。装完后用appium driver list查看当前已安装的 Driver。很多人环境搭完报 The uiautomator2 driver is not installed就是漏了这一条命令。如果 npm 下载慢可以把 registry 换成国内镜像命令不变速度会快很多。3.3 Inspector 的用法比反复跑脚本省事得多先启动 Appium Serverappium默认监听 4723 端口。然后打开 Appium Inspector填好 Capabilities 配置后面会详细讲点连接。成功后会看到手机屏幕的实时快照和元素树点击某个控件就能看到它的 resource-id、text、class 等属性。写测试脚本时直接把这些属性拿过去用不用每次改一行代码就跑一次全脚本调试效率能翻倍。4. 设备连接与 Capabilities环境搭好之后的第一道坎4.1 真机连接从开发者模式到授权弹窗设备连接是新手最头痛的部分。Android 真机要开启开发者模式设置 → 关于手机 → 连点版本号7 次直到提示已进入开发者模式。然后进开发者选项打开USB 调试。连上电脑后手机屏幕会弹出允许 USB 调试吗的对话框这里必须点允许并且勾选始终允许。很多环境下 Session 建立失败就是因为这个弹窗没被处理或者手机锁屏导致弹窗根本看不见。接着在终端跑adb devices看到类似XXXXXX device的输出才算真正连上。如果显示unauthorized说明授权没通过如果显示空列表先检查数据线是不是只能充电不能传数据——这种线我见过太多人拿来调试了。部分国产手机还需要额外开启USB 安装USB 调试安全设置等选项否则自动化过程中安装 Appium Settings 辅助应用时会报错。每个品牌的入口不同但基本都在开发者选项里。4.2 模拟器连接新手的练习首选如果手头没有真机用 Android Studio 自带的 AVD 模拟器完全够用。创建模拟器后启动adb devices里会自动出现emulator-5554这样的设备直接就能用。模拟器调试的好处是重启快、不怕点坏适合初学者先从它练起。唯一要注意的是别同时开多个设备和模拟器否则自动化命令会不知道发给谁。不得已多设备连接时可以在 Capabilities 里通过udid指定或者命令后面加-s 设备序列号。4.3 Capabilities 参数详解Capabilities 是告诉 Appium我要在什么设备上、用什么方式、打开什么应用的配置。下面是 Android 真机/模拟器最常用的一组{ platformName: Android, platformVersion: 13.0, deviceName: emulator-5554, appPackage: com.android.settings, appActivity: .Settings, automationName: UiAutomator2, noReset: true }核心参数含义platformName平台类型Android 或 iOS。platformVersion系统版本可以写具体的版本号也可以省略让 Appium 自动识别。deviceName设备标识模拟器一般是 emulator-5554真机填 adb devices 里显示的序列号。appPackage / appActivity被测应用的包名和启动 Activity。拿到这两个值最简单的方法是先用adb shell dumpsys window | grep mCurrentFocus查当前前台应用的类和包名。automationNameAndroid 固定用 UiAutomator2这也是为什么要单独装这个 driver。noReset不重置应用数据调试阶段强烈建议设成 true否则每次启动用例都会清数据重新走安装流程。autoGrantPermissions如果被测应用启动时需要一堆权限弹窗设成 true 可以自动授权。5. 跑通首个自动化用例与高频报错排查链路5.1 一个可直接运行的 Python 示例先安装 Python 客户端库pip install Appium-Python-Client然后写一个最简单的脚本启动系统设置应用并读取当前包名from appium import webdriver desired_caps { platformName: Android, platformVersion: 13.0, deviceName: emulator-5554, automationName: UiAutomator2, appPackage: com.android.settings, appActivity: .Settings, noReset: True } driver webdriver.Remote(http://127.0.0.1:4723, desired_caps) print(driver.current_package()) driver.quit()运行前提是 Appium Server 已经在另一个终端跑着。看到控制台输出com.android.settings就说明从 Client 到 Server 到 Driver 再到设备的整条链路全部通了。此时恭喜你Appium 环境搭建的核心目标已经达成接下来可以往里面填各种业务操作了。5.2 高频报错的定位思路把我在实际调试中遇到最多、新人也最容易卡住的报错整理成一张表按这个顺序排查大部分 Session 建立失败的问题都能解决。报错关键词常见原因排查顺序Could not find a connected Android deviceadb 没识别到设备先跑 adb devices再检查授权和线材adb server version doesnt match this client多个 adb 版本冲突which adb 定位所有 adb统一版本uiautomator2 driver is not installedAppium 2.x 未装 driverappium driver install uiautomator2Failed to create session原因最杂看完整日志最后几行多半是 Capabilities 配置问题Settings App could not be launched权限弹窗未授权重新插拔 USB勾选始终允许An unknown server-side error occurred常跟 Activity 相关核对 appPackage/appActivity 是否真实存在有个经验值得单独说报错信息一定要看最后 20 行而不是开头那几行。Appium 日志是链式输出真正的根因通常藏在末尾的某个堆栈里。很多人一看到开头一个红字 Error 就慌其实是自乱了阵脚。5.3 一次完整的排查案例有次帮一个同事在 Windows 上排查环境日志一直报 io.appium.settings 启动失败。她以为是 Appium 装坏了重装了三遍问题还在。我过去看了一眼发现手机屏幕一直锁着那台手机 USB 调试授权弹窗被晾在一边Appium 根本没权限安装辅助应用。解决方法很简单手机解锁重新插一下 USB把允许 USB 调试和始终允许都确认一遍。这类问题跟技术无关却最容易把新手卡死所以遇到环境问题先确认设备层面再往上层查。还有一次是 Node 版本太旧Appium Server 启动后端口一直在监听但一转发起 Session 就崩。用appium --version看版本没问题查日志才发现某个依赖包在高版本 Node 下编译不过。换用 Node 18 LTS 后一切恢复。这就是为什么前面强调版本组合工具链的兼容性远比图新重要。根据我个人的搭环境经验第一次搭最好在自己经常用的电脑上完整跑通一次哪怕多花点时间也别着急换机器。跑通一次之后你对整套链路会有一个整体感知后面再换机器、换系统、帮别人排错心里都有底。如果你后续打算做 iOS 自动化那就在这个基础上再装 xcuitest driver原理是相通的只是设备侧的要求不一样。本文还有配套的精品资源点击获取