SuperAPI AI 工具集

build-mobile-app

编程与开发

查看项目

更新于 11-03 23:38

技能介绍

用途

build-mobile-app 用于构建并运行 Opensteer 自定义 Expo 客户端,目标环境是自有模拟器或设备,也覆盖 mock 模式。应用必须使用自定义 dev client:它注册了 com.opensteer.mobile scheme,OAuth 回调会返回到该 scheme,Expo Go 无法做到这一点。构建自定义客户端还会从 app.config.ts 生成 ios/ 和 android/ 目录,这两个目录都不纳入版本跟踪。

主要能力

  • 在 iOS 设备或模拟器上构建并运行移动客户端。
  • 在 Android 上构建并运行移动客户端。
  • 通过 Release 配置查看接近发布形态的应用。
  • 使用 EXPO_PUBLIC_OPENSTEER_MOCK=1 让所有界面针对 @opensteer/client/mock 中的内存 Host 运行,无需登录任何部署。
  • 使用 EXPO_PUBLIC_OPENSTEER_MOCK_HOME=absent 在没有 Chat 的情况下启动 mock Host,用于验证首条消息界面。
  • 通过 expo export 检查 Metro 依赖图能否解析,而无需进行原生构建。

使用方式

iOS 运行命令:

pnpm --filter @opensteer/mobile exec expo run:ios --device "iPhone 17 Pro"

Android 运行命令:

pnpm --filter @opensteer/mobile exec expo run:android

加 --configuration Release 可查看应用发布时的样子;Debug 构建会运行开发覆盖层和 Metro 自身计时,人实际拿到的不是这些。

Mock 模式:

EXPO_PUBLIC_OPENSTEER_MOCK=1 让每个界面针对 @opensteer/client/mock 的内存 Host 运行,无需登录部署。该变量在构建时读取,因此必须设置在 run:ios / run:android 命令上,不能事后设置。mock 模式会把认证、Host 和通知注册替换为模拟,所以非开发构建会拒绝运行它:应用会显示“this build cannot run”的普通消息,而不是运行模拟产品。只有两个打包期字面量能打开这扇门:Metro 的 DEV(在开发 bundle 中为 true),以及构建命令设置的 EXPO_PUBLIC_OPENSTEER_BUILD_PROFILE=development|preview。Release 原生构建的 DEV 为 false,因此要以发布形态查看 mock 模式,需要设置 profile:

EXPO_PUBLIC_OPENSTEER_BUILD_PROFILE=development EXPO_PUBLIC_OPENSTEER_MOCK=1
pnpm --filter @opensteer/mobile exec expo run:ios --configuration Release --device "iPhone 17 Pro"

不要在除开发者外的任何人会安装的构建上设置 EXPO_PUBLIC_OPENSTEER_BUILD_PROFILE。

EXPO_PUBLIC_OPENSTEER_MOCK_HOME=absent 会在没有 Chat 的情况下启动 mock Host,以验证首条消息界面。mock 中的其他内容保持不变,因此它测试的是没有 Home 的 Deployment,而不是空的 Deployment。在其中创建的 Chat 会在应用重新启动前一直存在,因为 mock Host 位于内存中;未发送的草稿像其他草稿一样保存在手机上。它不能证明真实服务器上的任何行为。

EXPO_PUBLIC_OPENSTEER_BUILD_PROFILE=development EXPO_PUBLIC_OPENSTEER_MOCK=1
EXPO_PUBLIC_OPENSTEER_MOCK_HOME=absent
pnpm --filter @opensteer/mobile exec expo run:ios --configuration Release --device "iPhone 17 Pro"

检查 Metro 依赖图能否解析而不进行原生构建:

pnpm --filter @opensteer/mobile exec expo export --platform ios --output-dir /tmp/mobile-export-ios

环境与平台要求

  • 设置 LANG=en_US.UTF-8(或其他 UTF-8 locale)。
  • 让 xcode-select 指向完整的 Xcode,而不是 Command Line Tools。
  • 在 iOS Simulator 中,Mac 回环地址可访问 http://localhost:43100 上的 pnpm dev;没有 Account 服务就没有推送。
  • 仅在 docs/testing.md 中保留的 VM/设备工作流中运行 GUI 工作。
  • 检查结束后停止 Metro、服务器和自有设备。
  • iPhone Duo 支持需要 Xcode 27.1 和 iOS 27.1 运行时。Expo 生成的 scene 生命周期负责启动和链接;配置保持单 scene。

Android 推送需要私有 prebuild 文件:

OPENSTEER_MOBILE_GOOGLE_SERVICES_FILE=/absolute/path/google-services.json
pnpm --filter @opensteer/mobile exec expo run:android pnpm --filter @opensteer/mobile exec expo config --type introspect

永远不要提交该文件。推送送达限制见 docs/mobile.md#6-notifications。

适用场景

  • 在自有模拟器或设备上验证 Opensteer 移动客户端的构建与运行。
  • 在无需真实部署登录的情况下,用 mock 模式检查界面与流程。
  • 检查首条消息等特定界面状态(通过 MOCK_HOME=absent)。
  • 在原生构建前快速检查 Metro 依赖图解析。

限制

  • 仅构建和导出检查不能证明折叠、原生 OAuth 或通知送达合格。
  • mock 模式仅能在开发或受支持的 preview profile 下运行,Release 构建默认拒绝。
  • mock Host 位于内存中,创建的 Chat 在应用重启后消失;不能验证真实服务器行为。
  • 不应在非开发者安装的构建上设置 EXPO_PUBLIC_OPENSTEER_BUILD_PROFILE。
  • Android 推送需要私有 google-services.json,不得提交。