在 Limrun 远程模拟器上运行 Expo/React…

当需要在远程 iOS 模拟器或 Android 模拟器上运行 Expo dev-client 构建、通过 Metro 隧道进行 JS/TS 热更新迭代而无需反复原生重建时使用。

适用场景

解决思路

1. 所有构建和设备操作都必须在 Limrun 上运行，不要使用本地 Xcode、本地模拟器、本地 Android SDK 或本地模拟器；本地 adb 仅用于通过 CLI 隧道与远程模拟器通信。
2. 在修改 Expo 依赖或应用配置前，检查应用的 Expo SDK 版本并使用匹配的版本化文档。
3. 用 `npx expo config --type introspect --json` 验证这是 Expo 应用，并推导：从 `ios.bundleIdentifier` 得到 `BUNDLE_ID`、从 `android.package` 得到 `PACKAGE`（若缺失，introspect 会报告占位符而构建会生成不同的真实 applicationId，需先在 app.json 中设置 `android.package`）、从 `slug` 得到 `SLUG`、从 `scheme` 得到 `SCHEME`（回退到 `exp+${SLUG}`）、从 `git branch --show-current` 得到 `BRANCH`（回退到 `main`）、iOS 上 `ASSET_NAME="${BUNDLE_ID}/${BRANCH}-debug.zip"`、Android 上 `ASSET_NAME="${PACKAGE}/${BRANCH}-debug.apk"`。
4. Expo 开发构建需要 `expo-dev-client`；若 package.json 中缺失，用 `npx expo install expo-dev-client` 自动安装。
5. 安装 expo-dev-client、增删改原生依赖或修改原生应用配置后，已上传的 Debug 资产会过期，必须在启动开发循环前重新构建 Debug 应用，不要只警告用户。
6. 先用 `lim asset list --name-prefix "$BUNDLE_ID/"`（iOS）或 `lim asset list --name-prefix "$PACKAGE/"`（Android）检查是否已有可复用的 Debug dev-client 资产；仅当资产存在且本次会话未改动原生依赖或原生配置时才复用该 `$ASSET_NAME`。
7. 复用资产时，用 `lim ios create --reuse-if-exists --install-asset "$ASSET_NAME" --label repo=<repo> --label agent=<agent>` 或 `lim android create --reuse-if-exists --install-asset "$ASSET_NAME" --no-open --label repo=<repo> --label agent=<agent>` 创建或复用设备并安装。
8. Android 注意：保留 create 默认打开的隧道（不要传 `--no-connect`），Metro 反向隧道会走它；记下输出的实例 ID，并在之后每次 `lim android` 调用中传 `--id`，因为 Metro 和 Expo 从应用目录运行，实例解析按 git worktree 进行。
9. Android 全新构建：用 `lim gradle build . --upload "$ASSET_NAME"` 远程构建 Debug APK 并上传为资产，再用 `lim android create --reuse-if-exists --install-asset "$ASSET_NAME" --no-open --label repo=<repo> --label agent=<agent>` 创建。
10. Android 后续原生重建：用 `--upload` 重新构建，并通过构建输出的 Download URL 安装新 APK：`lim gradle build . --upload "$ASSET_NAME"` 然后 `lim android install-app "<Download URL from the build output>" --id <android-instance-id>`。
11. iOS 全新构建：先创建或复用独立的 Xcode 沙箱再构建，避免模拟器在长构建期间空闲超时：`lim xcode create --reuse-if-exists --label repo=<repo> --label agent=<agent>`，然后 `lim xcode build . --configuration Debug --upload "$ASSET_NAME"`。
12. 当项目需要特定 Xcode 主版本时，在仓库中运行一次 `lim xcode version set <major>`。
13. 项目布局需要时使用 `--expo-app-dir`、`--scheme` 或 `--workspace`。
14. 然后创建附加到该 Xcode 目标的模拟器，附加会立即安装并启动构建：`lim ios create --attach --reuse-if-exists --label repo=<repo> --label agent=<agent>`。
15. 没有浏览器可展示给用户时，给任何 `create` 加 `--no-open`，跳过打开流 URL 并在输出中保留 URL 供分享。
16. 若 iOS 模拟器已从复用资产运行且后续需要原生重建，用 `lim xcode attach-simulator <ios-instance-id> --id <xcode-instance-id>` 附加同一模拟器而不是创建第二个；附加后每次成功的 `lim xcode build` 都会安装并启动应用到该模拟器。
17. iOS 上在 Debug 应用安装后启动一个目标隧道，Metro 保持正常本地端口，Expo 广播 localhost：`METRO_PORT=8081`、`lim ios tunnel --selector "localhost:${METRO_PORT}" --detach --id <ios-instance-id>`、`TUNNEL_URL="http://localhost:${METRO_PORT}"`，然后 `EXPO_PACKAGER_PROXY_URL="$TUNNEL_URL" npx expo start --dev-client --port "$METRO_PORT"`。
18. `EXPO_PACKAGER_PROXY_URL` 保持 localhost 和声明的端口出现在 manifest、bundle URL 和深链中；内联设置以优先于项目 dotenv 值；用户迭代期间保持 Metro 和分离隧道运行。
19. 若 8081 端口被占用，选择另一个显式端口并在隧道 selector、`TUNNEL_URL` 和 Expo 的 `--port` 中使用相同值；selector 集不可变，端口变化时需停止并用完整 selector 列表重建隧道。
20. 仅在依赖已安装且确实网络隔离的环境中使用 `--offline`；离线模式禁用网络检查和依赖验证，不要用它补偿普通的 Expo 认证问题。
21. iOS 启动 dev client：用 `ENCODED_URL="$(node -e 'console.log(encodeURIComponent(process.argv[1]))' "$TUNNEL_URL")"` 编码 URL，构造 `DEV_CLIENT_URL="${SCHEME}://expo-development-client/?url=${ENCODED_URL}"`，然后 `lim ios open-url --id <ios-instance-id> "$DEV_CLIENT_URL"`。
22. 若打开失败且主 scheme 来自 `scheme`，用 `exp+${SLUG}` 重试一次；新实例上 iOS dev-menu 引导页可能消耗第一个深链，点过它再打开 URL。
23. Expo Go 场景：把 `--dev-client` 换成 `--go`，然后打开 `lim ios open-url --id <ios-instance-id> "exp://${TUNNEL_URL#http://}"`。
24. 隧道生命周期管理：用 `lim ios tunnel status --id <ios-instance-id> --json` 查看状态，用 `lim ios tunnel stop --id <ios-instance-id>` 停止；一个实例只接受一个活动目标隧道，启动另一路由集前先停止当前隧道；迭代结束时用 Ctrl+C 停止 Metro 并用上述命令停止分离隧道。
25. 若 Metro 停止时模拟器尝试路由，隧道保持活动并在状态中记录相关的 `connection_refused`；用相同代理 URL 重启 Metro 并重新打开 dev-client URL，不要重建模拟器或隧道。
26. Android 上 Metro 走 `adb reverse`：`lim android connect --id <android-instance-id>`（后台 shell，打印 "Tunnel started on 127.0.0.1:<port>."），然后 `adb -s 127.0.0.1:<port> reverse tcp:8081 tcp:8081`，再 `npx expo start --dev-client --port 8081`，最后 `lim android open-url "${SCHEME}://expo-development-client/?url=http%3A%2F%2F127.0.0.1%3A8081" --id <android-instance-id>`。
27. ADB 隧道随启动它的 shell 一起消亡，且每次重连端口都会变；重连后用新 serial 重新运行 `adb reverse`。
28. 首次启动时点过 dev-menu 引导页（`lim android tap-element --text Continue`）并关闭 dev menu，bundle 会在原生 sheet 后面加载。
29. 回退方案：若 Limrun 端点不可用，用 `npm install --save-dev '@expo/ngrok@^4.1.0'` 和 `npx expo start --dev-client --tunnel` 启动 Expo 公共隧道，然后用 Expo 打印的完整 dev-client URI 通过 `lim ios open-url` 或 `lim android open-url` 打开。
30. 遗留 iOS 固定端口反向隧道：`lim ios reverse` 仍可用于已使用保留端口 57090–57099 的工作流；在 `REACT_NATIVE_PACKAGER_HOSTNAME` 和编码的 dev-client URL 中都使用 `lim ios reverse` 打印的面向模拟器的主机，并在 Metro 运行时把 reverse 命令保持在单独或后台终端：`lim ios reverse 57090:57090 --id <ios-instance-id>`，然后 `REACT_NATIVE_PACKAGER_HOSTNAME=<reverse-host> npx expo start --dev-client --host lan --port 57090`，再构造并打开编码的 dev-client URL。
31. 快速静态验证优先用 `npx tsc --noEmit`；仅当仓库已配置 ESLint 时才运行 `npm run lint` 或 `npx expo lint`，因为 Expo lint 可能在未配置 lint 的项目中创建 ESLint 配置并改动依赖。
32. iOS 验证先用元素树 `lim ios element-tree`；成功意味着应用 UI 可见或 Expo dev menu 显示已连接到隧道；新实例上首次 dev-client 启动可能落在覆盖启动器的 dev-menu 引导页，点过它（`lim ios tap-element --ax-label Continue`）再打开 dev-client URL，因为第一个深链被引导页消耗；若元素树无法确认连接，用 `lim ios app-log "$BUNDLE_ID" --tail 100` 检查应用日志。
33. Android 验证用截图而非元素树（Expo 应用通常不暴露无障碍节点，渲染屏幕和空树可共存）：`lim android screenshot check.png --id <android-instance-id>`。
34. 要查看应用为何死亡（崩溃、ANR），用 `lim android launch-app "$PACKAGE" --mode RelaunchIfRunning --id <android-instance-id>` 监视式重启，该命令在应用运行时阻塞（在后台 shell 运行），死亡时打印退出原因、堆栈跟踪和最近的应用日志尾部。
35. 连接后 JS/TS 编辑应通过 Metro 更新而无需再次原生构建；若任务改动原生依赖、原生配置或构建设置，重新启动开发循环前先重建 Debug。
36. 告知用户：设备流作为短 Markdown 链接（如 `[Open simulator stream](<signedStreamUrl>)` 或 `[Open emulator stream](<signedStreamUrl>)`）、上传的 Debug 资产名、JS/TS 改动现在可通过 Metro 迭代、原生改动需要新的 Debug 构建。
37. 最终可分享预览或 PR 演示使用 Release 构建，这样用户无需运行 Metro：iOS 用 `ASSET_NAME="<bundle-id>/<pr-or-session>.zip"` 和 `lim xcode build . --configuration Release --upload "$ASSET_NAME"`；Android 用 `ASSET_NAME="<package>/<pr-or-session>.apk"` 和 `lim gradle build . --task assembleRelease --upload "$ASSET_NAME"`；预览 URL 为 `https://console.limrun.com/preview?asset=${ASSET_NAME}&platform=ios`（APK 资产用 `platform=android`）。
38. 注意：`npx expo start --dev-client` 需要 `expo-dev-client`，否则 Expo 无法确定开发构建的 scheme；`No script URL provided` 通常意味着应用不是 dev-client 构建或启动时未带 dev-client URL；全新原生重建/安装后，像 `Cannot find native module` 这样的陈旧 Metro/运行时错误可能来自旧应用进程，重新打开 dev-client URL 并用 element-tree 验证再假设重建失败；添加原生依赖后的 Debug 构建若仍像旧原生图，这是意外的 Limrun 行为，重试构建，创建全新构建/设备目标仅作为故障排查回退；Expo 隧道启动可能不稳定，改变工作流前先重试；原生依赖或原生配置变化后不要复用已上传的 Debug 资产；Android 上给此循环中每次 `lim android` 调用传 `--id <android-instance-id>`，因为实例解析按 git worktree 且循环命令从混合目录运行；Android 元素树为空而截图显示应用是 Expo 应用的正常现象，用截图验证。

适用边界 · 注意事项

• 不适用于非 Expo/React Native 项目或需要非 Expo 原生构建工作流（应使用 limrun-xcode、limrun-gradle 等构建技能）。
• 不适用于无法访问 Limrun 服务或未安装 lim 命令行的环境（此时只能用 Expo 公共隧道回退，但仍需 lim 打开 URL）。
• 不适用于需要本地 Xcode、本地模拟器、本地 Android SDK 或本地模拟器的场景，因为本技能要求所有构建和设备操作都在 Limrun 上运行。