安装
安装依赖，并在 iOS、Android、Web 或 Expo Go 中运行 Expo 应用。
这篇指南会带你从一份新的 soar-expo 克隆开始，运行到 Expo dev server。
前置条件
- Node.js LTS — 使用 active LTS 版本。
- pnpm — 模板固定为
packageManager: pnpm@10.32.1。 - Xcode — 只有 iOS simulator 和本地 iOS 原生构建需要，且仅限 macOS。
- Android Studio — 只有 Android emulator 和本地 Android 原生构建需要。
- Expo Go 或 Web — 适合第一眼预览，但要注意 Native-only 限制。
开始时不需要装齐所有原生工具链。pnpm web 可以在浏览器运行，Expo Go 可以
在真机预览。购买、原生 Google Sign-In、部分通知行为以及 config-plugin 变化
需要 development build。
设置
克隆模板
git clone <repo-url> soar-expo
cd soar-expo创建本地环境文件
cp .env.example .env.local先设置 Supabase 这一对值：
EXPO_PUBLIC_SUPABASE_URL=https://your-project-ref.supabase.co
EXPO_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_keySupabase client 会在模块加载时创建，所以应用需要这两个值。RevenueCat、Google、 PostHog、Sentry、链接和更新策略 key 可以先留空，等验证 shell 后再配置。
启动 Expo dev server
pnpm dev脚本会运行 expo start -c -p 3000，清 Metro cache 并使用 3000 端口。在 Expo
终端中按：
i打开 iOS simulator。a打开 Android emulator。w打开 Web build。
也可以用 Expo Go 扫描二维码进行真机预览。
Development build 与 Expo Go
Expo Go 很适合快速检查 UI，但它不包含这个 starter 使用的所有原生模块。需要真实 原生运行时时，创建 development build：
eas build --profile development --platform ios
eas build --profile development --platform android| 界面/能力 | Expo Go / Web 预览 | Development build |
|---|---|---|
| Home、Component、Showcase、i18n、theming | 可用于 UI 检查 | 可用 |
| 邮箱认证、todos、profile 读写 | 配置 Supabase 后可用 | 可用 |
| RevenueCat purchases | Web 不可用；Expo Go 不是目标运行时 | 需要 |
| 原生 Google Sign-In | Web no-op；Expo Go 不是目标运行时 | 需要 |
| Apple Sign-In | 仅 iOS 原生 | 需要 |
| Push token 和通知行为 | 依赖真机；只能粗略检查 | 推荐 |
| Config-plugin 变化 | 不会体现 | 需要重建 |
更多 profiles、channels 和 OTA update 设置见 EAS 构建。
验证安装
添加可选服务前，先检查这些点：
- Dev server 启动时没有 Metro 错误。
- Onboarding 首次启动出现，完成后消失。
- Legal consent modal 会在 bundled legal screens 之外出现。
- Login screen 可以从抽屉或需要登录的门禁打开。
- Component tab 未登录可渲染，不依赖网络。
- Home / Showcase / Me 可渲染，需要登录的行会拉起登录而不是崩溃。
- Supabase-backed features 在配置 Supabase project 并应用 migrations 后， 可以登录并持久化数据。
常用脚本
| 命令 | 作用 |
|---|---|
pnpm dev | expo start -c -p 3000；按 i、a 或 w |
pnpm dev:preview | 使用 APP_VARIANT=preview 启动 Metro |
pnpm dev:prod | 使用 APP_VARIANT=production 启动 Metro |
pnpm ios | 清 cache 并打开 iOS simulator |
pnpm android | 清 cache 并打开 Android emulator |
pnpm web | 清 cache 并打开 Web build |
pnpm typecheck | 运行 tsc --noEmit |
pnpm lint | 运行 expo lint |
pnpm format | 用 Prettier 格式化 TS、TSX、JS、JSON、CSS 和 Markdown |
pnpm gen:types | 从 Supabase 生成 types/database.ts；需要 SUPABASE_PROJECT_ID |
pnpm clean | 删除 .expo 和 node_modules |
常见首次运行问题
| 现象 | 常见原因 | 修复 |
|---|---|---|
Missing Supabase environment variables. | 缺少 EXPO_PUBLIC_SUPABASE_URL 或 EXPO_PUBLIC_SUPABASE_ANON_KEY | 复制 .env.example 到 .env.local 并填写两者 |
3000 端口被占用 | 另一个 dev server 正在运行 | 停掉它，或让 Expo 使用其他端口 |
| Simulator 无法打开 | Xcode command-line tools 或 simulator runtime 缺失 | 安装 Xcode，打开一次，并安装 iOS simulator |
| Android emulator 无法打开 | Android SDK / emulator 未配置 | 安装 Android Studio，创建 emulator，并检查 JAVA_HOME / SDK path |
| 路由、资源或原生模块状态陈旧 | Metro cache | pnpm dev 已经传 -c；改 env 或 native config 后重启 |
| Watchman 警告 | 本地文件 watcher 状态 | 重启 Watchman 或清理 watches |
| Purchases 或 Google Sign-In 不可用 | 正在 Expo Go/Web 中运行，或缺少 key | 使用 development build，并配置相关 public key |