Ubuntu 从零到一搭建 Appium+Python 自动化环境（含下厨房真机实战）

Ubuntu 从零到一搭建 Appium+Python 自动化环境（含下厨房真机实战）—2025 版

适用读者：初级~中级测试工程师；适用系统：Ubuntu 20.04/22.04/24.04；时间：2025-08

本文手把手带你在 Ubuntu 上搭建移动自动化测试环境：JDK、Android SDK、Appium Server、Appium Driver（UiAutomator2）、Appium-Python-Client、Python、PyCharm、定位工具（Appium Inspector），并以 「下厨房」App 为例跑通第一条真机用例。文中包含常见坑位与排查清单，复制即用。

环境准备与术语
系统更新 & 基础工具
安装 JDK（OpenJDK 17）
安装 Android SDK & 平台工具（ADB）
配置环境变量（ANDROID_HOME、PATH）
安装 Node.js（LTS）与 Appium Server（2.x）
安装 Appium Driver：UiAutomator2
使用 appium-doctor 体检与修复
安装 Python & 创建虚拟环境（解决 PEP 668）
安装 Appium-Python-Client
安装 PyCharm（两种方式）
安装与启动 Appium Inspector（定位）
真机连接与 USB 权限（udev 规则）
准备「下厨房」App（获取/安装 APK）
编写并运行第一条 Python 用例
常见问题（FAQ & 故障排查）
附：一键安装脚本 & requirements.txt 模板

1. 环境准备与术语

JDK：Java 开发工具包，Android 构建与部分工具依赖。
Android SDK：Android 平台工具（含 adb）与平台镜像，Appium 真机/模拟器都需要。
Appium Server 2.x：移动端自动化测试服务器，2.x 驱动与插件解耦。
UiAutomator2 Driver：Android 自动化首选驱动，稳定、社区活跃。
Appium-Python-Client：Python 客户端库，与服务端通信。
Appium Inspector：元素定位/录制工具。
PEP 668：Ubuntu 等发行版对系统 Python 依赖的保护策略；解决方案：虚拟环境。

建议准备：一台 Ubuntu、1 条数据线、1 台已开启开发者模式 + USB 调试的 Android 真机。

2. 系统更新 & 基础工具

sudo apt update && sudo apt upgrade -y
sudo apt install -y git curl unzip zip wget software-properties-common build-essential

3. 安装 JDK（OpenJDK 17）

JDK 11/17 均可，推荐 17，兼容性更好。

sudo apt install -y openjdk-17-jdk
java -version    # 确认输出 17

如需切换多版本：sudo update-alternatives --config java

4. 安装 Android SDK & 平台工具（ADB）

下载 Command-line Tools（无 GUI，轻量）：

