This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.
排查 EAS 模拟器问题
在 EAS 模拟器中诊断访问、会话生命周期、控制器、安装、预览和快速刷新问题。
未找到命令
🌐 Command not found
Command simulator:start not found
已安装的 EAS CLI 太旧。安装或更新 EAS CLI，然后检查命令：
🌐 The installed EAS CLI is too old. Install or update EAS CLI, then inspect the command:
这些命令保持隐藏，因为这个 API 还是实验性的。
🌐 The commands remain hidden because the API is experimental.
simulator:start 拒绝了一个已记录的标记
🌐 simulator:start rejects a documented flag
更新到最新版本的 EAS CLI，然后将命令与安装的帮助进行比较：
🌐 Update to the latest version of EAS CLI, then compare the command with the installed help:
访问和项目错误
🌐 Access and project errors
该账户未启用 EAS 模拟器
🌐 EAS Simulator is not enabled for the account
开始前检查一下：
🌐 Check before starting:
如果 available 是 false，不要重试 simulator:start。可以使用本地模拟器或模拟器，或者加入候补名单获取访问权限。
🌐 If available is false, do not retry simulator:start. Use a local simulator or emulator, or join the waitlist for access.
EAS CLI 报告说需要一个用户账户
🌐 EAS CLI reports that a user account is required
以交互方式登录或在无头环境中提供 EXPO_TOKEN：
🌐 Log in interactively or provide EXPO_TOKEN in a headless environment:
EAS CLI 报告说该项目未关联
🌐 EAS CLI reports that the project is not linked
在 Expo 项目里运行命令并初始化 EAS：
🌐 Run the command inside the Expo project and initialize EAS:
会话生命周期问题
🌐 Session lifecycle problems
这个会话启动很慢
🌐 The session takes a long time to start
启动时间取决于设备容量。在设备启动时，轮询现有会话：
🌐 Boot time varies with device capacity. While the device is starting, poll the existing session:
当状态为 IN_PROGRESS 并且存在 remoteConfig 时，会话就准备好了。如果状态达到 STOPPED 或 ERRORED，或者启动命令报告终止失败，就启动一个新会话。在第一个会话仍在启动时启动第二个会话不会加快进程。
🌐 The session is ready when the status is IN_PROGRESS and remoteConfig is present. If it reaches STOPPED or ERRORED, or the start command reports a terminal failure, start a new session. Starting a second session while the first is still booting does not speed up the process.
非交互式会话没有自动停止
🌐 A non-interactive session did not stop automatically
--non-interactive 会在控制器准备好后返回。它不会停止会话。运行:
开始新的会话时，上一个会话还在运行
🌐 Starting a session left the previous session running
simulator:start 默认会创建一个新会话，即使 .env.eas-simulator 中包含另一个会话 ID。它会替换本地配置，但不会停止之前的远程会话。
列出当前活跃的会话，并明确停止旧的会话：
🌐 List active sessions and stop the old one explicitly:
当你希望 simulator:start 失败，而不是在环境中已有 ID 时创建新会话时，使用 --no-force。给每个会话一个描述性的 --name，这样在列表中就容易识别。
🌐 Use --no-force when you want simulator:start to fail instead of creating a new session while the environment already contains an ID. Give every session a descriptive --name so it is easy to identify in the list.
控制器和隧道问题
🌐 Controller and tunnel problems
Remote daemon is unavailable 或隧道端点离线
🌐 Remote daemon is unavailable or the tunnel endpoint is offline
控制器隧道已断开或远程虚拟机已结束。控制器断开会使已安装的应用状态、可访问性引用和连接配置失效。
🌐 The controller tunnel has dropped or the remote VM has ended. A dropped controller invalidates the installed app state, accessibility references, and connection configuration.
如果会话还在进行，就先停止它，然后再开启一个新的会话，按照安装 → 打开 → 驱动的顺序重复操作。不要对已经失效的端点反复重试控制器命令。
🌐 Stop the session if it is still active, then start a fresh session and repeat install → open → drive. Do not repeatedly retry a controller command against the dead endpoint.
Unknown command: tap 或 Unknown command: click
🌐 Unknown command: tap or Unknown command: click
代理-设备动作命名为 press：
🌐 The agent-device action is named press:
一个控制器动作卡住了
🌐 A controller action hangs
有些 iOS 截图和交互可能需要几十秒。如果某个操作超时，请在重试前刷新交互辅助功能树：
🌐 Some iOS snapshots and interactions can take tens of seconds. If an action times out, refresh the interactive accessibility tree before retrying:
即使响应延迟，原始操作可能已经到达设备，而盲目重试可能会执行两次。
🌐 The original action may have reached the device even when the response was delayed, and blindly retrying can perform it twice.
install requires an active session or an explicit device selector
经过站台：
🌐 Pass the platform:
截图显示没有活动会话
🌐 Screenshot reports that there is no active session
在截屏之前打开已安装的应用：
🌐 Open an installed app before taking the screenshot:
应用和构建问题
🌐 App and build problems
Launch options require an application source
--launch-arg 和 --open-url 适用于会话启动时安装的应用。使用命令传入恰好一个源:
--build-id <build-id>用于 EAS 构建--application-archive-url <url>用于远程应用存档--expo-go用于与项目 SDK 匹配的 Expo Go 版本
对于本地的 .app 或 APK，可以先开启一个空白会话，然后通过代理设备或其他控制器安装它。
🌐 For a local .app or APK, start a blank session and install it through agent-device or another controller instead.
Expo Go 无法确定 SDK 版本
🌐 Expo Go cannot determine the SDK version
从一个有有效应用配置的 Expo 项目中运行命令，或者同时传入 --sdk-version <version> 和 --expo-go。SDK 覆盖在 --build-id 或 --application-archive-url 中无效。
🌐 Run the command from an Expo project with a valid app config, or pass --sdk-version <version> together with --expo-go. The SDK override is not valid with --build-id or --application-archive-url.
远程设备上没有这个应用
🌐 The remote device does not contain the app
当会话在没有 --build-id、--application-archive-url 或 --expo-go 的情况下启动时，这是正常的。可以通过控制器安装本地模拟器或模拟器构建，或者使用应用源启动一个新会话。
🌐 This is expected when the session starts without --build-id, --application-archive-url, or --expo-go. Install a local simulator or emulator build through the controller, or start a new session with an application source.
截图显示了旧的源代码
🌐 The screenshot shows old source code
发布版在构建时会嵌入 JavaScript。可以从当前源代码重新构建它，确认现有的 EAS 构建是否有匹配的指纹，或者安装开发版并连接到 Metro。
🌐 A release build embeds JavaScript at build time. Rebuild it from the current source, confirm that an existing EAS Build has the matching fingerprint, or install a development build and connect it to Metro.
更改源文件不会更新已经安装的发布版。
🌐 Changing source files does not update an already-installed release build.
快速刷新无法使用
🌐 Fast Refresh does not work
确认以下所有内容：
🌐 Confirm all of the following:
- 安装的二进制文件是带有
expo-dev-client的开发版，而不是发布版 - Metro 正在运行一次，没有其他进程占用 8081 端口
- 开发客户端已连接到公共地铁隧道 URL
- 模拟器会话和控制器仍然处于活动状态
在远程或无头代理环境中使用 tunnel v2：
🌐 Use tunnel v2 in remote or headless agent environments:
如果第一次连接失败，请重置模拟器会话和 Metro 一次，然后重复已记录的开发构建流程。重新连接发布版本无法启用快速刷新。
🌐 If the first connection fails, reset the simulator session and Metro once, then repeat the documented development-build flow. Reconnecting a release build cannot enable Fast Refresh.
浏览器预览问题
🌐 Browser preview problems
Android 没有返回 webPreviewUrl
🌐 Android did not return a webPreviewUrl
目前不支持 Android 浏览器预览。请改用 agent-device 或 Argent，然后收集截图或录屏。
🌐 Android browser preview is not currently supported. Use agent-device or Argent and collect screenshots or recordings instead.
预览会显示在模拟器里
🌐 The preview appears inside the simulator
webPreviewUrl 被打开得好像是一个应用链接。请在桌面浏览器中打开它。它是一个浏览器流，不是应用深度链接。
🌐 The webPreviewUrl was opened as though it were an app URL. Open it in the desktop browser instead. It is a browser stream, not an application deep link.
报告反馈
🌐 Report feedback
EAS 模拟器及其 CLI 还处于实验阶段。报告问题时请包括 EAS CLI 版本、会话 ID、平台、控制器类型以及出错的命令。
🌐 EAS Simulator and its CLI are experimental. Include the EAS CLI version, session ID, platform, controller type, and failing command when reporting a problem.
关于官方 EAS 模拟器技能的反馈：
🌐 For feedback about the official EAS Simulator skill: