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

在 EAS 模拟器上安装一个应用，然后用 agent-device、Appium、Argent 或 iOS 浏览器预览来控制它。

远程设备在没有收到应用源的启动命令时会启动为空白状态。你可以在会话开始时让 EAS CLI 安装并启动 EAS Build、应用归档或 Expo Go。你也可以先启动一个空白设备，然后通过它的控制器安装本地模拟器或模拟器兼容的构建。

🌐 The remote device starts blank unless the start command receives an application source. You can ask EAS CLI to install and launch an EAS Build, an application archive, or Expo Go while the session starts. You can also start a blank device and install a local simulator- or emulator-compatible build through its controller.

信息 典型使用场景： 一个编码代理启动代理-设备会话，打开 Expo Go 或连接到 Metro 的开发构建，并通过快速刷新进行迭代。你可以在网页预览中跟踪同样的 iOS 会话。让代理使用 EAS 模拟器技能，它可以处理构建工作流、远程会话、设备控制、证据收集和清理。下面的部分记录了手动使用的同样工作流程。

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

🌐 Choose the build type based on what you need:

警告 发布版包含构建时的 JavaScript。连接到 Metro 并不会启用快速刷新。想要实时迭代，请使用开发版。

选择一个会议类型

🌐 Choose a session type

在开始会话之前，选择你打算如何控制设备。明确传递会话类型。在 iOS 上，agent-device、Appium 和 Argent 会话包含所选的控制器和网页预览。如果你只需要网页预览而不需要编程控制，请使用 web-preview-only。

🌐 Choose how you plan to control the device before starting the session. Pass the session type explicitly. On iOS, agent-device, Appium, and Argent sessions include both the selected controller and a web preview. Use web-preview-only when you only need the web preview without programmatic control.

找到应用标识

🌐 Find the app identifier

在安装版本之前先查看已解决的应用配置：

🌐 Read the resolved app configuration before installing a build:

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

🌐 Use ios.bundleIdentifier for iOS commands and android.package for Android commands. Configure the missing value in the app config before creating the build.

安装 EAS 构建产物

🌐 Install an EAS Build artifact

在 EAS 构建配置中为每个平台创建可安装的构件。iOS 需要 ios.simulator: true，Android 需要一个 APK 构建 ：

🌐 Create an installable artifact for each platform in an EAS Build profile. iOS requires ios.simulator: true, and Android requires an APK build:

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

在启动 EAS 模拟器之前先构建应用。构建可能需要足够长的时间，以至于空闲的模拟器会丢失其控制器通道：

🌐 Build the app before starting EAS Simulator. A build can take long enough for an idle simulator session to lose its controller tunnel:

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

🌐 Record the build ID from the command output, or find a completed simulator build:

构建准备好后，把它的 ID 传给 simulator:start。EAS 会下载、安装并启动这个构建，然后会话就准备好了：

🌐 After the build is ready, pass its ID to simulator:start. EAS downloads, installs, and launches the build before the session becomes ready:

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

🌐 You can pass an application archive URL instead of a build ID:

--build-id 和 --application-archive-url 互斥。iOS 构建必须以模拟器为目标。

对于安卓，从同一个配置文件创建并安装 APK：

🌐 For Android, create and install the APK from the same profile:

Android 构建必须生成一个 APK。Android 会话支持控制器驱动的交互和截图，但不支持实时浏览器预览。

🌐 The Android build must produce an APK. Android sessions support controller-driven interactions and screenshots, but not the live browser preview.

如果会话已经在运行，代理设备仍然可以将一个工件下载到活动的远程虚拟机（VM）中：

🌐 If the session is already running, agent-device can still download an artifact into the active remote virtual machine (VM):

用 agent-device 安装本地版本

🌐 Install a local build with agent-device

对于本地 iOS 模拟器 .app 的包，install 通过控制器上传构建：

🌐 For a local iOS Simulator .app bundle, install uploads the build through the controller:

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

