Windows下Python+Appium环境搭建全攻略：从零到跑通第一个脚本

做移动端自动化测试绕不开 Appium。这几年我带过不少新同事Windows 系统上搭 pythonappium 环境看着就是一路“下一步”真轮到自己动手坑一个接一个JDK 版本对不上、adb 设备连不上、Appium Server 端口起不来、Python 客户端连超时随便一个就能耗掉一下午。这篇文章我直接把踩过的坑和验证过的方案完整写出来从零开始在 Windows 下把 JDK、Android SDK、Appium Server、Python 客户端、设备联调全部配通再跑通第一个冒烟脚本。适合刚入门 App 自动化测试的同学也适合要给团队统一搭建测试环境的人做参考。为了让这套环境不只是一个“能用”的状态我会把每个环节为什么这么选、每一步命令在干什么、遇到报错怎么排查都讲清楚。环境搭过几轮之后你会发现真正卡人的不是工具本身而是不知道整条工具链的依赖关系。这篇文章的目标就是先把这个关系理顺。1. 环境准备与整体选型思路1.1 核心组件清单与版本建议Windows 下做 App 自动化测试环境从来不是“装一个软件”那么简单。先别急着下载东西把整条链路搞清楚后面至少省一半时间。Appium 的角色像一个“翻译官”Python 脚本发出指令Appium Server 接收后翻译给手机上的自动化驱动驱动再操作 App。所以一套完整环境至少要包含下表里的这些组件组件推荐版本作用说明JDK8 或 11Appium Server 和部分 Android 工具的运行依赖Android SDKplatforms 33 / build-tools 33.x提供 adb、系统镜像、编译工具Node.js14 LTS 及以上新版 Appium Server 的运行环境Appium Server2.x自动化测试的核心服务端uiautomator2 驱动最新Appium 2.x 中负责 Android 平台通信的驱动Python3.8 及以上书写测试脚本的语言Appium-Python-Client3.xPython 连接 Appium Server 的客户端库Appium Inspector最新可视化查看页面层级、定位元素的辅助工具这张表里的每个组件都不是可有可无的装饰。JDK 是老牌依赖从 Appium 1.x 时代就一直存在到了 Appium 2.x 时代又多了 Node.js 这项运行环境要求Android SDK 负责把 PC 和手机、模拟器连起来Python 和客户端库则是日常写脚本的主力。哪个环节断了后面的工作都没法展开。1.2 版本搭配的选型逻辑我看到不少人直接把 JDK 下到最新版比如 19 或者 21然后折腾一下午各种工具要么不识别要么报奇怪的错。说实话在移动端自动化这个场景里新版 JDK 带来的特性几乎用不上反而容易因为兼容性问题浪费大量时间。所以我的建议是 JDK 直接装 8 或 11这是经过大量实践验证的稳妥组合。网上有些项目脚本的源码甚至还是基于老 JDK 语法写的太新的版本反而会在编译期报错。Appium 侧的变化更值得注意。很多人还停留在 Appium 1.x 的阶段找的教程都是去官网下载那个带图形界面的 Appium Desktop。从 2.0 开始官方已经不再维护桌面客户端服务端和调试工具分开独立发展。现在推荐直接用 npm 安装 Appium CLI再通过命令安装 Android 平台驱动环境更轻量升级也方便不会遇到“图形界面打不开”“服务起不来”之类的老问题。下面各章节我统一按 Appium 2.x Python 3.8 的组合来讲这也是目前社区里讨论最多、维护最活跃的一条路。注意版本选择原则是稳定和兼容优先不是越新越好。搭环境的目的是尽快把脚本跑起来而不是在这上面追新这个方向别搞反。2. 基础环境JDK 与 Android SDK2.1 JDK 安装与环境变量配置第一步先装 JDK。下载安装包时选择 Windows x64 版本安装路径建议不要带空格和中文比如直接装到C:\Java\jdk8后面配置环境变量会省心很多。如果电脑上装了多个 JDK记得把 JAVA_HOME 指向你要用的那个不要依赖系统默认的 Java 目录。安装完之后需要配置环境变量。打开“此电脑 → 属性 → 高级系统设置 → 环境变量”在系统变量里新建变量名JAVA_HOME 变量值C:\Java\jdk8然后在 Path 中添加一行%JAVA_HOME%\bin配置完成后新开一个命令行窗口输入java -version和javac -version能看到版本信息就说明 JDK 装好了。这里有个细节环境变量修改后所有已打开的命令行窗口都不会立刻生效必须新开窗口重新读取环境变量。很多新手卡在“明明配了还是显示找不到 java”十有八九就是没新开窗口。2.2 Android SDK 的安装commandlinetools 方式以前装 Android SDK 会去下载 Android Studio装一堆用不上的东西然后还要在图形界面里点半天。其实做自动化测试只需要 SDK 的命令行工具。去 Android 开发者官网下载 commandlinetools 压缩包解压到一个固定目录比如C:\android-sdk。这里有一个容易踩坑的结构问题刚解压出来里面是cmdline-tools目录直接能看到 bin、lib 这些子目录。官方约定的目录结构要求你必须把它整理成cmdline-tools\latest\bin\sdkmanager.bat这样的形式。实际操作时建议这样处理在C:\android-sdk下创建cmdline-tools\latest把解压出来的内容全部移进去。不这样做的话后续执行 sdkmanager 会找不到自己的定位信息直接抛错。整理好之后在命令行进入C:\android-sdk\cmdline-tools\latest\bin执行以下命令安装基础组件sdkmanager platform-tools platforms;android-33 build-tools;33.0.0sdkmanager是官方提供的包管理工具可以把它理解为 SDK 的“应用商店”。这里安装的platform-tools会提供 adb 命令platforms;android-33对应 Android 13 的平台库build-tools则包含打包、签名等一系列工具。如果你的测试设备是 Android 12 或更低版本装platforms;android-31甚至更低也够用但多装一个较高版本平台库问题不大设备侧的兼容性由 Appium 统一处理。建议顺手执行一句sdkmanager --licenses把所有许可协议都接受掉。这一步不做后面某些工具可能会因为协议未接受而拒绝初始化报错信息还不直观。2.3 环境变量配置细节与验证Android SDK 装完之后同样要在系统变量中注册变量名ANDROID_HOME 变量值C:\android-sdk然后把以下两个路径追加到 Path%ANDROID_HOME%\platform-tools %ANDROID_HOME%\cmdline-tools\latest\binANDROID_HOME是很多工具查找 SDK 位置的依据ANDROID_SDK_ROOT是另一个常见变量名建议同步设置成同一个值。某些老工具只认ANDROID_SDK_ROOTAppium 的驱动安装和部分脚本执行时也会读取这些变量提前配上省得后面排查半天。验证方法很直观新开一个命令行窗口输入adb version看到类似Android Debug Bridge version 1.0.41的输出说明 platform-tools 已生效。如果提示“adb 不是内部或外部命令”优先检查 Path 里是否加了%ANDROID_HOME%\platform-tools其次检查命令行窗口是否新开。到这里Android 基础链路已经通了接下来进入 Python 和 Appium 部分。3. Python 与 Appium 服务端3.1 Python 安装与虚拟环境Python 安装本身没什么难度但有两个点必须留意。第一安装时勾选“Add Python to PATH”不勾选的话后续执行 python 命令会提示找不到第二安装路径同样建议短一些、不带中文例如C:\Python312。安装完成后验证一下python --version pip --version两条命令都能正常输出版本信息说明基础 Python 环境没问题。接下来我强烈建议创建一个虚拟环境把 Appium 相关依赖都装在里面不要直接装到系统全局。原因很实际电脑上可能还有别的项目每个项目对第三方库的版本要求不一样全局安装很容易出现今天升级一个库、明天另一个项目跑不起来的情况。虚拟环境相当于给当前项目划了一个独立的“房间”。创建和激活命令如下python -m venv appium_env appium_env\Scripts\activate激活后命令行前方会出现(appium_env)前缀表示当前已进入虚拟环境。之后所有 pip 安装操作都在这环境下执行不会污染全局。3.2 Appium Server从桌面版到 CLIAppium Server 的安装是重头戏版本关系最复杂。如果你还在按旧教程下载 Appium Desktop 的安装包可以停下来了。从 Appium 2.0 起官方把 GUI 客户端从服务端中剥离不再推荐使用桌面版。现在推荐用 npm 全局安装 Appium CLI。先确认 Node.js 已安装且版本不低于 14node -v npm -v然后执行npm install -g appium安装完成后再看版本appium --version如果能看到类似2.5.x的输出说明服务端装好了。Appium 2.x 和老版本最大的区别在驱动机制1.x 时代驱动集成在主包里而 2.x 把驱动做成了插件式Android 平台需要单独安装名为 uiautomator2 的驱动appium driver install uiautomator2这个驱动负责和手机上的自动化组件通信。没有它启动 session 时会看到类似Could not find a driver for platformName Android的报错。装完可以用appium driver list确认状态会看到uiautomator2 - [installed]这样的标记。最后启动服务appium默认监听在127.0.0.1:4723看到日志输出listening之类的信息就说明服务正常。这个命令行窗口不要关服务需要一直保持运行。3.3 Python 客户端库安装服务端就绪后回到之前创建的虚拟环境安装 Python 侧的客户端库pip install Appium-Python-Client注意正确名称是Appium-Python-Client不是appium。有些同学在包索引里搜到别的同名包装上后导入时报错白白浪费不少时间。安装完成后在 Python 环境里验证python -c from appium import webdriver; print(ok)能打印 ok说明客户端库可用。到这里pythonappium 环境的核心部分已经全部配好。接下来的问题是怎么让它和手机建立连接、跑起第一个脚本这才是很多教程没讲清楚的地方。4. 设备连接与第一个脚本4.1 真机与模拟器的连接测试设备我建议先用模拟器方便重置跑自动化也不消耗真机。Android Studio 自带的 AVD Manager 可以创建模拟器下载一个系统镜像比如 Android 12 的 x86_64 镜像创建虚拟设备后启动。如果不想装完整的 Android Studio也可以单独配置模拟器但需要手动处理系统镜像和创建命令对新手不够友好。模拟器启动后在命令行执行adb devices正常会看到一个emulator-5554 device的设备。如果输出是unauthorized说明设备未授权需要在模拟器或手机上确认调试授权弹窗。如果是真机还需要在设置里打开“开发者选项”然后开启“USB 调试”插上数据线后在手机弹窗里点允许。真机的 deviceName 通常是类似RF8N...的序列号以 adb devices 显示为准。这里有个值得注意的点如果电脑上装了多个模拟器工具adb 的版本可能互相干扰导致只识别其中一个、另一个显示 offline。解决办法是统一使用 SDK 目录下的 adb并检查系统环境变量里的路径顺序确保%ANDROID_HOME%\platform-tools排在更靠前的位置。4.2 用 Appium Inspector 快速定位元素写测试脚本前先打开 Appium Inspector。这个工具能直观展示手机界面上的元素层级和属性定位元素时非常方便。启动后在界面里配置连接信息Remote Host: 127.0.0.1Remote Port: 4723Path: /wd/hub然后在 JSON Representation 里填上启动会话的能力参数一个最小可用的配置如下{ platformName: Android, automationName: UiAutomator2, deviceName: emulator-5554, appPackage: com.android.settings, appActivity: .Settings, noReset: true }这里的appPackage和appActivity表示要启动的 App。以 Android 系统设置为例包名是com.android.settings入口 Activity 是.Settings。点击 Start Session如果配置没问题Inspector 会展示出设置页面的 UI 树鼠标点选元素就能在右侧看到它的 id、text、resource-id 等属性这些就是写脚本时要用的定位依据。4.3 跑通第一个冒烟脚本有了元素信息写第一个脚本就顺理成章了。回到虚拟环境新建一个smoke_test.py内容如下from appium import webdriver from appium.options.android import UiAutomator2Options from selenium.webdriver.common.by import By desired_caps { platformName: Android, automationName: UiAutomator2, deviceName: emulator-5554, appPackage: com.android.settings, appActivity: .Settings, noReset: True } options UiAutomator2Options().load_capabilities(desired_caps) driver webdriver.Remote(http://127.0.0.1:4723/wd/hub, optionsoptions) driver.implicitly_wait(10) # 查找并点击关于手机入口 target driver.find_element(By.XPATH, //*[text关于手机]) target.click() # 验证跳转后的页面中出现关于手机标题 page_title driver.find_element(By.XPATH, //*[text关于手机]) assert page_title is not None driver.quit()脚本的逻辑很简单启动设置 App等待页面加载用 XPath 找到“关于手机”并点击最后通过断言确认跳转成功。implicitly_wait(10)给元素查找设置了最多 10 秒的隐式等待避免设备或网络慢时频繁报错。执行命令python smoke_test.py如果看到页面正常拉起、控制台没有异常退出说明 pythonappium 环境真正打通了。之后要做的就是在框架里添加更多测试步骤、断言逻辑和异常处理。5. 常见问题排查与避坑实录5.1 高频报错速查实战中会遇到一批非常典型的报错我把它们整理成速查表遇到时可以直接对号入座报错信息常见原因解决办法Could not find a driver for platformName AndroidAppium 2.x 未安装 uiautomator2 驱动执行appium driver install uiautomator2adb: command not foundplatform-tools 未安装或未加入 PATH检查C:\android-sdk\platform-tools是否存在确认环境变量Connection refusedAppium Server 未启动或端口被占用确认 4723 端口监听正常必要时换端口appium -p 4724Unauthorized设备未允许 USB 调试授权在设备上重新授权或执行adb kill-server后重连SessionNotCreatedExceptioncapabilities 中 deviceName 与 adb 显示不一致将 deviceName 改成adb devices输出的实际值Error: Could not find adb in SDKANDROID_HOME 指向错误或 SDK 目录不完整重新配置 ANDROID_HOME再执行 sdkmanager 安装 platform-tools脚本执行时中文乱码Windows 命令行默认编码不是 UTF-8执行chcp 65001切换代码页脚本文件统一用 UTF-8 保存比如connection refused很多时候不是服务没起而是同时装了多个 Node 版本Appium CLI 装在了其中一个 Node 的全局目录下新开的命令行窗口加载的是另一个。这类问题的排查思路很关键先从环境变量入手确认命令行实际执行的命令来自哪个路径再顺藤摸瓜。5.2 环境搭建的几条避坑经验最后分享几条实操中沉淀下来的经验这些在官方文档里往往不会写明。第一Appium 服务端和测试脚本要有一个明确的启动顺序先启动模拟器或连接真机再启动 Appium Server最后执行脚本。反过来容易遇到连接超时而且排查起来费劲。如果你经常跑自动化可以把这几条命令串成一个启动脚本一键做完设备检测、服务启动和自测。第二不要忽视端口冲突。4723 是 Appium 默认端口5037 是 adb 端口。某些软件可能占用这些端口。一条很管用的排查命令是netstat -ano | findstr 4723能看到占用进程的 PID然后去任务管理器里按 PID 找到对应进程决定是否结束它。第三虚拟环境这个习惯一定要养成。我之前在团队里观察过有人在全局环境里装了新版 Appium-Python-Client结果另一个项目用的老版测试框架导入同名模块时报了一堆错。后来统一改用虚拟环境管理依赖这类问题就再也没出现过。第四团队协作时建议把环境版本写成固定配置文件。我的做法是创建一个requirements.txt里面锁定 Appium-Python-Client 的版本号Node 侧的 Appium 版本和驱动版本也在文档里登记。这样无论是换电脑还是新同事入职照着版本号安装半小时内就能恢复一套一致的环境不会出现“我这边能跑你那边不行”的情况。第五定位元素时优先用 resource-id 或 textXPath 能用但别滥用。整个环境搭好后后续真正的工作就落在元素定位和脚本维护上。Inspector 看层级时优先选稳定的属性作为定位锚点页面改版时脚本也能少改几行。我个人在实际操作中最深的体会有两点。一是这套环境本质上就是一条工具链每一环都有明确职责理解了链路关系报错时脑子里自然就有排查方向。二是别怕重装环境搭坏了大不了删掉重来Windows 下路径问题很多时候重装一次比反复排查更快。希望这篇文章能帮你顺利跑通第一个 Appium 脚本后面做数据驱动、关键字驱动框架时也就有个踏实的底子。