Windows下Python+Appium移动端UI自动化测试环境搭建全攻略

做移动端UI自动化测试，windows下搭建python+appium环境是新手们走得最多、也最容易绕弯路的一条路。很多人一开始觉得装个软件而已，结果卡在环境变量三天起不来；也有人花了一晚上装完各种组件，跑demo的时候却连不上设备。我自己刚入行那会儿也经历过“一晚上装环境，两小时删掉重来”的折腾，所以特意把整套路整理成一篇能直接照着操作的文章，从版本选型、安装顺序到各种坑，一篇讲透。这篇文章适用于准备入门移动自动化测试、或正在做App测试项目但还没搞定基础的同学们，照着做，基本能让你在半小时左右把最核心的链路跑通。

1. 环境搭建前的整体思路与版本选型

1.1 先理清组件之间的依赖关系

Python + Appium这套技术栈，表面上只有两个名字，实际牵扯到的东西不少。我习惯把它拆成四层来看：

• 脚本层：Python + Appium-Python-Client，负责写测试逻辑、发送自动化指令
• 服务层：Appium Server，一个基于 Node.js 的 HTTP 服务，负责接收客户端的请求，再把指令翻译成安卓能听懂的操作
• 工具层：Android SDK，尤其是 platform-tools 里的 adb，负责跟手机或模拟器通信，安装应用、模拟点击、读取界面信息都靠它
• 基础层：JDK。很多人不理解为什么跑 Appium 还要装 Java，因为 Android 系统层面的工具链、以及部分辅助调试工具都依赖 Java 运行时，所以这一步省不掉

理清这四条，后面所有安装都会变得有方向：每一层装完都能单独验证，就不会出现装了一堆东西、最后不知道哪里坏的尴尬局面。

1.2 版本选型的建议

选版本这件事，我踩过的坑比装环境本身还多。这里直接给结论：

• Appium 服务端：建议用 2.x 最新稳定版。1.x 虽然资料多，但已经进入维护末期，新驱动安装方式也不一样了。2.x 把驱动和服务器分离，安装更干净
• 客户端库：Appium-Python-Client 2.x 对应 Appium 2.x，安装时直接用 pip 拉最新即可
• Python：3.8 以上都行，建议 3.10 或 3.11，Python 3.12 也支持但个别依赖库偶尔会有兼容问题
• JDK：建议 JDK 8 或者 JDK 11。不建议一上来就装 JDK 17，部分安卓工具链对高版本支持没那么稳
• Android SDK：用官方提供的命令行工具安装最新 platform-tools 就行，不强制装 Android Studio（装了也可以）

版本这块我的原则是：别追新，追新容易把自己坑进去。测试环境讲究的是稳定复现，不是前沿尝鲜。

2. 前置软件安装与逐项验证

2.1 JDK 安装与 JAVA_HOME 配置

先装 JDK。去甲骨文官网下载对应操作系统的安装包，安装时建议把路径简化，避免中文或空格，比如D:\Java\jdk1.8.0_202。装完之后没有 JAVA_HOME 环境变量，Appium 经常会报找不到 Java 的错误，所以这一项务必配置好。

设置环境变量，在“此电脑 → 属性 → 高级系统设置 → 环境变量”里操作：

• 新建系统变量JAVA_HOME，值填 JDK 安装根目录，比如D:\Java\jdk1.8.0_202
• 编辑Path，新增一行%JAVA_HOME%\bin

验证方式：打开新的命令提示符窗口，输入java -version，能看到版本信息就算成功。这里有个很常见的坑：配置完环境变量后，旧窗口不会刷新，必须新开一个 cmd 或终端，否则还是报“不是内部或外部命令”。

2.2 Android SDK 与 platform-tools 配置

Android SDK 就是安卓调试工具的集合，核心是 adb。我用的方式是只装命令行工具，不装完整 IDE，这样快很多。

下载官方 commandline-tools 压缩包，解压到一个比如D:\Android\cmdline-tools的目录。然后用命令行创建 SDK 目录并安装 platform-tools：

mkdir D:\Android\sdk cd D:\Android\cmdline-tools\bin sdkmanager "platform-tools" "platforms;android-33"

装完配置环境变量：