🌐 Large local builds take longer because the client uploads them from your machine. Prefer install-from-source when an EAS artifact URL is available.

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

🌐 For a local Android APK, use the same command with the Android package, APK path, and --platform android.

使用 Expo Go

🌐 Use Expo Go

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

🌐 For a project that is compatible with Expo Go, start Metro with a public tunnel before creating the simulator session. The remote device must be able to reach Metro when EAS CLI opens the URL:

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

🌐 EAS CLI selects the Expo Go version that matches the current project's Expo SDK. Pass --sdk-version <version> with --expo-go only when you need to override the detected version. The --open-url value must be an Expo URL that the installed app understands; do not pass the browser's webPreviewUrl.

使用开发版以实现实时更改

🌐 Use a development build for live changes

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

🌐 Live iteration requires a development build with expo-dev-client. The development build loads JavaScript from Metro instead of relying only on the bundle embedded at build time.

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

🌐 If the machine cannot create the native build locally, configure an EAS profile with both developmentClient: true and ios.simulator: true:

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

在开始模拟器会话之前先创建构建：

🌐 Create the build before starting the simulator session:

对于 Android，相同的配置在你使用 --platform android 运行构建命令时会生成一个可安装的 APK。不需要额外的 Android 配置。

🌐 For Android, the same profile produces an installable APK when you run the build command with --platform android. No additional Android configuration is required.

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

🌐 Start Metro with a public tunnel that the remote development client can reach. Start Metro first because EAS CLI opens the URL while preparing the session:

将 EAS 构建 ID 和开发客户端 URL 传给 simulator:start。EAS 会安装并启动构建，然后在会话准备好之前打开这个 URL：

🌐 Pass the EAS Build ID and development-client URL to simulator:start. EAS installs and launches the build, then opens the URL before the session becomes ready:

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

🌐 Replace <scheme> with the custom scheme from the app config and URL-encode the public Metro URL when needed. Repeat --launch-arg <value> for any launch-time arguments the app requires.

保持只运行一个 Metro 进程。第一个包加载后，Fast Refresh 会将源代码的修改发送到远程应用。

🌐 Keep exactly one Metro process running. After the first bundle loads, Fast Refresh sends source edits to the remote app.

start 命令只能从远程 EAS Build 或应用存档安装开发版本。对于本地开发 .app，先启动一个空的 agent-device 会话，用 install 上传它，然后使用 agent-device 打开开发客户端 URL。

🌐 The start command can install a development build only from a remote EAS Build or an application archive. For a local development .app, start a blank agent-device session, upload it with install, and use agent-device to open the development-client URL.

要完成完整的测试开发客户端流程，请安装 EAS 模拟器技能。

🌐 For the complete tested development-client sequence, install the EAS Simulator skill.

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

🌐 Run controller commands with simulator:exec

simulator:exec 是与控制器无关的。它会加载活动会话的连接环境并运行随后的命令。请使用会话开始时选择的控制器的命令模式：

用代理设备控制应用

🌐 Control the app with agent-device

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

🌐 For installation and broader controller guidance, see agent-device and Expo.

在用 --type agent-device 开始的会话中使用这些命令：

🌐 Use these commands with a session started with --type agent-device:

检查交互式可访问性树：

🌐 Inspect the interactive accessibility tree:

快照会返回像 @e1 和 @e2 这样的引用。使用 press 来激活一个元素：

🌐 The snapshot returns references such as @e1 and @e2. Use press to activate an element:

这个动作叫做 press，不是 tap 或 click。

🌐 The action is named press, not tap or click.

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

🌐 Enter text and capture a screenshot:

截图已下载到运行该命令的机器上。

🌐 The screenshot is downloaded to the machine running the command.

记录一个流程：

🌐 Record a flow:

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

🌐 Other useful controller commands include scroll, gesture, logs, network, and perf. Read the version-matched help through the active session:

