This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.

在 EAS Simulator 上安装应用，并使用 agent-device、Appium、Argent 或 iOS 浏览器预览来控制应用。

远程设备默认从空白状态启动，除非启动命令收到应用源。你可以让 EAS CLI 在会话启动时安装并启动 EAS Build、应用归档文件或 Expo Go。你也可以启动空白设备，然后通过其控制器安装本地兼容模拟器或仿真器的构建版本。

典型用例： 编码代理启动 agent-device 会话，打开连接到 Metro 的 Expo Go 或开发构建，并使用 Fast Refresh 进行迭代。你可以在 Web 预览中跟进同一 iOS 会话。让代理使用 EAS Simulator skill，它会处理构建工作流、远程会话、设备控制、证据收集和清理。以下章节记录了相同工作流的手动操作方式。

根据您的需求选择构建类型：

警告 发布构建包含构建时的 JavaScript。将其连接到 Metro 不会启用快速刷新。请使用开发构建进行实时迭代。

选择会话类型

在启动会话之前，选择计划用于控制设备的方式。请明确传入会话类型。在 iOS 上，agent-device、Appium 和 Argent 会话同时包含所选控制器和 Web 预览。如果只需要 Web 预览而无需程序化控制，请使用 web-preview-only。

查找应用标识符

在安装构建版本之前，读取解析后的应用配置：

对于 iOS 命令，使用 ios.bundleIdentifier；对于 Android 命令，使用 android.package。创建构建版本之前，请在应用配置中配置缺失的值。

安装 EAS 构建产物

为 EAS Build 配置文件中的每个平台创建可安装的产物。iOS 需要设置 ios.simulator: true，Android 需要进行 APK 构建：

{
  "build": {
    "remote-device": {
      "ios": {
        "simulator": true
      },
      "android": {
        "buildType": "apk"
      }
    }
  }
}

在启动 EAS Simulator 前构建应用。构建过程可能耗时较长，导致空闲的模拟器会话失去其控制器隧道：

从命令输出中记录构建 ID，或查找已完成的模拟器构建：

构建就绪后，将其 ID 传递给 simulator:start。EAS 会在会话就绪前下载、安装并启动构建：

你可以传递应用归档文件 URL，而不是构建 ID：

--build-id 和 --application-archive-url 不能同时使用。iOS 构建必须面向 Simulator。

对于 Android，使用相同的配置文件创建并安装 APK：

Android 构建必须生成 APK。Android 会话支持通过控制器进行交互和截取屏幕截图，但不支持实时浏览器预览。

如果会话已在运行，agent-device 仍可将产物下载到活动远程虚拟机（VM）中：

使用 agent-device 安装本地构建

对于本地 iOS Simulator .app 程序包，install 会通过控制器上传构建：

本地大型构建版本需要更长时间，因为客户端会从你的计算机上传它们。如果有 EAS 构建产物 URL，建议使用 install-from-source。

对于本地 Android APK，使用相同的命令，但指定 Android 包名、APK 路径和 --platform android。

使用 Expo Go

对于兼容 Expo Go 的项目，请先通过公共隧道启动 Metro，再创建模拟器会话。EAS CLI 打开 URL 时，远程设备必须能够访问 Metro：

EAS CLI 会选择与当前项目 Expo SDK 匹配的 Expo Go 版本。只有需要覆盖检测到的版本时，才将 --sdk-version <version> 与 --expo-go 一起传递。--open-url 的值必须是已安装应用能够识别的 Expo URL；不要传递浏览器的 webPreviewUrl。

使用开发构建进行实时更改

实时迭代需要一个带有 expo-dev-client 的开发构建。开发构建会从 Metro 加载 JavaScript，而不是仅依赖构建时嵌入的 bundle。

如果机器无法在本地创建原生构建，请配置一个同时包含 developmentClient: true 和 ios.simulator: true 的 EAS 配置文件：