• 新建ANDROID_HOME，值填D:\Android\sdk
• Path里追加%ANDROID_HOME%\platform-tools

验证方式：新开窗口执行adb version，显示 adb 版本号就说明配置好了。

补充一个细节：模拟器和真机的驱动依赖并不相同。如果后面跑的是真机，还需要各手机厂商自己的 USB 驱动，多数情况下装上调试软件自动就有，但遇到“设备列表空空如也”时，优先考虑驱动问题。

2.3 Python 环境与 pip 源配置

Python 安装包去官网下载，安装时务必勾选“Add Python to PATH”。这一步漏了，之后命令行打python直接报错，都是在这儿栽的。装完后同样用新终端验证：

python --version pip --version

这里我给一个强烈建议：项目依赖不要全局装，用虚拟环境隔离。新建一个工作目录appium_work，然后在里面创建并激活环境：

mkdir appium_work cd appium_work python -m venv venv venv\Scripts\activate

以后所有 pip 安装操作都在这个虚拟环境里做，避免不同项目的依赖互相干扰。这个习惯我后来一直保留，直到现在做自动化项目也这么做。

如果发现 pip 下载速度很慢，可以在用户目录下新建pip.ini文件，内容填入镜像源。这一步不是必须的，但能让你省下大量等待时间，建议直接做。

3. Appium 服务端与客户端库安装

3.1 Appium Server 安装与驱动管理

Appium Server 本质上是一个 Node.js 程序，所以要先有 Node.js 环境。去官网下载 LTS 版本安装，然后在终端里验证：

node -v npm -v

接着全局安装 Appium：

npm install -g appium appium --version

Appium 2.x 安装完之后，还需要单独安装安卓驱动。这里的“驱动”类似打印机驱动，是 Appium 跟底层自动化引擎之间的翻译层：

appium driver install uiautomator2

查看驱动列表确认装好了：

appium driver list --installed

到这里 Appium 服务端就算装好了。启动服务用appium命令，默认监听 4723 端口，日志里看到 “Appium ready” 就说明服务正常。许多教程会在这一步直接让跑桌面版 Appium，但那个默认绑定 1.x，新项目直接用命令行方式更干净。

我自己的经验是：前期调试阶段，终端跑appium最有价值，因为能实时看到错误日志，一旦脚本连不上设备，这些日志就是第一手的排错线索。

3.2 客户端库安装与引入验证

激活虚拟环境后，安装 Python 的客户端库：

pip install Appium-Python-Client

装完打开 Python 交互环境，执行：

from appium import webdriver print(webdriver.__name__)

能正常输出就说明库可用。这里有人会混用 selenium 的 webdriver，写法类似，但 appium 的客户端是基于 mobile JSON wire protocol 扩展的，别混。

版本对应关系我也顺手总结一下：

如果装完之后运行脚本报错提示版本不兼容，优先检查这两个版本是否匹配。

4. 连接模拟器/真机与第一个自动化脚本

4.1 模拟器/真机的连接准备

模拟器方面，随便选一款市面上主流的安卓模拟器就行，最省事的其实是 Android 官方提供的 AVD，因为随 SDK 管理，不会有驱动兼容问题。第三方模拟器一般也会自带 adb 调试开关，通常在设置里能找到“ADB 调试”或“开发者选项”，开启之后就能被识别。

启动模拟器之后，用 adb 验证设备连接：

adb devices

看到device状态就代表正常，offline则是驱动或端口问题。模拟器有时还需要手动连接 adb 端口，格式取决于模拟器的监听端口配置，常见的写法是：

adb connect 127.0.0.1:62001

不同模拟器的端口不一样，自己查一下自己用的那款的默认端口就行。这个操作不是必须的，但当你输入adb devices发现没有设备时，这是一招有效的补救方法。

真机的连接准备则是另外一套逻辑：

• 进入开发者选项，打开“USB 调试”
• 用数据线连电脑，手机上弹出授权确认框时点“允许”
• 多次插拔后如果还是识别不到，检查 USB 模式是否为传输文件

4.2 编写并跑通第一个 Appium 脚本

准备工作全部完成后，写一个最小可跑的脚本做冒烟验证。下面这个例子是启动安卓系统设置应用并获取页面标题：