用 Argent 控制这个应用

🌐 Control the app with Argent

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

🌐 For installation and broader controller guidance, see Argent and Expo.

安装 Argent CLI:

🌐 Install the Argent CLI:

使用 Argent 启动会话：

🌐 Start an Argent-backed session with:

在使用 --type argent 启动的会话中使用这些命令。simulator:exec 会从 .env.eas-simulator 提供 ARGENT_TOOLS_URL 和 ARGENT_AUTH_TOKEN，因此以这种方式调用命令时不需要 argent link：

🌐 Use these commands with a session started with --type argent. simulator:exec supplies ARGENT_TOOLS_URL and ARGENT_AUTH_TOKEN from .env.eas-simulator, so argent link is not required for commands invoked this way:

Argent 使用自己的工具和应用安装命令。Argent 会话也不会配置代理设备守护程序，所以不要对它运行代理设备命令。

🌐 Argent uses its own tools and app installation commands. An Argent session does not also provision an agent-device daemon, so do not run agent-device commands against it.

用 Appium 控制应用

🌐 Control the app with Appium

当你想连接一个现有的 Appium 客户端或测试套件时，启动一个由 Appium 支持的会话：

🌐 Start an Appium-backed session when you want to connect an existing Appium client or test suite:

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

🌐 EAS CLI writes APPIUM_URL and APPIUM_CAPS to .env.eas-simulator. simulator:exec loads those values before running the Appium client command. Appium sessions do not also provision agent-device or Argent.

查看会话活动

🌐 Inspect session activity

使用代理设备或Argent记录控制器活动的会话。显示当前会话到目前为止记录的活动：

🌐 Sessions that use agent-device or Argent record controller activity. Show the activity recorded so far for the current session:

在另一个终端中，当你或代理操作设备时，跟踪新的活动：

🌐 In another terminal, follow new activity while you or an agent drives the device:

以下命令会在会话结束时退出。使用 --id <session-id> 检查另一个会话，或者使用 --json 返回某个代理或脚本的原始事件记录。--json 和 --follow 不能同时使用。

🌐 The follow command exits when the session ends. Use --id <session-id> to inspect another session, or --json to return raw event records for an agent or script. --json and --follow cannot be used together.

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

🌐 Session activity describes controller operations and interactions. It does not replace application runtime logs.

记录网络流量

🌐 Record network traffic

在 iOS 上，会话可以记录设备上应用发出的 HTTP 和 HTTPS 请求。开始会话时添加 --network-capture ：

🌐 On iOS, a session can record the HTTP and HTTPS requests that apps on the device make. Add --network-capture when you start the session:

在会话运行时，网页预览会在其 工具 面板的 网络请求 下列出每个请求。

🌐 While the session runs, the web preview lists each request under Network requests in its Tools panel.

警告 网络捕获会解密 HTTPS。它不会编辑你保留的正文和查询值，所以这些内容可能包含明文的凭证。只保留你需要的字段，并且把预览链接和下载文件当作密钥对待。

被记录下来的东西

🌐 What gets recorded

Capture 会记录一个应用通过它创建的 URLSession 发送的 HTTP 和 HTTPS 请求。React Native 的 fetch 和图片加载就是通过这种方式发送请求的。Capture 也会记录那些自己创建 URLSession 的库和 SDK 的请求，比如 expo-updates 的更新检查。

🌐 Capture records HTTP and HTTPS requests that an app sends through a URLSession that it creates. React Native fetch and image loading send requests this way. Capture also records requests from libraries and SDKs that create their own URLSession, such as update checks from expo-updates.

• 重新启动一个已经在运行的应用来记录它的流量。在 agent-device 和 Argent 会话中，捕获可以在已安装应用的首次启动后开始。这种情况下，会捕获不到应用仅在启动时发送的请求。重新启动应用可能不会再次发送这些请求。
• 抓包不会记录来自苹果系统应用（比如 Safari）的流量，也不会记录使用 URLSession.shared 的请求。
• 在 Android 上，或者当会话通过你的机器使用 --egress local 发送流量时，无法进行网络捕获。如果你同时传递 --network-capture 和 --egress local，eas simulator:start 会报错。