{
  "build": {
    "development-simulator": {
      "developmentClient": true,
      "ios": {
        "simulator": true
      }
    }
  }
}

在启动模拟器会话之前创建构建：

对于 Android，使用 --platform android 运行构建命令时，同一个配置文件会生成可安装的 APK。无需其他 Android 配置。

使用远程开发客户端可访问的公共隧道启动 Metro。请先启动 Metro，因为 EAS CLI 会在准备会话时打开该 URL：

将 EAS Build ID 和开发客户端 URL 传递给 simulator:start。EAS 会安装并启动构建，然后在会话就绪前打开 URL：

将 <scheme> 替换为应用配置中的自定义 scheme，并在需要时对公共 Metro URL 进行 URL 编码。对于应用需要的启动参数，可重复使用 --launch-arg <value>。

请确保恰好只有一个 Metro 进程在运行。第一个 bundle 加载后，Fast Refresh 会将源代码更改发送到远程应用。

启动命令只能从远程 EAS Build 或应用归档文件安装开发构建。对于本地开发 .app，请启动一个空白 agent-device 会话，使用 install 上传，并通过 agent-device 打开开发客户端 URL。

如需完整且经过测试的开发客户端流程，请安装 EAS Simulator skill。

使用 simulator:exec 运行控制器命令

simulator:exec 与控制器无关。它会加载当前会话的连接环境，并运行后续命令。请使用会话启动时所选控制器对应的命令格式：

使用 agent-device 控制应用

有关安装和更广泛的控制器指南，请参阅 agent-device 和 Expo。

将这些命令与使用 --type agent-device 启动的会话配合使用：

检查交互式辅助功能树：

快照会返回类似 @e1 和 @e2 的引用。使用 press 激活元素：

该操作名为 press，而不是 tap 或 click。

输入文本并截取屏幕截图：

屏幕截图会下载到运行该命令的计算机上。

录制操作流程：

其他有用的控制器命令包括 scroll、gesture、logs、network 和 perf。通过活动会话读取与版本匹配的帮助信息：

使用 Argent 控制应用

有关安装和更广泛的控制器指南，请参阅 Argent 和 Expo。

安装 Argent CLI：

使用以下命令启动由 Argent 支持的会话：

将以下命令用于使用 --type argent 启动的会话。simulator:exec 会从 .env.eas-simulator 提供 ARGENT_TOOLS_URL 和 ARGENT_AUTH_TOKEN，因此无需为通过这种方式调用的命令运行 argent link：

Argent 使用自己的工具和应用安装命令。Argent 会话不会同时配置 agent-device 守护进程，因此不要对其运行 agent-device 命令。

使用 Appium 控制应用

如果要连接现有 Appium 客户端或测试套件，请启动由 Appium 支持的会话：

EAS CLI 会将 APPIUM_URL 和 APPIUM_CAPS 写入 .env.eas-simulator。simulator:exec 会在运行 Appium 客户端命令前加载这些值。Appium 会话不会同时配置 agent-device 或 Argent。

检查会话活动

使用 agent-device 或 Argent 的会话会记录控制器活动。显示当前会话截至目前记录的活动：

在另一个终端中，跟踪你或代理驱动设备时产生的新活动：

会话结束时，跟踪命令会退出。使用 --id <session-id> 检查其他会话，或使用 --json 返回代理或脚本的原始事件记录。--json 和 --follow 不能同时使用。

会话活动描述控制器的操作和交互。它不能替代应用程序运行时日志。

使用 iOS 浏览器预览

受支持的 iOS 会话会返回一个 webPreviewUrl。在会话处于活动状态时，在桌面浏览器中打开它。

将预览交给其他人时，启动会话时添加 --max-duration-minutes <minutes>，以便会话自动停止。你也可以添加 --max-idle-time-minutes <minutes>，使会话在一段时间没有活动后停止。请告知查看者会话何时停止，并记住会话停止前会持续消耗用量。

完成后停止

如果你启动了 Metro，也请停止该进程。