企业官网建设流程全解析

Appium 2 迁移完全指南：从 Appium 1 平滑升级的破坏性变更清单与实战方案

【免费下载链接】appiumCross-platform automation framework for all kinds of apps, built on top of the W3C WebDriver protocol项目地址: https://gitcode.com/GitHub_Trending/ap/appium

Appium 2 是该框架五年来最大的一次架构级发布，它不再执着于改变某个特定平台的自动化行为，而是把整个项目重塑为"核心服务器 + 驱动（Driver）+ 插件（Plugin）"的自动化工具生态。本文基于本仓库的官方迁移文档整理，逐条梳理 Appium 1 升级到 Appium 2 时遇到的全部破坏性变更、对应的修复动作，以及迁移后值得立即使用的核心新特性，并辅以仓库源码层面的实现证据，帮助你在升级前完成完整评估、在升级中按清单逐项改造环境与测试代码，最终平稳落地 Appium 2。

迁移前的准备：为什么不要"直接升级"

Appium 2 是重大架构变更，官方文档明确给出建议：不要直接对 Appium 1 的安装执行就地升级，而是先卸载 Appium 1，再安装 Appium 2。原因在于两者的包结构完全不同——Appium 1 把全部驱动捆绑在服务器包内，而 Appium 2 采用模块化设计：

• 核心 Appium 模块只保留与平台无关的功能；
• 特定平台的自动化能力被拆分为独立的driver（驱动）模块；
• 用于改变或扩展 Appium 行为的能力被拆分为独立的plugin（插件）模块。

同时，Appium 2 借此机会清理了大量老旧、废弃的功能与依赖。从本仓库的目录结构可以直观看到这套模块化的落地：packages 目录下既有承载核心的appium、base-driver、base-plugin、schema、support等基础设施包，也有fake-driver、images-plugin、execute-driver-plugin、storage-plugin、universal-xml-plugin等驱动与插件包——这正是"生态化"结构在源码层面的直接体现。

一、破坏性变更逐条清单

1. 驱动不再随服务器捆绑安装

安装 Appium 1 时，所有官方驱动会一并装好；而 Appium 2 默认只安装核心服务器，不附带任何驱动，需要你主动安装所需驱动。官方提供了三种安装途径：

# 方式一：安装 Appium 时通过 --drivers 标志一并安装指定驱动 npm i -g appium --drivers=xcuitest,uiautomator2 # 方式二：使用 Extension CLI 单独安装 appium driver install uiautomator2 # 方式三：使用 Setup CLI 预设命令（Appium 2.6 新增） appium setup mobile

其中"短名"（如uiautomator2、xcuitest）与真实 npm 包名的对应关系，定义在 packages/appium/lib/constants.ts 中：KNOWN_DRIVERS聚合了移动端（uiautomator2、xcuitest、espresso）、桌面端（mac2、windows）与浏览器端（safari、gecko、chromium）驱动，KNOWN_PLUGINS则收录了execute-driver、images、inspector、relaxed-caps、storage、universal-xml等官方插件。也就是说，appium driver install uiautomator2实际上等价于安装appium-uiautomator2-driver这个 npm 包。

appium setup mobile这类"预设"命令在 packages/appium/lib/cli/setup-command.ts 中实现：setup下分mobile、desktop、browser、reset四个子命令，默认插件为images与inspector，并且会做平台适配——xcuitest、safari、mac2仅在 macOS 主机上安装，windows仅在 Windows 主机上安装。

需要执行的动作：安装 Appium 2 时，务必使用上述三种方式之一安装你所需的驱动。

驱动与插件的完整管理方式（安装、更新、卸载、运行脚本、doctor 检查），请参考 Managing Drivers and Plugins 指南 与 Extension CLI 参考。

2. 驱动的安装路径发生了变化

Appium 1 中，驱动是主服务器的依赖，安装路径固定为/path/to/appium/node_modules，例如手动构建 WebDriverAgent 时会出现在/path/to/appium/node_modules/appium-xcuitest-driver/node_modules/appium-webdriveragent。

Appium 2 中，驱动和插件统一安装到由APPIUM_HOME环境变量指定的目录，其默认值是~/.appium。同样的文件现在位于：