选择保留什么

🌐 Choose what to keep

默认情况下，录音只会保留每个请求的方法、URL、状态、时间和大小，并会在 URL 中屏蔽查询值。使用 --network-capture-field 可以保留更多内容：

🌐 By default, a recording keeps only the method, URL, status, timing, and size of each request, and redacts query values in URLs. Use --network-capture-field to keep more:

重复标志，或传递用逗号分隔的列表：

🌐 Repeat the flag, or pass a comma-separated list:

下载录音

🌐 Download the recording

录制仅在捕获进行时存在。EAS 不会将其保存为会话记录。在停止会话之前，或者在 网络请求 下选择 关闭并重启 前下载它，因为这两种操作都会删除它。下载的文件是一个 HTTP Archive (HAR) 文件，浏览器开发者工具和 HTTP 调试工具都可以打开它。

🌐 The recording exists only while capture is on. EAS does not save it as a session artifact. Download it before you stop the session or select Turn off and restart under Network requests, because both actions delete it. The download is an HTTP Archive (HAR) file, which browser developer tools and HTTP debugging tools can open.

要在浏览器中下载它，请在网页预览中打开 工具 面板。在 网络请求 下，选择下载图标，其工具提示为 将会话下载为 HAR。

🌐 To download it in the browser, open the Tools panel in the web preview. Under Network requests, select the download icon, whose tooltip reads Download session as HAR.

要从命令行下载它，请获取会话的预览 API URL：

🌐 To download it from the command line, get the session's preview API URL:

从输出中复制 remoteConfig.previewApiUrl。它的形式是 https://<preview-host>/?token=<token>。在 Authorization 头中发送令牌，因为捕获路由不接受 URL 中的令牌：

文件中的每一条记录都有请求和响应、状态和时间，还有你选择保留的头信息和内容。

🌐 Each entry in the file has the request and response, the status, and timings, plus the headers and bodies that you chose to keep.

排查在截取时失败的应用

🌐 Troubleshoot apps that fail during capture

Capture 会将应用的流量通过会话机器上的代理发送并解密。有些应用会对此有反应：固定了服务器证书的应用无法连接，其他请求可能失败或超时。如果在开启 capture 时应用表现异常，可以启动一个不带 --network-capture 的新会话来检查是否是 capture 导致的。不需要时就关掉 capture。

🌐 Capture sends the app's traffic through a proxy on the session's machine and decrypts it. Some apps react to that: apps that pin their server certificates cannot connect, and other requests can fail or time out. If the app behaves in an unexpected way while capture is on, start a new session without --network-capture to check whether capture causes it. Leave capture off when you do not need it.

使用 iOS 浏览器预览

🌐 Use the iOS browser preview

支持的 iOS 会话会返回一个 webPreviewUrl。在会话有效期间，用桌面浏览器打开它。

🌐 Supported iOS sessions return a webPreviewUrl. Open it in a desktop browser while the session is active.

当把预览交给别人时，在开始会话时加上 --max-duration-minutes <minutes> 这样它会自动停止。你也可以加上 --max-idle-time-minutes <minutes>，在一段时间没有会话活动后停止。告诉查看者会话什么时候会停止，并记住它会一直消耗使用量直到停止。

🌐 When handing the preview to another person, add --max-duration-minutes <minutes> when starting the session so it stops automatically. You can also add --max-idle-time-minutes <minutes> to stop after a period without session activity. Tell the viewer when the session will stop, and remember that it continues consuming usage until it stops.

完成后停止

🌐 Stop when finished

如果你启动了 Metro，也把那个进程停掉。

🌐 If you started Metro, stop that process too.