from appium import webdriver desired_caps = { "platformName": "Android", "deviceName": "emulator-5554", "appPackage": "com.android.settings", "appActivity": ".Settings" } driver = webdriver.Remote("http://127.0.0.1:4723", desired_caps) # 等待界面加载 driver.implicitly_wait(10) # 获取当前界面标题 title = driver.find_element(By.ID, "android:id/action_bar") print("页面标题:", title.text) driver.quit()

这段代码里面有几个关键点要解释：

• platformName固定写 “Android”，连接 iOS 设备时才写 “iOS”
• deviceName要和adb devices输出的设备序列号一致，模拟器一般形如emulator-5554
• appPackage和appActivity是安卓应用的两个核心标识。设置应用的包名是com.android.settings，启动 Activity 是.Settings，这是官方固定的，不需要额外查询
• 如果不知道某个应用的包名和 Activity，可以先用 adb 打开目标应用，再执行：

adb shell dumpsys window | findstr mCurrentFocus

输出里会包含当前前台应用的包名和页面名，直接抄进配置就行。

跑通这个脚本，等于把整条链路验证了一遍。后续在此基础上加点击、输入、断言这些操作，就都是水到渠成的事了。

5. 常见问题与排查技巧实录

5.1 环境变量相关的坑

环境变量是 Windows 下搭建这套环境最容易出错的重灾区。单独拎出来写，是因为我见过太多人在这上面反复卡壳。

• 配置完环境变量后命令行还报找不到命令：新开终端窗口，旧窗口的环境变量不会自动刷新。实在不行就注销或重启一次，别用 cmd 里的 set 命令去改
• 配置了 JAVA_HOME 但 Appium 启动仍然报 Java 错误：检查 JAVA_HOME 是否指向 JDK 根目录，而不是包含bin的目录。指向D:\Java\jdk1.8.0_202\bin，会导致后续路径拼接出错
• Path 变量被覆盖：编辑系统 Path 时注意追加而不是替换，不要漏掉原有的%SystemRoot%之类的条目

5.2 Session 创建失败的常见原因

运行脚本时如果卡在Remote创建这一步，报错形如Could not create a new session，大概率是以下问题：

最后这个adb 被占用是隐蔽问题。有时候安卓模拟器自带的 adb 版本和官方 SDK 里的版本不一致，会导致服务端互相抢占端口。遇到了就执行：

adb kill-server adb start-server

保持两边 adb 版本一致最好。用大版本一致的 platform-tools 基本不会再踩这个坑。

5.3 元素定位与调试阶段的小技巧

环境跑通之后的调试阶段，也有几个经验直接分享：

• 用 Appium Inspector 连上同一个 session 查看页面元素，不用反复跑脚本查层级，事半功倍
• 定位元素优先用 resource-id，其次是 content-desc，最后才是 xpath。id 的稳定性和效率都远高于 xpath
• 脚本跑崩后 appium 日志会留很长，搜索error或Original error关键字能快速定位关键信息

这些技巧看起来都很小，但实际调试时能省下大量时间。

6. 实操心得：这套环境后续能做什么

最后聊点个人感觉。环境搭好的那一刻只是起点，真正有价值的是这套技术栈在工作里的延伸。它可以用来跑回归测试，把重复点击、填写表单、跨页面跳转这类高频操作变成自动化用例；也可以用来做性能摸底，通过脚本连续启动和切换页面，观察应用响应耗时；还能跟 CI 结合，每次提测自动跑一遍冒烟测试，把低级功能缺陷挡在发布之前。

我在实际项目中踩过几次坑之后，发现一个规律：环境搭建的顺利与否，和后面调试效率高度正相关。前期老老实实按版本对应关系装，每步验证，后面就省心；反之一次性全装完不看中间结果，出了问题往往要返工。如果中间某个步骤确实装卡住了，别硬着头皮往下走，停下来执行一遍对应命令重新验证，大概率能定位到具体环节。

这套环境本身其实没什么玄学，无非是每层依赖都装对、验证过、版本匹配。希望这篇分享能帮你绕开我当年走过的弯路，把时间留到真正有意思的自动化用例设计上。