企业官网建设流程全解析

Omi Flutter App 开发环境怎么搭：make dev-up 本地 harness 加 setup.sh 首次跑通

【免费下载链接】FriendAI that sees your screen, listens to your conversations and tells you what to do项目地址: https://gitcode.com/GitHub_Trending/fr/Friend

你要完成的任务是：在本机把 Omi 的 Flutter 移动应用（iOS 或 Android）以devflavor 构建起来，并让它连上本仓库自带的本地后端 harness（Python API + Firebase Auth/Firestore 模拟器），完成首次跑通。整条路径全程在本地机器上运行，不触碰任何生产数据。官方推荐路径是 docs/doc/developer/AppSetup.mdx 中的 "Build the App Automatically"：一条make dev-up起服务，再进app/目录跑setup.sh。

准备条件

按 AppSetup 文档列出的前置依赖：

用flutter doctor -v检查工具链，文档给出的示例输出（文档示例，仅作参照）：

[✓] Flutter (Channel stable, 3.44.5, on macOS 15.4.1) [✓] Android toolchain - develop for Android devices (Android SDK version 36.0.0) [✓] Xcode - develop for iOS and macOS (Xcode 16.4) [✓] Chrome - develop for the web [✓] Android Studio (version 2025.1) [✓] VS Code (version 1.101.0) [✓] Connected device (4 available) [✓] Network resources

harness 缺 Python 3.11、Java 或 firebase-tools 时，make dev-up会把缺少的项直接点名报出来。

第一步：启动本地后端 harness

在仓库根目录执行（Makefile 中这些 target 分别转发到scripts/dev-harness/下的脚本）：

make dev-init # 一次性：创建 backend/.venv，并复制 backend/.env.local-dev.template 为 backend/.env.local-dev make dev-up # 启动 Firestore + Auth 模拟器和 Python API

两点注意：

• make dev-init会用当前python3解析到的解释器构建backend/.venv，所以先确认它解析到的是 Python 3.11，否则 harness 稍后会以 import 错误失败。
• 如果你有 OpenAI / Deepgram / Gemini / Anthropic 的 API key，把它们写进backend/.env.local-dev（dev-init已从模板复制出来）。没有 key 也可以用离线假 provider 起步：

PROVIDER_MODE=offline make dev-up

harness 注入的固定端点（见 local-emulator-manual-qa.md，这些是 harness 内部值，不要写进.env.local-dev，写了也会被忽略）：

第二步：验证 harness 已就绪

make dev-status # 输出各端点、provider 模式、已 seed 的本地用户

harness 会 seed 本地用户，runbook 列出的有：

确认端点都在监听后，再进行下一步；不用的时候用make dev-down停止 harness 进程。

第三步：用 setup.sh 构建并运行 App

setup.sh本身不启动任何后端服务——必须先完成第一步，否则 App 能构建、能启动，但每个请求都连不上。

进入 App 目录并按平台执行（app/setup.sh 会依次完成：写入.dev.env并指向http://127.0.0.1:8000/、安装demo-omi-local的本地 Firebase 模拟器配置、flutter pub get、iOS 侧pod install、dart run build_runner build，最后直接flutter run）：

cd app bash setup.sh ios # iOS # 或 bash setup.sh android # Android

脚本内置了版本检查（如check_ios_prerequisites会检查 Flutter ≥ 3.44.5、Xcode 可用且 ≥ 16.4、CocoaPods ≥ 1.16.2、jq），缺什么会列出缺失项和修复命令，而不是在构建深处报一个莫名错误。

也可以不走setup.sh的最后一步，改为手动运行：

flutter run --flavor dev

或在 IDE 中运行：Xcode 打开app/ios，Android Studio 打开app/android，然后按 run。

结果验证

• make dev-status显示端点、provider 模式与 seed 用户正常（可选make dev-summary看会话摘要）。
• flutter run把 App 装到模拟器上：iOS 模拟器用127.0.0.1寻址本地服务，Android 模拟器默认走10.0.2.2（emulator 的 host 别名）。
• 如果 App 能连上 harness，用上面表格里的 seed 账号（如alice）即可在本地环境登录。

常见失败与排查

App 连不上后端（connection refused / 超时）：setup.sh构建的 App 指向http://127.0.0.1:8000但它不启动任何进程。确认已在仓库根目录先跑make dev-up，再用make dev-status核实。真机上127.0.0.1是手机自己，需要把OMI_DEV_HOST设成 Mac 的局域网或 Tailscale 地址（只接受私有地址，如192.168.x.x、100.x.x.x），并且要在同一个 shell里让setup.sh和make dev-up都看到它——前者决定 App 编译时指向哪，后者让 harness 真正监听在那个地址（默认只监听 loopback）。只想让 harness 绑定与 App 不同地址时，用OMI_DEV_BIND_HOST。

登录成功但所有请求返回 401 Unauthorized：App 和后端不在同一个 Firebase 项目上。Firebase ID token 是项目范围的，demo-omi-local的 token 无法被其他项目的后端验证，所以登录看似成功、之后全部 401。不要把 dev 构建指向 Omi 共享的生产 API（https://api.omiapi.com/）——它按生产项目验证 token，本地模拟器签发的 token 一律被拒；要访问生产数据需要显式的beta构建（bash setup.sh ios beta，且需要FIREBASE_SERVICE_ACCOUNT_KEY），本文不展开该路径。

iOS 真机：flutter run挂着时能跑，从主屏打开就崩：debug 构建的 Dart VM 是 JIT 模式，iOS 只允许 Flutter 工具链在真机上启动 JIT VM，flutter run断开后 App 无法自启。解法之一是装 AOT 构建：

OMI_MOBILE_BUILD_MODE=profile bash setup.sh ios

profile（或 release）构建可以从主屏直接打开，代价是没有 hot reload；在flutter run里按d可以断开工具但保持 App 运行。setup.sh ios在 debug 构建要装到真机时会主动打警告。模拟器没有这个限制。

限制与收尾

• 这条路径整体跑在本机（本地 API、本地模拟器），是开发迭代最快的组合；它产出的行为只能算本地手动 QA 证据，不代表任何生产验证。
• 停止服务用make dev-down；需要清掉 harness 本地状态时用make dev-reset（只清 sentinel 拥有的本地状态，不删除真实外部 provider 侧保留的数据）。
• 想换自己的后端而非本地 harness，走 AppSetup 文档的 "Build the App Manually" 路径，自己维护.dev.env（API_BASE_URL记得带尾部/）和自己的 Firebase 配置，本文不覆盖。

【免费下载链接】FriendAI that sees your screen, listens to your conversations and tells you what to do项目地址: https://gitcode.com/GitHub_Trending/fr/Friend