$APPIUM_HOME/node_modules/appium-xcuitest-driver/node_modules/appium-webdriveragent

APPIUM_HOME的妙处在于可以灵活切换多套扩展集合。例如你想让同一驱动在不同版本间共存，可以参考 managing-exts.md 中的做法：

APPIUM_HOME=/path/to/home1 appium driver install xcuitest@4.11.1 APPIUM_HOME=/path/to/home2 appium driver install xcuitest@4.11.2 APPIUM_HOME=/path/to/home1 appium # 使用 xcuitest 4.11.1 APPIUM_HOME=/path/to/home2 appium # 使用 xcuitest 4.11.2

已安装扩展的记录文件（manifest）存放在$APPIUM_HOME/node_modules/.cache/appium/extensions.yaml，这一点与 packages/appium/lib/constants.ts 中定义的缓存目录常量CACHE_DIR_RELATIVE_PATH（node_modules/.cache/appium）相互印证。

需要执行的动作：如果代码里写死了指向 Appium 驱动文件的绝对路径，请改用APPIUM_HOME环境变量推导。

3. 驱动与服务器可以各自独立更新

Appium 1 中，想获得驱动更新必须等待新版本 Appium 发布，然后整体升级服务器；Appium 2 中驱动与服务器是独立 npm 包，可以各自发布、独立更新——你不再需要等待新的服务器版本，即可立刻安装最新驱动。

检查驱动是否有更新，使用 Extension CLI：

appium driver list --updates

若有可用更新，对指定驱动执行update命令：

appium driver update xcuitest

服务器本身的更新方式与以前一致，但由于驱动不再捆绑在服务器包中，升级过程会快很多：

npm update -g appium

需要执行的动作：务必使用 Extension CLI 来管理你的驱动。

补充说明：appium driver update默认只升级 minor/patch 版本以规避破坏性变更，如需升级到新的主版本（major），需要显式加--unsafe参数；appium plugin update installed可以一次性更新所有已安装插件。

4. 已废弃的软件包不再被支持

Appium 1 生态中有些驱动、客户端等包早已被新包取代，Appium 2 不再为这些包提供支持，官方建议迁移到以下替代品：

需要执行的动作：如果你正在使用上述任一软件包，请迁移到官方推荐的替代方案。仓库内 Ecosystem 文档 列出了当前生态中可用的驱动与客户端。

5. 服务器默认基础路径（base path）变更

Appium 1 的默认服务器 URL 是http://localhost:4723/wd/hub，其中/wd/hub是源自 Selenium 1 的历史遗留约定。Appium 2 将默认基础路径改为/，因此默认服务器 URL 变为：

http://localhost:4723/

如果你希望保留 Appium 1 的行为，可以在启动时显式传入--base-path=/wd/hub（参见 服务器 CLI 参考）。

需要执行的动作：在测试脚本中，把目标服务器 URL 的基础路径从/wd/hub改为/；或者通过--base-path=/wd/hub命令行参数沿用旧路径。

从源码看，base path 不只是"URL 前缀"这么简单：在 packages/appium/lib/appium.ts 中，WebDriver BiDi 的 WebSocket 地址也是由address、port、basePath拼接而成的；在 packages/appium/lib/bootstrap/grid-v3-register.ts 中，注册到 Selenium Grid 的节点 URL 同样是http://${addr}:${port}${basePath}的形式。也就是说，修改 base path 会影响所有以此为前缀的 HTTP 路由与 WebSocket 端点，改造时务必全局替换。

6. 服务器端口 0 不再被支持

Appium 1 支持--port 0，其效果是让服务器自动选择一个空闲随机端口。Appium 2 不再允许端口为 0，端口值必须大于等于 1。如果你确实需要随机端口，必须在启动服务器之前自行处理（例如在脚本中探测空闲端口再传入）。

需要执行的动作：如果代码/脚本中使用--port 0启动 Appium，请把端口改为1或更大的值。

7. 驱动特有的 CLI 选项全部"搬家"

Appium 1 中，特定驱动专用的命令行选项都挂在主 Appium 服务器上，例如--chromedriver-executable可以用来为 UiAutomator2 驱动指定 Chromedriver 的位置。Appium 2 中这些选项被移回驱动自身，但不同驱动接收这些选项的方式不同，主要有三种：