mkdir -p "$HOME/Android" && cd "$HOME/Android"
wget -O cmdtools.zip https://dl.google.com/android/repository/commandlinetools-linux-11076708_latest.zip
unzip cmdtools.zip -d cmdline-tools
# 为符合 sdkmanager 目录结构，重命名为 latest
mkdir -p "$HOME/Android/cmdline-tools/latest"
mv cmdline-tools/* "$HOME/Android/cmdline-tools/latest/"

先临时设置环境变量（后文会永久写入）：

export ANDROID_HOME="$HOME/Android/sdk"
export PATH="$PATH:$ANDROID_HOME/platform-tools:$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/tools/bin"

安装 SDK 组件（接受许可）：

mkdir -p "$ANDROID_HOME"
yes | sdkmanager --licenses
sdkmanager --update
sdkmanager "platform-tools" \
           "platforms;android-34" \
           "build-tools;34.0.0"
# 如需模拟器：sdkmanager "system-images;android-34;default;x86_64" "emulator"

验证 ADB：

adb version

5. 配置环境变量（永久）

将以下内容追加到 ~/.bashrc 或 ~/.zshrc：

echo 'export JAVA_HOME="/usr/lib/jvm/java-17-openjdk-amd64"' >> ~/.bashrc
echo 'export ANDROID_HOME="$HOME/Android/sdk"' >> ~/.bashrc
echo 'export PATH="$PATH:$ANDROID_HOME/platform-tools:$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/tools/bin"' >> ~/.bashrc
source ~/.bashrc

新开终端后，echo $ANDROID_HOME 应有值。

6. 安装 Node.js（LTS）与 Appium Server（2.x）

不建议用 apt install nodejs（版本可能过旧）。这里用 nvm 安装 LTS。

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
# 安装 LTS 版本（示例：v20 LTS）
nvm install --lts
node -v && npm -v
# 安装 Appium 2.x（全局）
npm install -g appium@latest
appium -v

启动服务（先别关）：appium

7. 安装 Appium Driver：UiAutomator2

你已经走到这一步，这里给出完整命令与排查。

# 列出可用驱动
appium driver list --installed
# 安装/更新 uiautomator2
appium driver install uiautomator2
# 或指定版本：appium driver install --source=npm appium-uiautomator2-driver@latest
# 验证
appium driver list --installed

若安装失败，尝试：

npm config set registry https://registry.npmmirror.com   # 网络慢可换源
appium driver uninstall uiautomator2 || true
appium driver install uiautomator2

8. 使用 appium-doctor 体检与修复

npm install -g appium-doctor
appium-doctor --android

按提示补齐缺失的工具或环境变量。

9. 安装 Python & 创建虚拟环境（解决 PEP 668）

Ubuntu 近年默认 外部管理 Python（PEP 668），不要用 sudo pip 写系统环境。正确方式：虚拟环境。

sudo apt install -y python3 python3-venv python3-pip
cd ~/workspace && mkdir -p appium-demo && cd appium-demo
python3 -m venv venv
source venv/bin/activate
python -m pip install --upgrade pip

若你已在项目目录（如 /home/pxr/xcf）：

cd /home/pxr/xcf
python3 -m venv appium-env
source appium-env/bin/activate
python -m pip install --upgrade pip

10. 安装 Appium-Python-Client

pip install Appium-Python-Client pytest
# 可选：requests loguru allure-pytest 等
pip install requests loguru

11. 安装 PyCharm（两种方式）

方式 A：Snap（简单）

sudo apt install -y snapd
sudo snap install pycharm-community --classic
# 或专业版：sudo snap install pycharm-professional --classic

方式 B：JetBrains Toolbox（推荐管理多 IDE）

从官网下载 Toolbox App（.tar.gz），解压运行 ./jetbrains-toolbox，按向导安装 PyCharm。

若网络受限，可用浏览器手动下载后传到服务器。

12. 安装与启动 Appium Inspector（定位）

方式 A：AppImage（官方发布）

# 以 2025.x 为例，去 GitHub Releases 下载对应 AppImage
chmod +x Appium-Inspector-*.AppImage
./Appium-Inspector-*.AppImage

方式 B：使用终端下载并运行

# 遇到 wget SSL 问题可改用 curl
curl -L -o inspector.AppImage "<GitHub_Release_AppImage_URL>"
chmod +x inspector.AppImage && ./inspector.AppImage

连接到 http://127.0.0.1:4723 的 Appium Server，选择平台 Android，勾选 automationName=UiAutomator2，填好 app 或 appPackage/appActivity 后启动会话。

13. 真机连接与 USB 权限（udev 规则）

打开手机 开发者选项 → USB 调试。
连接数据线，授权。
安装并验证 adb：

adb devices   # 看到 device 状态即成功

若状态为 unauthorized 或 no permissions，添加 udev 规则：

# 新建规则文件（示例包含常见厂商，可按需新增）
cat <<'EOF' | sudo tee /etc/udev/rules.d/51-android.rules
SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", MODE="0666", GROUP="plugdev"   # Google
SUBSYSTEM=="usb", ATTR{idVendor}=="12d1", MODE="0666", GROUP="plugdev"   # HUAWEI
SUBSYSTEM=="usb", ATTR{idVendor}=="2a70", MODE="0666", GROUP="plugdev"   # Xiaomi
SUBSYSTEM=="usb", ATTR{idVendor}=="05c6", MODE="0666", GROUP="plugdev"   # Qualcomm/OPPO/OnePlus
SUBSYSTEM=="usb", ATTR{idVendor}=="04e8", MODE="0666", GROUP="plugdev"   # Samsung
SUBSYSTEM=="usb", ATTR{idVendor}=="0bb4", MODE="0666", GROUP="plugdev"   # HTC
EOF
sudo udevadm control --reload-rules
sudo udevadm trigger
sudo usermod -aG plugdev $USER
adb kill-server && adb start-server
adb devices

重插数据线；必要时重启。

14. 准备「下厨房」App（获取/安装 APK）

方案 A：已安装在真机 → 直接抓取并备份：

adb shell pm list packages | grep xiachufang
# 假设包名为 com.xiachufang（示例）
adb shell pm path com.xiachufang
# 输出形如：package:/data/app/~~xxx==/com.xiachufang-xxxx/base.apk
adb pull /data/app/~~xxx==/com.xiachufang-xxxx/base.apk ~/Downloads/xiachufang.apk

方案 B：未安装 → 自行获取官方渠道 APK，然后：

adb install -r ~/Downloads/xiachufang.apk

获取启动 Activity（用于 Desired Capabilities）：

adb shell cmd package resolve-activity -c android.intent.category.LAUNCHER com.xiachufang
# 或启动一次后查看当前 Activity
adb shell monkey -p com.xiachufang -c android.intent.category.LAUNCHER 1
adb shell dumpsys activity activities | grep mResumedActivity

15. 编写并运行第一条 Python 用例

项目结构建议

/home/pxr/xcf
├── appium-env/                 # venv
├── cases/
│   ├── __init__.py
│   ├── base_case.py
│   └── test_xcf_home.py
├── requirements.txt
└── README.md

requirements.txt（示例）

Appium-Python-Client>=3.2.0
pytest>=8.0.0
requests>=2.31.0
loguru>=0.7.0

base_case.py（示例）

from appium import webdriver
from time import sleep

class BaseCase:
    def setup(self, caps: dict):
        self.driver = webdriver.Remote(
            command_executor="http://127.0.0.1:4723",
            desired_capabilities=caps,
        )
        self.driver.implicitly_wait(10)

    def teardown(self):
        sleep(2)
        self.driver.quit()

test_xcf_home.py（示例，真机+已装 App）

from cases.base_case import BaseCase

# 按你的设备信息修改以下 3 项：platformVersion / deviceName / appPackage+appActivity
ANDROID_VERSION = "13"         # 示例：Android 13
DEVICE_NAME = "emulator-5554"  # 或 adb devices 看到的序列号
APP_PACKAGE = "com.xiachufang"  # 示例包名，按实际修改
APP_ACTIVITY = ".ui.activity.MainActivity"  # 示例入口，按实际修改

class TestXCF(BaseCase):
    def test_launch(self):
        caps = {
            "platformName": "Android",
            "platformVersion": ANDROID_VERSION,
            "deviceName": DEVICE_NAME,
            "automationName": "UiAutomator2",
            "appPackage": APP_PACKAGE,
            "appActivity": APP_ACTIVITY,
            "noReset": True,
            "newCommandTimeout": 180,
        }
        self.setup(caps)

        # 示例：校验首页是否存在某个元素（替换成你的定位）
        # element = self.driver.find_element("xpath", "//*[@text='下厨房']")
        # assert element.is_displayed()

        self.teardown()

运行步骤

# 1) 启动 Appium Server（独立终端）
appium

# 2) 激活虚拟环境（项目终端）
cd /home/pxr/xcf
source appium-env/bin/activate
pip install -r requirements.txt  # 首次

# 3) 确认真机在线
a db devices

# 4) 运行用例（保持在项目根目录）
PYTHONPATH=. python cases/test_xcf_home.py
# 或使用 pytest
pytest -q -s cases/test_xcf_home.py

小技巧：如果你在 cases/ 里直接运行脚本，务必在 cases/ 目录下也加上 __init__.py，或使用 PYTHONPATH=.. 运行，避免 ModuleNotFoundError: No module named 'cases'。

16. 常见问题（FAQ & 故障排查）

Q1：pip install 报 PEP 668 / 要求 --break-system-packages？

原因：系统 Python 受保护。解决：使用 python3 -m venv venv 创建虚拟环境，再在 venv 内 pip install。

Q2：ModuleNotFoundError: No module named 'appium'？

说明：依赖没装到当前 Python。解决：确认已激活 venv，pip install Appium-Python-Client，并用 venv 内的 python 运行。

Q3：adb devices 显示 unauthorized 或 no permissions？

解决：手机点授权；添加 udev 规则；adb kill-server && adb start-server；重插线/换口/换线。

Q4：Appium Inspector AppImage 下载报 SSL 错误？

解决：改用浏览器/curl -L 直接从 GitHub 下载；避免第三方代理源；或临时 --no-check-certificate（仅测试）。

Q5：appium driver install uiautomator2 失败？

解决：npm set registry 切换镜像；appium driver uninstall uiautomator2 后重装；确保 Node.js 版本为 LTS。

Q6：如何获取 appPackage / appActivity？

指令：adb shell pm list packages | grep 关键字；adb shell cmd package resolve-activity -c android.intent.category.LAUNCHER 包名；或启动后 adb shell dumpsys activity activities | grep mResumedActivity。

Q7：PyCharm 用 snap 安装提示找不到包？

解决：sudo apt install snapd 后安装 pycharm-community --classic；或用 JetBrains Toolbox 安装。

Q8：跑用例时 Appium Server 报 Could not find adb？

解决：确认 ANDROID_HOME、PATH 包含 platform-tools，并在 Server 启动的终端中也能 adb version。

17. 附：一键安装脚本 & requirements 模板

install_android_appium.sh（可按需裁剪）

#!/usr/bin/env bash
set -euo pipefail

sudo apt update && sudo apt upgrade -y
sudo apt install -y git curl unzip zip wget software-properties-common build-essential \
    openjdk-17-jdk python3 python3-venv python3-pip

# Android SDK
mkdir -p "$HOME/Android" && cd "$HOME/Android"
wget -O cmdtools.zip https://dl.google.com/android/repository/commandlinetools-linux-11076708_latest.zip
unzip -o cmdtools.zip -d cmdline-tools
mkdir -p "$HOME/Android/cmdline-tools/latest"
mv cmdline-tools/* "$HOME/Android/cmdline-tools/latest/" || true

# ENV
{
  echo 'export JAVA_HOME="/usr/lib/jvm/java-17-openjdk-amd64"'
  echo 'export ANDROID_HOME="$HOME/Android/sdk"'
  echo 'export PATH="$PATH:$ANDROID_HOME/platform-tools:$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/tools/bin"'
} >> ~/.bashrc
source ~/.bashrc

mkdir -p "$ANDROID_HOME"
yes | sdkmanager --licenses
sdkmanager --update
sdkmanager "platform-tools" "platforms;android-34" "build-tools;34.0.0"

# Node & Appium
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install --lts
npm install -g appium@latest appium-doctor
appium driver install uiautomator2

# Python venv（示例项目路径）
PROJECT_DIR="$HOME/xcf"
mkdir -p "$PROJECT_DIR" && cd "$PROJECT_DIR"
python3 -m venv appium-env
source appium-env/bin/activate
pip install --upgrade pip
pip install Appium-Python-Client pytest requests loguru

appium-doctor --android || true

echo "All done. Reopen terminal to ensure PATH is loaded."

保存为 install_android_appium.sh，赋权并执行：

chmod +x install_android_appium.sh
./install_android_appium.sh

requirements.txt（可直接用）

Appium-Python-Client>=3.2.0
pytest>=8.0.0
requests>=2.31.0
loguru>=0.7.0

结束语

到这里，你已经在 Ubuntu 上完成了 JDK → Android SDK → Appium Server 2.x → UiAutomator2 → Python Client → PyCharm → Inspector → 真机跑通用例 的全链路搭建。建议把本文收藏为你的环境手册，并将安装脚本与 requirements.txt 纳入团队仓库，保证环境一致性与可复用性。祝测试顺利！🚀

Ubuntu 从零到一搭建 Appium+Python 自动化环境（含下厨房真机实战）—2025 版