引言

最近要写个安卓自动化项目，想用 Appium 来实现，版本已经来到了 2.19.0，搜了一圈，发现文档比较少，至少 7 年没有用过了，有点陌生，打算重新研究下，写成文章分享给有需要的人。作为最流行的移动端自动化测试框架之一，其 2.x 版本有许多重要的改进和新特性。这篇文章将详细介绍如何在 Windows 和 macOS 系统上安装 Appium 2.19.0 版本，并配置 Python 环境进行自动化测试开发。

第一部分：环境准备

1.1 系统

1.操作系统：Windows 10/11 或 macOS 10.15+
2.Python 版本：推荐 3.8+（我使用的是 3.12）

1.2 必要组件清单

在开始前，请确保已安装以下组件：

1.Node.js 16.x 或更高版本（我使用的是 v22.13.1）

2.Java JDK 11+（Android 测试需要）（我使用的是 17）

3.Android SDK（Android 测试需要）（最新就好）

4.Xcode 13+（iOS 测试需要，仅 macOS）（我使用的是 16.4）

5.Python 3.8+（我使用的是 3.12）

第二部分：基础环境安装

2.1 安装 Node.js

Appium 2.x 需要 Node.js 16+ 版本：

1.访问 Node.js 官网下载 16.x 或更高版本的 LTS 版本

2.安装时勾选"Automatically install the necessary tools"选项

3.验证安装：

node -v
# 应显示v16.x.x或更高
npm -v
# 应显示8.x.x或更高

2.2 安装 Python 环境
推荐使用 Python 3.8+：

1.从 Python 官网下载安装包

2.安装时勾选"Add Python to PATH"选项

3.验证安装：

python --version
# 应显示Python 3.8.x或更高
pip --version
# 应显示pip 21.x.x或更高

2.3 安装 Java JDK

Appium Android 驱动需要 Java 环境：

1.下载 JDK 11+

2.安装后设置环境变量：

# Windows
setx JAVA_HOME "C:\Program Files\Java\jdk-17"
setx PATH "%PATH%;%JAVA_HOME%\bin"

# macOS
export JAVA_HOME=$(/usr/libexec/java_home)
export PATH=$JAVA_HOME/bin:$PATH

3.验证安装：

java -version
# 应显示11.x.x

第三部分：安装 Appium 2.19.0

3.1 通过 npm 安装 Appium

Appium 2.x 采用了新的架构设计，核心与驱动分离：

npm i -g appium

安装完成后验证：

appium -v
# 应显示2.19.0

这里如果 windows 提示 appium 不是内部命令,需要把 npm 的路径添加进环境变量 path

# Windows
setx PATH "%AppData%\Roaming\npm"

# macOS
#输入以下命令来查找npm的全局路径
npm bin -g
#将输出的路径添加到你的shell配置文件中
export PATH="/usr/local/share/npm/bin:$PATH"

3.2 安装 Appium 驱动
Appium 2.x 需要单独安装所需驱动：

# 安装Android驱动
appium driver install uiautomator2

# 安装XCUITest驱动(iOS)
appium driver install xcuitest

查看已安装驱动：

appium driver list

3.3 安装 Appium 客户端库
Python 客户端库安装：

pip install Appium-Python-Client

第四部分：配置移动开发环境
4.1 Android 环境配置
1.下载并安装 Android Studio

2.通过 SDK Manager 安装：

* Android SDK Platform-Tools

* Android SDK Build-Tools

* 对应 API 级别的系统镜像

3.配置环境变量：

# Windows
setx ANDROID_HOME "C:\Users\YourUser\AppData\Local\Android\Sdk"
setx PATH "%PATH%;%ANDROID_HOME%\platform-tools;%ANDROID_HOME%\tools"

# macOS/Linux
export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/platform-tools:$ANDROID_HOME/tools

验证 ADB：

adb devices

4.2 iOS 环境配置（仅 macOS）
从 App Store 安装 Xcode 13+

安装 Xcode 命令行工具：

xcode-select --install

安装 Carthage（可选）：

brew install carthage

配置开发者账号和签名证书

第五部分：验证安装

5.1 启动 Appium 服务器

appium
# 或使用更多选项
appium --log-level debug --allow-insecure chromedriver_autodownload

5.2 编写 Python 测试脚本
创建 test.py 文件：

from appium import webdriver
from appium.options.android import UiAutomator2Options
import time

# 配置Android设备参数
capabilities = dict(
    platformName='Android',
    automationName='uiautomator2',
    deviceName='Android',
    appPackage='com.android.settings',
    appActivity='.Settings'
)

# 转换capabilities为Appium Options
options = UiAutomator2Options().load_capabilities(capabilities)

# 连接Appium服务器
driver = webdriver.Remote('http://localhost:4723', options=options)

# 简单操作示例
try:
    time.sleep(5)
    print("当前Activity:", driver.current_activity)
finally:
    driver.quit()

5.3 运行测试
确保：
1.已连接 Android 设备或启动模拟器
2.Appium 服务器正在运行

执行测试：

python test.py

第六部分：常见问题解决

6.1 安装问题
问题：npm 安装 Appium 时权限错误
解决：

# Windows以管理员身份运行CMD
# macOS使用sudo
sudo npm install -g appium

问题：Python 客户端库版本冲突
解决：

#先卸载
pip uninstall Appium-Python-Client
#重新安装
pip install Appium-Python-Client

6.2 连接问题
问题：无法检测到 Android 设备
解决：

#杀死adb服务
adb kill-server
#再启动
adb start-server
#验证
adb devices

问题：iOS 真机连接失败
解决：

确保 Xcode 中信任开发者证书

在设备上信任电脑

第七部分：进阶配置

7.1 使用 Appium Doctor 检查环境

npm install -g @user1/doctor
appium-doctor --android
appium-doctor --ios

7.2 配置 Appium 日志
创建 appium-server.log 配置文件：

{
  "server": {
    "port": 4723,
    "log": "./appium.log",
    "log-level": "debug"
  }
}

启动时指定配置：

appium --config appium-server.log

7.3 使用 Appium 元素定位器（可选）
1. 使用命令安装

pm install -g appium-inspector

2. 直接从 Github 下载 Appium Inspector 桌面应用

结语
通过以上步骤，你应该已经成功安装了 Appium 2.19.0 并配置好了 Python 测试环境，下面就可以愉快的玩耍了