Omi App Flutter 移动端开发实战本地后端 Harness、iOS/Android 构建与真机部署指南【免费下载链接】FriendAI that sees your screen, listens to your conversations and tells you what to do项目地址: https://gitcode.com/GitHub_Trending/fr/Friend本指南以仓库中 app/README.md 为骨架完整讲解 Omi AppFlutter 移动端伴生应用从零开始的本地开发链路如何启动仓库根目录提供的本地后端 harnessFirestore/Auth 模拟器 Python API如何通过setup.sh生成 iOS/Android 的原生工程配置如何以devflavor 运行应用以及如何构建可脱离电脑独立运行的 iPhone 真机包。读完本文你将能够独立完成本地模拟器 真机调试 beta 生产数据 profile 真机 AOT 部署的全流程搭建并理解OMI_*构建参数在启动期如何被校验、防误连生产。Omi App 是什么Flutter 伴生应用的仓库定位Omi App 是一个基于 Flutter 的移动端应用是 Omi 智能穿戴设备的伴生客户端承担三类职责与 Omi 设备交互、管理已安装的 apps、定制个人体验见 app/README.md 开篇描述。它位于仓库的app/目录下与backend/Python 后端、desktop/macOS/Windows 桌面端等模块并列。从 app/lib/flavors.dart 可以看到App 内部通过 flavor 区分运行环境Environment.prod与Environment.dev其中 dev 环境下应用标题显示为 Omi Dev。这意味着开发者的每一次本地构建都运行在开发身份之下与生产构建标题 Omi在运行时即可区分避免误用生产数据。环境准备设备与工具链前置条件README 明确要求在开始之前完成两项设备检查见 app/README.mdiPhone连接并解锁且在 iPhone 设置中开启Developer Mode开发者模式Android连接设备并在开发者选项中开启USB debuggingUSB 调试。除此之外setup.sh的文件头注释app/setup.sh列出了完整工具链版本要求构建脚本会在启动时主动检测版本并给出修复建议平台工具版本要求通用Flutter SDKv3.44.5通用Opus Codec任意稳定版iOSXcodev16.4iOSCocoaPodsv1.16.2iOSjq用于选择 iOS 构建目标AndroidAndroid StudioIguana / 2024.3AndroidAndroid SDK PlatformAPI 36AndroidJDKv21AndroidGradlev8.10AndroidNDK28.2.13676358值得说明的是iOS 侧的版本检查check_ios_prerequisitesapp/setup.sh 中_version_at_least与check_ios_prerequisites函数不仅检查命令是否存在还会解析xcodebuild -version输出若 xcodebuild 在 PATH 上却拿不到版本号脚本会提示许可未接受或组件缺失并给出sudo xcodebuild -license accept sudo xcodebuild -runFirstLaunch的修复命令——这正是为了避免工具存在但不可用时在构建深处才暴露的迷惑性报错。第一步启动本地后端 Harness必须最先执行README 特别强调setup.sh只负责构建 App不会启动后端。如果不先启动本地 harnessApp 启动后将无物可连。因此本地开发的正确顺序是先在仓库根目录启动后端。make dev-init # 一次性创建 backend/.venv 并复制环境模板 make dev-up # 启动 Firestore Auth 模拟器与 :8000 端口上的 Python API # 没有 Provider API Key使用离线假 Provider PROVIDER_MODEoffline make dev-up对应 Makefile 定义Makefile 中dev-init、dev-up目标make dev-init执行scripts/dev-harness/dev-init.sh创建backend/.venv基于当前python3解析到的解释器并复制环境模板后端要求 Python 3.11不能使用 3.12make dev-up执行scripts/dev-harness/dev-up.sh同时拉起 Firestore 模拟器、Auth 模拟器与 Python APIharness 还需要 Java 运行时以及firebase-tools/npx缺失时make dev-up会明确列出缺失项make dev-status查看已启动的服务端点、Provider 模式与已播种用户make dev-down停止 harness 全部进程。Harness 注入的默认端口与项目配置记录在 backend/docs/runbooks/local-emulator-manual-qa.mdREADME 内链接已转换为仓库根路径服务地址Firebase 项目demo-omi-localFirestore 模拟器127.0.0.1:8085Auth 模拟器127.0.0.1:9099Redis127.0.0.1:6380Python APIhttp://127.0.0.1:8000Rust 桌面 APIhttp://127.0.0.1:10201同时该 runbook 给出了已播种的本地测试用户供 App 登录调试使用ProfileEmail密码alice默认alicelocal.omi.invalidalice-local-password-030bobboblocal.omi.invalidbob-local-password-030local_default_userlocal_default_userlocal.omi.invalidlocal_default_user-local-password-030runbook 还提到PROVIDER_MODEoffline模式用于做不依赖真实 LLM/STT Provider 的调试离线模式下所有 provider 调用由假实现接管make dev-status会显示当前 Provider 模式。第二步运行 App 侧设置脚本后端就绪后进入 App 目录并运行对应平台的设置脚本app/README.mdcd app# macOS/LinuxiOS bash setup.sh ios # macOS/LinuxAndroid bash setup.sh android# Windows PowerShellAndroid .\setup\scripts\setup.ps1 androidbash setup.sh ios是安全的本地开发路径它使用本地 API/模拟器 harness 与demo-omi-localFirebase 项目。iOS 设置依赖 macOS/Xcode因此 Windows 开发者应使用 Android 路径。真机调试必须设置 OMI_DEV_HOST若目标是真实 iPhoneREADME 强调在先后执行setup.sh ios与make dev-up之前先导出OMI_DEV_HOST为 Mac 的局域网LAN或 Tailscale 地址——注意要export让两个命令都能看到该变量因为 harness 现在也会绑定到该地址而不仅仅是 App 构建时使用export OMI_DEV_HOST192.168.x.x # 或 Tailscale 地址背后的原因在 app/setup.sh 中可找到源码佐证LOCAL_DEV_HOST${OMI_DEV_HOST:-127.0.0.1}若未设置该变量dev 后端地址默认是127.0.0.1——在真机上这是设备自己而不是开发 MacApp 会一直卡在等待后端响应。Android 模拟器则使用10.0.2.2作为默认宿主地址ANDROID_DEV_HOST${OMI_ANDROID_DEV_HOST:-${OMI_DEV_HOST:-10.0.2.2}}这是 Android 模拟器访问宿主机的标准回环地址。拉取签名证书配置 SSH第 4 步是确保 GitHub SSH 访问配置正确用于从证书仓库拉取 iOS 签名证书app/README.mdcd ~/.ssh; ssh-add如果提示输入 passphrase输入 SSH 私钥口令若未设置过口令则直接回车。第三步运行 App设置完成后在 App 目录下运行flutter run --flavor dev这条命令会以devflavor 启动应用。devflavor 对应的构建 profile 是local_dev其默认 API 地址为http://127.0.0.1:8000/Firebase 项目为demo-omi-local并启用 Firebase Auth 模拟器。完整的 profile 定义在 app/lib/env/environment_profile.dartProfile名称默认 API 地址Firebase 项目Auth 回调 scheme使用 Auth 模拟器允许生产数据local_devlocal_devhttp://127.0.0.1:8000/demo-omi-localomi-dev是否local_prodlocal_prodhttp://127.0.0.1:8000/based-hardwareomi否是mobile_betamobile_betahttps://api.omiapi.com/based-hardwareomi-beta否是productionproductionhttps://api.omi.me/based-hardwareomi否是profile 由构建期--dart-defineOMI_APP_PROFILE...注入运行时通过AppEnvironmentProfile.forFlavor解析app/lib/env/environment_profile.dart并在启动期通过validateProfilePairing强制约束local_dev只能配 dev flavor、prod flavor 不能用local_dev防止误配导致访问错误的数据平面。Mobile Beta / Dogfood显式的生产数据构建Mobile beta 是一种明确的生产数据 profile它使用生产 Firebase 项目与用户 ID但将服务流量路由到https://api.omiapi.com/与 macOS beta 的 serving 平面保持一致app/README.md。export FIREBASE_SERVICE_ACCOUNT_KEY/secure/path/to/firebase-service-account.json bash setup.sh ios beta # Android beta 复用现有 prod flavor 与包名 bash setup.sh android beta注意事项README 原文要点结合 setup.sh 源码Firebase 服务账号必须能生成生产移动端配置setup_firebase_with_service_account_ios/androidapp/setup.sh会调用flutterfire config指定--service-account与--projectbased-hardwarebeta bundle ID 必须同时在 Firebase 与 Apple 团队注册默认 ID 为com.friend-app-with-wearable.ios12.betaAndroid 侧为com.friend.ios团队使用不同注册 ID 时可用OMI_MOBILE_BETA_BUNDLE_ID覆盖beta 构建使用mobile_betaprofile 与omi-beta://auth/callback回调 scheme产品流量走 beta serving API而Google 与 Apple OAuth 仍留在https://api.omi.me/对应 app/lib/env/env.dart 中authApiBaseUrl的逻辑mobileBeta profile 下认证平面固定为生产地址beta绝不能被当作本地模拟器构建对待。构建并部署到 iPhone脱离电脑独立运行快捷路径AOT 构建模式OMI_MOBILE_BUILD_MODEprofile bash setup.sh ios # 或 release普通的bash setup.sh ios安装的是 debugJIT构建iOS 只允许它在flutter run附着时运行从主屏幕直接打开会显示一段引擎不可用提示而非启动。而profile/release是 AOT 构建可独立启动代价是失去热重载。这条规则在 app/setup.sh 的mobile_build_mode_flag函数中有精确注释iOS 14 只允许 Flutter 工具链在物理设备上启动 JIT Dart VMdebug 构建下FlutterEngine init返回 nil、storyboard 的FlutterViewController没有 engine、第一个 Swift 插件会因 nil registrar 而崩溃——这正是flutter run下一切正常、主屏幕打开即死症状的根因。mobile_build_mode_flag支持debug/profile/release三值其他值直接报错退出。手动等价命令更细粒度控制在正常 setup 已生成 iOS/Firebase 文件之后可以手动复现构建app/README.mdsource setup.sh setup_app_env local_dev $LOCAL_API_BASE_URL scripts/validate_mobile_build_config.sh --flavor dev --profile local_dev flutter build ios --flavor dev --release \ --dart-defineOMI_APP_PROFILElocal_dev \ --dart-defineOMI_API_BASE_URL$LOCAL_API_BASE_URL \ --dart-defineOMI_FIREBASE_AUTH_EMULATOR_HOST$LOCAL_DEV_HOST产物位于build/ios/iphoneos/Runner.app其中scripts/validate_mobile_build_config.shapp/scripts/validate_mobile_build_config.sh负责构建前校验devflavor 必须搭配local_devprofile、prod必须搭配mobile_beta并检查对应 env 文件dev 用.dev.env、prod 用.env必须存在且包含USE_WEB_AUTHtrue与USE_AUTH_CUSTOM_TOKENtrue。setup 脚本在每次构建前都会执行该校验prepare_mobile_build_env确保flavor-profile-env 三者的配对始终一致。直接安装到真机ios-deploy --bundle build/ios/iphoneos/Runner.app --debug该命令会把.appbundle 直接安装到已连接的 iPhone安装完成后应用即可脱离开发机独立运行。原理深挖构建参数如何在启动期防止误连生产OMI_API_BASE_URL、OMI_FIREBASE_AUTH_EMULATOR_HOST等--dart-define参数在 app/lib/env/env.dart 中通过String.fromEnvironment读取。其中apiBaseUrl的解析优先级为运行时 override测试用OMI_API_BASE_URL编译期定义 运行时配置 profile 默认值。更关键的是启动期路由校验validateStartupRoutingapp/lib/env/env.dart它保证一个构建无法悄悄连到错误的服务平面local_devprofile要求 API 必须是回环或私有网段地址。_isLocalDevelopmentApi不仅放行localhost/host.docker.internal/::1还精确识别 RFC 1918 私网10.0.0.0/8、172.16.0.0/12、192.168.0.0/16以及RFC 6598 共享地址段100.64.0.0/10——注释说明这是 Tailscale 分配的网段物理真机无法使用127.x普通局域网地址又不可达时Tailscale 是唯一通路因此被有意纳入白名单且严格限定真正的 /10 范围100.63.x与100.128.x属于公网不放行local_prodprofile只允许 debug 构建使用且必须是合法 http(s) 端点production/mobile_beta要求 API 地址与 profile 默认值完全一致https://api.omi.me//https://api.omiapi.com/否则抛错。同时validateFirebaseProject会核对初始化时的 Firebase 项目 ID 是否与 profile 声明一致如local_dev必须匹配demo-omi-local。这套编译期注入 启动期强制校验的机制配合 app/scripts/validate_mobile_build_config.sh 的构建期校验构成双重防线任何配置漂移都会在应用联网前以明确错误而非静默行为异常暴露出来正如 app/lib/startup_failure_app.dart 注释所言——OMI_API_BASE_URL的错误应当呈现为精确、可操作的提示而不是空白启动页。常见问题速查现象原因与对策App 启动后一直等待、无响应后端 harness 未启动先执行make dev-init与make dev-up真机上 App 连不上后端未设置OMI_DEV_HOST默认127.0.0.1在真机上是设备自身export 后再跑setup.sh ios与make dev-up主屏幕打开 App 显示引擎不可用提示安装的是 debug/JIT 构建改用OMI_MOBILE_BUILD_MODEprofile bash setup.sh iosmake dev-up报缺失组件缺少 Java 运行时或firebase-tools/npx按输出安装即可后端 venv 构建失败后端要求 Python 3.113.12 不受支持确认python3解析到的版本构建时校验报 flavor/profile 不匹配运行scripts/validate_mobile_build_config.sh --flavor dev --profile local_dev自查 env 文件与 dart-define 配对总结Omi App 的本地开发链路是一条先 harness、后 setup、再 run的固定管线make dev-init/dev-up提供模拟器与 APIbash setup.sh ios|android完成 Firebase 配置、原生工程文件与签名准备flutter run --flavor dev进入开发循环OMI_MOBILE_BUILD_MODEprofile与ios-deploy完成真机独立部署。贯穿始终的是 profile 机制对数据平面的严格隔离——local_dev、mobile_beta、production三套身份从构建期到启动期逐层校验既保障日常开发的敏捷也守住生产数据的边界。如需更深入的 harness 细节端口、种子用户、离线 Provider、make dev-desktop桌面联调可继续阅读 backend/docs/runbooks/local-emulator-manual-qa.md 与 Makefile。【免费下载链接】FriendAI that sees your screen, listens to your conversations and tells you what to do项目地址: https://gitcode.com/GitHub_Trending/fr/Friend创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考