仍然作为 CLI 标志，但加上了--driver-<名字>-前缀：

appium --webdriveragent-port=5000 # Appium 1 appium --driver-xcuitest-webdriveragent-port=5000 # Appium 2

改由环境变量传入：

appium --chromedriver-version=100 # Appium 1 CHROMEDRIVER_VERSION=100 appium # Appium 2

改由 capabilities 传入：

appium --chromedriver-executable=/path/to/chromedriver # Appium 1 {"appium:chromedriverExecutable": "/path/to/chromedriver"} # Appium 2

需要执行的动作：如果你使用了驱动特有的 CLI 选项，请查阅对应驱动的文档，确认在 Appium 2 中应通过 CLI 标志、环境变量还是 capability 传入。

8. 部分 CLI 选项不再接受文件路径

Appium 1 中，以下四个服务器选项支持传入文件路径，Appium 会自动解析文件内容作为选项值：

• --nodeconfig
• --default-capabilities
• --allow-insecure
• --deny-insecure

Appium 2 不再解析传入这些选项的文件路径，而是提供了两种指定方式：

• 直接在命令行传字符串：
  • --nodeconfig/--default-capabilities：传 JSON 字符串；
  • --allow-insecure/--deny-insecure：传逗号分隔的列表。
• 写入 Appium 配置文件（详见 Config File 指南）。

需要执行的动作：如果你在使用上述选项时传的是文件路径，请改为直接传递文件内容（字符串），或把内容放入 Appium 配置文件。

9. 旧协议 JSONWP / MJSONWP 被移除

Appium 的 API 长期基于 W3C WebDriver 协议。在 W3C 协议成为标准之前，业界先后使用过 JSON Wire Protocol（JSONWP）和 Mobile JSON Wire Protocol（MJSONWP）。Appium 1 同时兼容这三种协议，以便旧版 Selenium/Appium 客户端与新服务器通信；Appium 2 移除了 JSONWP/MJSONWP 支持，只兼容 W3C WebDriver 协议。

需要执行的动作：确保你使用的 Selenium/Appium 客户端兼容 W3C WebDriver 协议。

10. Capabilities 必须带厂商前缀（vendor prefix）

Appium 1 中创建会话时要指定 desired capabilities（例如要使用哪个驱动）。Appium 2 延续这一行为（现在直接叫 capabilities），但作为 W3C WebDriver 协议规范的一部分，所有非标准 capability 必须使用厂商前缀。

W3C 标准能力（standard capabilities）很少，常见的就是browserName、platformName等几个。其余能力必须以"厂商名 + 冒号"开头，例如moz:、goog:。Appium 的大部分能力超出了 W3C 标准集，因此除个别特例外都必须带appium:前缀：

deviceName # Appium 1 appium:deviceName # Appium 2

这一要求对现有测试套件是否构成破坏，取决于你的客户端：较新版本的官方 Appium 客户端和 Appium Inspector 会自动为所有非标准能力添加appium:前缀，部分云端 Appium 服务商也是如此。关于标准能力与 Appium 扩展能力的完整对照，可参见 Session Capabilities 指南。

当一条会话请求包含大量 Appium 特有能力时，逐个加前缀会很啰嗦，此时可以把它们统一塞进一个appium:options对象能力中：

默认写法（逐个加前缀）：

{ "platformName": "iOS", "browserName": "Safari", "appium:platformVersion": "14.4", "appium:deviceName": "iPhone 11", "appium:automationName": "XCUITest" }

使用appium:options分组：

{ "platformName": "iOS", "browserName": "Safari", "appium:options": { "platformVersion": "14.4", "deviceName": "iPhone 11", "automationName": "XCUITest" } }

警告：appium:options对象内与对象外同名的能力，以对象内的值为准（会覆盖外部值）；不同云服务商对appium:options语法的支持程度可能不一致。

需要执行的动作：为测试中所有 Appium 特有能力添加appium:前缀，或者把它们包裹进appium:options对象。

11. 高级功能被抽离为插件

