1. 项目概述为什么要在Mac上搭建Appium环境如果你是一名软件测试或测试开发工程师正在或即将涉足移动端自动化测试那么“Appium环境搭建”绝对是你绕不开的第一道坎。尤其是在Mac平台上这个任务既带来了便利也伴随着一些特有的“坑”。为什么这么说因为Mac是iOS应用自动化测试的“官方指定”平台你想在真机或模拟器上跑iOS的自动化脚本离开Mac几乎寸步难行。同时Mac也能完美支持Android应用的自动化测试实现“一机双测”。所以在Mac上搭建一套稳定、高效的Appium环境就等于为你打通了iOS和Android两大移动平台的自动化测试通道是构建移动端CI/CD流水线、提升测试效率的基石。我见过太多新手包括几年前的我自己在这个环节耗费数天甚至一周时间被各种版本冲突、路径问题、权限错误搞得焦头烂额。网上的教程要么过于陈旧要么步骤跳跃缺了关键细节。今天我就以一名踩过无数坑的测试老兵身份带你从头到尾、手把手地搭建一套Mac下的Appium环境。我会把每一步的原理、可能遇到的问题以及我私藏的避坑技巧都讲清楚目标就是让你一次成功把时间花在更有价值的脚本编写和测试设计上。2. 环境搭建核心思路与工具选型在动手之前我们必须理清思路。Appium是一个客户端-服务器架构的测试框架它本身不“驱动”设备而是作为一个中间层接收来自你编写的测试脚本客户端的指令然后通过对应的设备驱动如XCUITest for iOS, UiAutomator2 for Android去控制真机或模拟器。因此搭建环境本质上是配置好这个通信链条上的所有节点。2.1 核心组件与依赖关系拆解一个完整的Mac Appium环境通常包含以下核心组件它们之间存在清晰的依赖关系编程语言与运行时环境这是你编写测试脚本的基础。Python和Java是主流选择考虑到生态和易用性本文将以Python为例。因此我们需要Python 3.x建议使用3.8或以上稳定版本。pipPython的包管理工具通常随Python安装。Appium Server这是核心服务端。有两种主要安装方式Appium Desktop图形化客户端内置了Server适合新手快速上手和Inspector元素定位。Appium via npm通过Node.js的包管理器npm安装更轻量更适合集成到CI/CD和命令行操作。我们选择这种方式因为它更“极客”也更符合自动化部署的需求。设备驱动与SDK对于AndroidJava Development Kit (JDK)Appium的Android驱动UiAutomator2等需要JDK。Android SDK包含adbAndroid调试桥、构建工具等。现在通常通过安装Android Studio来便捷地获取和管理SDK。对于iOSXcode苹果官方的开发工具是iOS模拟器和真机测试的绝对前提。它自带了所需的命令行工具和模拟器。Carthage或libimobiledevice用于真机测试时的依赖管理或设备通信Appium 2.0后部分依赖已简化。Appium Client Libraries即你脚本中用来连接Appium Server的库如Python的Appium-Python-Client。我们的搭建顺序将遵循依赖关系先装基础运行时Node.js, Python, JDK再装平台SDKAndroid Studio/Xcode最后安装Appium Server和Client库。2.2 为什么选择这些工具和版本选择npm安装Appium而非DesktopDesktop版虽然直观但其内置的Server版本可能更新不及时且不利于脚本化部署。通过npm安装我们可以精确控制版本方便使用appium driver命令管理驱动也更容易与持续集成工具配合。Android环境通过Android Studio管理单独下载SDK并配置环境变量是过去的“硬核”做法现在通过Android Studio安装它能自动处理SDK路径、更新和许可协议大大降低了配置复杂度。Python 3.8Python 2已停止支持Appium及相关生态库都已全面转向Python 3。选择3.8或以上可以确保兼容绝大多数现代库。注意环境搭建中最大的敌人就是“版本冲突”。请务必记录下你安装的各个组件的版本号这在后续排查问题时至关重要。3. 分步实操基础运行时环境配置万丈高楼平地起我们先来搞定最底层的基础依赖。请打开你的Mac终端Terminal我们全程将在命令行下操作。3.1 安装Homebrew如果尚未安装Homebrew是Mac上强大的包管理器能让我们后续的安装命令变得无比简洁。在终端输入以下命令安装/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)安装完成后在终端执行brew --version验证。如果提示“command not found”你可能需要按照安装结束时的提示将Homebrew的可执行文件路径添加到你的shell配置文件如~/.zshrc或~/.bash_profile中。例如对于较新Mac系统默认的zshecho eval $(/opt/homebrew/bin/brew shellenv) ~/.zshrc source ~/.zshrc3.2 安装Node.js与npmAppium Server基于Node.js所以我们首先需要安装它。通过Homebrew安装非常方便brew install node安装完成后使用以下命令验证版本node -v npm -v我当前环境显示的是node v18.17.0和npm 9.6.7。只要不是特别陈旧的版本如Node.js v12以下一般都可以正常工作。Node.js会同时安装npm。3.3 安装Python3及pipmacOS系统自带了Python 2.7但我们需要Python 3。同样使用Homebrew安装brew install python3安装后系统会同时安装pip3。为了后续方便我们通常将python3命令软链接为pythonpip3软链接为pip。但更推荐的做法是明确使用python3和pip3命令避免与系统自带的Python 2.7混淆。验证安装python3 --version pip3 --version3.4 安装Java Development Kit (JDK)对于Android测试JDK是必须的。你可以选择安装OpenJDK。通过Homebrew安装一个长期支持版本例如JDK 17brew install openjdk17安装后brew会提示你如何将JDK添加到环境变量。通常需要执行类似下面的命令具体路径以brew安装完成后的提示为准echo export PATH/opt/homebrew/opt/openjdk17/bin:$PATH ~/.zshrc source ~/.zshrc验证安装java -version应该能看到类似openjdk version 17.0.8的信息。实操心得环境变量是Mac配置的常见痛点。如果你在后续步骤中遇到“command not found”的问题首先检查相关组件的路径是否已正确添加到PATH环境变量中。你可以使用echo $PATH查看当前路径。修改完~/.zshrc文件后务必执行source ~/.zshrc使其立即生效或者新开一个终端标签页。4. 分步实操平台SDK与环境配置基础环境就绪后我们来配置针对Android和iOS的特定环境。4.1 Android环境搭建Android Studio SDK下载并安装Android Studio访问 developer.android.com/studio 下载Mac版并安装。安装过程基本是“下一步”到底。首次运行与SDK配置首次启动Android Studio时它会引导你进行初始设置其中最关键的一步是SDK组件安装。在Welcome to Android Studio界面选择右下角的More Actions-SDK Manager。或者安装完成后在Preferences-Appearance Behavior-System Settings-Android SDK中打开SDK管理器。在SDK Platforms标签页选择你需要的Android版本例如Android 13.0 (Tiramisu)或Android 14.0。建议至少选择一个较新的版本和一个市场占有率较高的旧版本如Android 11。切换到SDK Tools标签页。这里至关重要请确保勾选以下项目Android SDK Build-Tools(选择最新版本或你需要的特定版本)Android SDK Command-line Tools (latest)Android EmulatorAndroid SDK Platform-Tools(包含adb, fastboot等)点击Apply开始下载安装。配置Android环境变量为了让终端命令如adb,emulator能够被识别需要将Android SDK的路径添加到环境变量。 首先找到你的Android SDK安装路径。默认路径通常是~/Library/Android/sdk。你可以在Android Studio的SDK管理器中看到确切路径。 然后编辑你的shell配置文件如~/.zshrcnano ~/.zshrc在文件末尾添加以下内容请根据你的实际路径修改export ANDROID_HOME$HOME/Library/Android/sdk export PATH$PATH:$ANDROID_HOME/emulator export PATH$PATH:$ANDROID_HOME/platform-tools export PATH$PATH:$ANDROID_HOME/cmdline-tools/latest/bin保存并退出按CtrlX然后Y 回车。执行source ~/.zshrc。验证Android环境adb version emulator -list-avds如果adb version能输出信息说明平台工具配置成功。emulator -list-avds会列出已创建的模拟器初始为空是正常的。4.2 iOS环境搭建XcodeiOS环境相对简单但安装包巨大。安装Xcode从Mac App Store搜索“Xcode”并安装。这是一个超过10GB的下载请确保网络通畅和磁盘空间充足。安装Xcode命令行工具安装完Xcode后必须安装命令行工具。打开终端执行xcode-select --install在弹出的窗口中点击“安装”。你也可以通过打开Xcode在Preferences-Locations中确认Command Line Tools已选择版本。接受Xcode许可协议在终端执行sudo xcodebuild -license一直按回车阅读到最后输入agree接受协议。创建iOS模拟器可选但推荐虽然可以通过Xcode的Devices and Simulators窗口创建但命令行更快捷。首先查看可用的设备类型和系统版本xcrun simctl list devicetypes # 列出设备类型如iPhone 14 xcrun simctl list runtimes # 列出iOS运行时版本然后创建模拟器例如创建一个名为iPhone 14 Test的模拟器使用iOS 16.2运行时xcrun simctl create iPhone 14 Test com.apple.CoreSimulator.SimDeviceType.iPhone-14 com.apple.CoreSimulator.SimRuntime.iOS-16-2创建后可以通过xcrun simctl list devices查看。踩坑记录Xcode的版本与iOS模拟器的版本强相关。你安装的Xcode版本决定了你能模拟的最高iOS版本。例如Xcode 14.3通常支持到iOS 16.4。如果你的App需要测试更高版本的iOS就必须更新Xcode。同时真机测试还需要Apple开发者账号和配置描述文件这比模拟器测试要复杂得多建议新手先从模拟器开始。5. 分步实操Appium Server与驱动安装基础和环境都准备好了现在来安装主角——Appium Server。5.1 安装Appium Server通过npm在终端中执行以下命令进行全局安装npm install -g appium安装完成后验证安装appium -v这将输出Appium的版本号例如2.5.2。5.2 安装Appium驱动DriversAppium 2.0 的一个重要变化是采用了驱动插件化架构。Server本身是空的需要单独安装你所需的平台驱动。这带来了更好的灵活性和更小的安装体积。安装UiAutomator2驱动用于Androidappium driver install uiautomator2安装XCUITest驱动用于iOSappium driver install xcuitest查看已安装驱动appium driver list --installed你应该能看到uiautomator2和xcuitest的状态为[installed]。5.3 安装Appium客户端库Python在你的项目目录下或者全局环境中安装Python的Appium客户端库pip3 install Appium-Python-Client这个库提供了与Appium Server通信的Python接口。5.4 安装appium-doctor环境诊断工具强烈推荐这是一个非常有用的工具可以检查你的环境配置是否完整。npm install -g appium-doctor安装后运行它来检查环境appium-doctor对于Android运行appium-doctor --android对于iOS运行appium-doctor --ios这个命令会逐项检查必要的依赖如JDK, ANDROID_HOME, adb, xcode等并给出通过✔或失败✖的提示。请务必根据它的提示修复所有标为“✖”的项这是确保环境健康的最快方法。6. 验证环境运行第一个自动化测试脚本理论说千遍不如跑一遍。我们来写一个最简单的Python脚本分别在Android模拟器和iOS模拟器上启动一个应用以验证整个环境是否畅通。6.1 准备测试应用与设备Android确保你有一个Android模拟器在运行。可以在Android Studio的Device Manager中创建并启动一个或者使用命令行emulator -avd 你的模拟器名称启动。准备一个测试APK文件例如从网上下载一个简单的计算器APK。iOS确保你有一个iOS模拟器在运行。可以通过xcrun simctl boot 模拟器UDID启动或者在Xcode中启动。iOS模拟器自带一些应用如“设置”或“Safari”我们可以用这些内置App的Bundle ID来测试。6.2 编写Python测试脚本创建一个名为first_test.py的文件内容如下。这是一个通用模板你需要根据注释替换其中的关键参数。from appium import webdriver from appium.options.common import AppiumOptions import time # 定义Appium Server的地址 APPIUM_SERVER http://127.0.0.1:4723 def test_android(): 测试Android模拟器 options AppiumOptions() # 设置Android设备能力Capabilities options.load_capabilities({ # 必填自动化测试引擎固定为UiAutomator2 platformName: Android, # 必填平台版本在模拟器的关于手机中查看或通过 adb shell getprop ro.build.version.release 获取 platformVersion: 13.0, # 请修改为你的模拟器版本 # 必填设备名通过 adb devices 获取 deviceName: emulator-5554, # 请修改为你的设备名 # 必填待测应用的绝对路径或下载链接这里以计算器为例需提前下载 app: /Users/yourusername/Downloads/calculator.apk, # 请修改为你的APK路径 # 可选App包名用于后续操作可通过 adb shell pm list packages 查看 # appPackage: com.android.calculator2, # 可选App启动Activity # appActivity: com.android.calculator2.Calculator, # 防止每次重置App noReset: True, # 设置命令超时时间 newCommandTimeout: 300 }) try: # 连接Appium Server并启动会话 driver webdriver.Remote(APPIUM_SERVER, optionsoptions) print(Android驱动创建成功) # 等待几秒观察应用是否启动 time.sleep(5) # 这里可以添加一些简单的操作比如点击、输入等 # ... # 退出会话 driver.quit() print(Android测试完成) except Exception as e: print(fAndroid测试出错{e}) def test_ios(): 测试iOS模拟器 options AppiumOptions() # 设置iOS设备能力Capabilities options.load_capabilities({ # 必填自动化测试引擎固定为XCUITest platformName: iOS, # 必填平台版本与模拟器系统版本一致 platformVersion: 16.2, # 请修改为你的模拟器版本 # 必填设备名可以是任意字符串但建议描述性 deviceName: iPhone 14, # 必填待测应用的Bundle ID这里以系统设置为例 bundleId: com.apple.Preferences, # 必填自动化引擎固定为XCUITest automationName: XCUITest, # 防止每次重置App noReset: True, # 设置命令超时时间 newCommandTimeout: 300 }) try: driver webdriver.Remote(APPIUM_SERVER, optionsoptions) print(iOS驱动创建成功) time.sleep(5) driver.quit() print(iOS测试完成) except Exception as e: print(fiOS测试出错{e}) if __name__ __main__: # 在运行测试前请确保已启动Appium Server: appium 或 appium --port 4723 # 并确保对应的模拟器已启动。 print(请先启动Appium Server和对应的模拟器...) # 注释掉你不测试的平台 test_android() # test_ios()6.3 执行验证测试启动Appium Server在一个终端标签页中运行appium如果看到[Appium] Welcome to Appium v2.5.2和[Appium] Appium REST http interface listener started on 0.0.0.0:4723之类的日志说明Server启动成功。启动模拟器按照前面章节的方法启动你的Android或iOS模拟器。修改并运行脚本用文本编辑器打开first_test.py根据你的实际情况修改platformVersion,deviceName,app(Android) 或bundleId(iOS) 等参数。保存后在另一个终端标签页运行python3 first_test.py观察结果如果一切配置正确你应该能在终端看到“驱动创建成功”的打印信息同时在对应的模拟器上看到目标应用计算器或系统设置被自动启动。关键技巧如何获取正确的Capabilities参数AndroiddeviceName在终端运行adb devices列表中显示的设备标识符就是deviceName。AndroidplatformVersion在模拟器中打开“设置”-“关于手机”查看“Android版本”。或者通过adb shell getprop ro.build.version.release获取。AndroidappPackage和appActivity如果你已经安装了APK可以通过adb shell dumpsys window | grep mCurrentFocus命令在应用启动后查看当前窗口的Activity。或者使用adb logcat | grep -i displayed过滤日志。iOSplatformVersion在模拟器中打开“设置”-“通用”-“关于本机”查看“软件版本”。iOSdeviceName可以是任意描述性字符串但通常与模拟器型号一致方便识别。iOSbundleId对于系统应用可以网上搜索如“Safari”的Bundle ID是com.apple.mobilesafari。对于自己开发的应用在Xcode项目设置中查看。7. 常见问题排查与实战技巧实录即使按照步骤操作你也可能会遇到一些问题。下面是我在无数次搭建和教学过程中总结的“高频坑点”及其解决方案。7.1 环境与依赖问题问题1appium命令未找到或appium -v报错。原因Node.js或npm安装异常或全局路径未配置。排查运行node -v和npm -v确认Node.js环境正常。运行which appium查看appium命令的安装路径。如果没输出可能是全局安装失败。解决尝试重新安装npm uninstall -g appium然后npm install -g appium。检查npm的全局安装路径是否在PATH中echo $PATH看是否包含类似/usr/local/bin或/opt/homebrew/bin的路径。npm全局包通常安装在这里。问题2运行appium-doctor --android时ANDROID_HOME检查失败。原因环境变量未正确设置或未生效。解决确认ANDROID_HOME的路径是否正确echo $ANDROID_HOME。确认路径下是否有platform-tools等文件夹。修改~/.zshrc后务必执行source ~/.zshrc或重启终端。有时需要关闭所有终端窗口重新打开。问题3启动Appium Server时提示[UiAutomator2] Error: Cannot find module ‘...’或[XCUITest]类似错误。原因驱动安装不完整或损坏。解决运行appium driver list --installed确认驱动已安装。尝试重新安装驱动appium driver uninstall uiautomator2然后appium driver install uiautomator2。检查网络有时npm安装会因网络问题中断。7.2 设备连接与会话创建问题问题4脚本执行时报错提示无法创建会话错误信息包含Unable to create a new remote session。原因这是最泛化的错误原因可能很多。排查步骤黄金排查流程检查ServerAppium Server终端是否有错误日志红色错误信息是关键。检查设备模拟器是否真的启动了对于Android运行adb devices确认设备在线状态为device。对于iOS运行xcrun simctl list devices确认模拟器状态为Booted。检查Capabilities这是最常见的原因。逐项核对platformVersion,deviceName,app,bundleId,automationName是否完全正确。特别注意大小写和空格。检查端口脚本中连接的端口默认4723是否与Appium Server启动的端口一致如果使用appium -p 4723指定了端口脚本也要改。检查应用Android的app路径是否正确文件是否存在iOS的bundleId对应的应用是否已安装在模拟器上问题5Android测试时安装APK失败提示INSTALL_FAILED_INSUFFICIENT_STORAGE等。原因模拟器存储空间不足或APK不兼容。解决清理模拟器数据或创建一个新的、存储空间更大的模拟器。确认APK的架构arm, x86与模拟器兼容。通常Google提供的系统镜像模拟器是x86架构。问题6iOS测试时提示bundleId对应的应用未安装。原因模拟器上没有这个应用。解决对于系统应用确保Bundle ID正确。可以先用xcrun simctl launch device_udid bundle_id命令手动尝试启动看是否报错。对于自己开发的应用需要先通过Xcode安装到模拟器上。7.3 独家避坑与优化技巧使用appium --allow-insecure解决WebView安全上下文问题在测试混合应用Hybrid App时可能需要切换到WebView上下文。如果遇到安全限制可以在启动Appium时添加参数appium --allow-insecure chromedriver_autodownload。但请注意安全风险仅用于测试环境。为Appium Server指定特定IP和端口如果你的脚本运行在远程机器上或者想避免端口冲突可以这样启动appium --address 0.0.0.0 --port 47230.0.0.0表示监听所有网络接口。使用appium --log-level debug获取详细日志当遇到疑难杂症时在启动Appium时加上--log-level debug参数会打印出极其详细的通信和操作日志是定位问题的利器。管理多个Appium驱动版本Appium 2.0允许安装不同版本的驱动。如果你需要测试不同版本的Android或iOS可以安装特定版本的驱动appium driver install uiautomator22.28.2使用appium driver list --installed查看和管理。将环境搭建过程脚本化对于团队协作或频繁重置环境的情况可以将本章的所有安装命令brew, node, python, appium, drivers等写成一个Shell脚本。这样新成员只需要运行一个脚本就能自动完成大部分环境搭建极大提升效率。环境搭建本身不是目的而是一个让你能专注于自动化测试业务逻辑的起点。当你成功运行第一个脚本看到模拟器自动启动应用时那种成就感会让你觉得之前所有的折腾都是值得的。记住遇到问题别慌按照“看Server日志 - 检查设备连接 - 核对Capabilities”这个三板斧去排查大部分问题都能迎刃而解。