安装
让 Kotlin Android 模板在模拟器或设备上完成构建并运行。
本指南会带你从全新 clone 走到在 Android Studio 或 Gradle 命令行中运行应用。
应用设计为 没有任何服务 key 也能构建和启动。等本地跑起来以后，再逐步添加 Supabase、RevenueCat、FCM、PostHog、Sentry、Play 发布签名和 App Links 配置。
前置要求
- Android Studio Meerkat 或更新版本。 模板使用 AGP 9.2.1、 Kotlin 2.3.0、KSP 2.3.9 和 Gradle wrapper 9.4.1。
- JDK 17+。 除非你已经固定了本地工具链，否则直接使用 Android Studio 自带的 JDK。
- API 26+ 模拟器或 Android 设备。 推荐使用带 Play services 的模拟器镜像， 因为 FCM、Play In-App Updates、Play In-App Review 和购买测试依赖 Google Play services。
- Google Play 开发者账号 只在测试真实 Play Billing 或准备 Play 发布时需要。
设置
克隆模板
git clone <repo-url>
cd soar-kotlin在 Android Studio 中打开
打开仓库根目录，而不是只打开 app/ 文件夹。等待 Gradle 同步完成，以便 Android
Studio 解析 Compose、Hilt、Supabase、Firebase、RevenueCat、PostHog、Sentry
和 Play Core 依赖。
可选：填写 local.properties
Android Studio 通常会自动创建 sdk.dir。第一次运行时，服务 key 都是可选的：
sdk.dir=/path/to/Android/sdk
SUPABASE_URL=https://your-project-ref.supabase.co
SUPABASE_PUBLISHABLE_KEY=your_publishable_key
GOOGLE_WEB_CLIENT_ID=your_google_oauth_web_client_id
REVENUECAT_ANDROID_KEY=your_public_revenuecat_android_key缺失的字符串 key 会被读取为空 BuildConfig 值。完整 key 参考见
配置。
运行应用
选择 app 运行配置和一个模拟器或设备，然后点击 Run。即使没有后端 key，
应用也能进入 onboarding / consent / login 流程，本地 Component 图库可以离线渲染。
命令行等价命令
模板的 Gradle 命令如下：
# Debug 构建
./gradlew assembleDebug
# 安装到已连接的模拟器或设备
./gradlew installDebug
# 单元测试
./gradlew testDebugUnitTest
# 仪器测试；需要连接模拟器或设备
./gradlew connectedDebugAndroidTest
# debug 变体的 Android lint
./gradlew lintDebug
# Release App Bundle；签名 key 从 local.properties 读取
./gradlew bundleRelease从命令行启动已安装的 debug 构建：
adb shell am start -n com.soarstarter.kotlin/.MainActivity验证安装
在没有配置服务 key 的情况下，先确认应用能走过本地启动界面：
- 应用可以安装并启动，不崩溃。
- Onboarding 出现并可以完成。
- 法律同意门禁出现并可以接受。
- 登录界面正常渲染。
GOOGLE_WEB_CLIENT_ID设置前，Google 按钮会隐藏。 - Component 标签页可离线使用，因为它渲染的是本地 Compose demo。
Auth、todos、profile、uploads、subscriptions 和 push 都需要后端设置。应用本地启动后， 继续阅读 Supabase 设置。
常见首次运行问题
| 现象 | 可能原因 | 修复 |
|---|---|---|
| Gradle sync 找不到 AGP 或 Kotlin 插件 | Android Studio 过旧或 Gradle 缓存陈旧 | 更新 Android Studio，并从项目根目录重新同步 |
JAVA_HOME / toolchain 报错 | JDK 低于 17 或 Android Studio 使用了错误 JDK | 将 Gradle 指向 Android Studio 自带的 JDK 17+ |
缺少 sdk.dir | local.properties 尚未创建 | 用 Android Studio 打开一次项目，或添加 sdk.dir=/path/to/Android/sdk |
| FCM、更新、评价或 Billing 在模拟器上不可用 | 模拟器镜像缺少 Play services，或应用不是通过 Play 安装 | 使用带 Play services 的镜像；真实购买和更新流程需要 Play 分发 |
| Google 登录按钮不存在 | GOOGLE_WEB_CLIENT_ID 为空 | 在 local.properties 添加 OAuth web client ID，并在 Supabase 配置 Google provider |
| KSP / Kotlin 依赖不匹配 | 版本被独立修改 | 保持模板版本一起升级：Kotlin 2.3.0、KSP 2.3.9、supabase-kt 3.2.6、Ktor 3.3.1 |