Appium 2 的设计目标之一，就是把非核心功能抽离为名为plugin的扩展（参见 插件生态文档）。Appium 1 中的两个功能被移到插件中，不再随 Appium 2 捆绑：

如果你在 Appium 1 中使用了这两类功能，迁移步骤为：先安装插件，再在启动服务器时激活插件：

appium plugin install images appium plugin install execute-driver appium --use-plugins=images,execute-driver

这两个插件在本仓库中均有独立实现：packages/images-plugin（内含图像查找finder.ts、图像比较compare.ts、图像元素image-element.ts等模块）和 packages/execute-driver-plugin（内含子进程执行execute-child.ts、VM 宿主绑定vm-host-binding.ts等模块），可以直接阅读其源码了解能力边界。

12. 部分服务器端点不再接受旧参数

Appium 1 中少量端点曾接受过旧的或无用的参数，Appium 2 移除了这些参数的支持。以下是变更清单（✗ 为不再接受的参数，✓ 为 Appium 2 继续接受的参数）：

• POST /session/:sessionId/appium/device/gsm_signal
  • ✗signalStrengh（注意拼写错误）
  • ✓signalStrength
• POST /session/:sessionId/appium/element/:elementId/value
  • ✗value
  • ✓text
• POST /session/:sessionId/appium/element/:elementId/replace_value
  • ✗value
  • ✓text

需要执行的动作：检查你的 Appium 客户端文档中调用这些端点的方法，调整代码只使用被接受的参数名。

13. 内部依赖包被重命名

Appium 1 的内部依赖包各自拥有独立仓库；Appium 2 改为 monorepo 结构，因此大量包被重命名，例如：

appium-base-driver # Appium 1 @appium/base-driver # Appium 2

本仓库的 packages 目录正是这一 monorepo 结构的体现：base-driver、base-plugin、schema、support、types、logger等包全部以@appium/*命名空间组织。

需要执行的动作：如果你的代码没有直接 import Appium 包，则无需任何改动；如果有，请更新所有 Appium 包的导入名称。

二、Appium 2 带来的主要新功能

1. 第三方驱动与插件

你不再局限于官方驱动/插件，甚至不限于 Appium 团队已知的扩展！开发者可以自行创建自定义驱动或插件，并通过 Extension CLI 从npm、git、GitHub、甚至本地文件系统安装。安装时可用--source指定来源，常见的组合方式包括：

# 官方短名 + 版本 appium driver install xcuitest@9.0.0 # 从 npm 安装指定包 appium driver install @appium/fake-driver@beta --source=npm # 从 GitHub 仓库安装（需配合 --package 指定包名） appium driver install https://github.com/appium/appium-xcuitest-driver --source=github --package=appium-xcuitest-driver # 从本地文件系统安装（指向含 package.json 的目录） appium plugin install /path/to/my/plugin --source=local

想要开发自己的驱动或插件？请参考 Developing 文档 与 驱动安装路径约束 中关于APPIUM_HOME的说明。另外值得注意的是，一个合格的驱动必须在package.json的appium字段中暴露driverName、automationName、platformNames、mainClass四个字段——这个校验逻辑在 packages/appium/lib/cli/driver-command.ts 的validateExtensionFields中实现，缺任一字段都会导致安装失败并提示缺失项。

2. 配置文件（Config File）

Appium 2 在命令行参数之外，新增了对配置文件的支持。几乎 Appium 1 中必须在 CLI 上指定的选项，现在都可以写进配置文件。配置文件支持 JSON、JS、YAML 三种格式。推荐命名为.appiumrc.json、.appiumrc.yaml、.appiumrc.js等（完整清单见 Config File 指南），Appium 会从当前工作目录向上逐级自动查找；也可用appium --config /path/to/config显式指定。

配置文件的结构是根级server对象，所有参数作为其子属性，且直接使用"原生类型"——例如 CLI 中要求逗号分隔列表的--use-plugins，在配置文件中就是一个数组：

{ "server": { "use-plugins": ["images", "execute-driver"] } }

驱动和插件自身的配置分别放在server.driver与server.plugin下，每个扩展一个命名属性（属性名使用 kebab-case，且区分大小写）：

{ "server": { "driver": { "xcuitest": { "webkit-debug-proxy-port": 5400 } } } }

上面的配置等价于 CLI 参数--driver-xcuitest-webkit-debug-proxy-port 5400——注意它正好对应前面"破坏性变更第 7 条"中提到的驱动特有选项的新命名规则。同时请记住：CLI 参数的优先级高于配置文件，两者同时设置时以 CLI 为准。仓库的 sample-code 目录 提供了 JSON、YAML、JS 三种格式的完整示例文件（appium.config.sample.json、appium.config.sample.yaml、appium.config.sample.js），可以直接作为模板使用。

3. 使用 npm 直接管理驱动与插件

如果你本来就在用 npm 管理 Node.js 项目，还有一条更贴合工程实践的扩展管理路线：把驱动、插件直接声明为项目的依赖，Appium 启动时会自动识别。前提是当前目录处于某个 npm 包中、appium出现在该包的依赖（dev/prod/peer）里、且未显式设置APPIUM_HOME。例如：

{ "devDependencies": { "appium": "^2.0.0", "appium-xcuitest-driver": "^4.11.1" } }

然后在项目内执行npx appium，Appium 就会检测到项目依赖关系并加载对应的驱动。这种方式仅推荐给已经在用 npm 管理项目的团队；否则还是优先使用 Extension CLI，必要时通过APPIUM_HOME调整扩展的存储位置。详见 Managing Drivers and Plugins 指南。

三、面向云服务提供商的特别说明

以上内容大多适用于 Appium 终端用户或普通开发者，但 Appium 2 的部分架构变更对各类 Appium 服务提供商（云测平台）而言同样是破坏性的。归根结底，Appium 服务器的维护者负责安装并向终端用户暴露各种驱动与插件——这意味着云平台需要：

• 用上文的方式预先安装并持续更新维护驱动与插件集合；
• 兼容 W3C WebDriver 协议、正确处理appium:前缀与appium:options语法（不同云平台对appium:options的支持程度可能不同）；
• 规划好APPIUM_HOME下的多版本、多租户扩展管理方案；
• 适配默认 base path 由/wd/hub变为/的变化。

官方建议云服务商认真阅读并理解 Session Capabilities 指南中的云服务商能力建议，以行业兼容的方式满足用户需求。

四、迁移行动清单速查

把全文要点汇总成一张可逐项勾选的清单，供升级时对照执行：

1. 先卸载 Appium 1，再安装 Appium 2，不要原地升级；
2. 通过--drivers、appium driver install或appium setup mobile安装所需驱动；
3. 代码中引用驱动文件路径的地方，改用APPIUM_HOME环境变量推导；
4. 用appium driver list --updates与appium driver update <name>取代"等服务器发版"的更新习惯；
5. 已废弃的 iOS Driver / UiAutomator /wd/ Appium Desktop 迁移到官方替代品；
6. 测试脚本中服务器 URL 基础路径由/wd/hub改为/（或启动时加--base-path=/wd/hub）；
7. 将--port 0改为1及以上的具体端口，随机端口自行探测；
8. 排查驱动特有 CLI 选项，按驱动文档改为--driver-*前缀标志、环境变量或 capability；
9. --nodeconfig、--default-capabilities、--allow-insecure、--deny-insecure不再接受文件路径，改为直接传字符串或写进配置文件；
10. 客户端升级到兼容 W3C WebDriver 协议（不再支持 JSONWP/MJSONWP）的版本；
11. 所有 Appium 特有 capability 加appium:前缀，或用appium:options分组；
12. 图像相关与 execute-driver 功能改为安装并激活images、execute-driver插件；
13. 涉及gsm_signal、元素value/replace_value端点的代码改用新参数名；
14. 若代码直接 import Appium 内部包，更新为@appium/*命名。

完成以上改造后，你还可以立即享用 Appium 2 带来的新能力：第三方驱动/插件生态、配置文件驱动的服务器参数管理，以及驱动与服务器的独立快速迭代。

【免费下载链接】appiumCross-platform automation framework for all kinds of apps, built on top of the W3C WebDriver protocol项目地址: https://gitcode.com/GitHub_Trending/ap/appium