Moonfin 开发环境搭建指南:Kotlin、Koin 依赖注入与 Jetpack Compose + Leanback 工程化实践
Moonfin 开发环境搭建指南:Kotlin、Koin 依赖注入与 Jetpack Compose + Leanback 工程化实践
Moonfin 是一个面向 Android TV 和 Fire TV 的 Jellyfin 媒体库客户端(工程内部名为 Moonfin-androidtv)。本文带你从零搭建它的开发环境:克隆仓库、配置 JDK 21、理解多模块结构,并搞清 Kotlin + Koin 依赖注入 + Jetpack Compose + Leanback 这套 TV 端工程化方案是如何协同工作的,适合刚接触 Android TV 开发的新手阅读。
一、项目速览:这是一个什么样的工程
Moonfin 在 settings.gradle.kts 中声明了 rootProject.name = "Moonfin-androidtv",应用包名为 org.moonfin.androidtv。它的核心特征是:
| 技术点 | 版本 | 说明 |
|---|---|---|
| Kotlin | 2.3.10 | 主开发语言 |
| Android Gradle Plugin | 9.0.0 | 构建系统 |
| Gradle | 9.3.1 | 由 Wrapper 锁定 |
| JDK | 21 | 由 .tools-versions 与根构建脚本约束 |
| compileSdk / minSdk | 36 / 23 | 覆盖绝大多数 TV 盒子 |
| Koin | 4.1.1 | 依赖注入 |
| Compose / Leanback | 1.10.2 / 1.2.0 | 混合 UI 方案 |
所有依赖版本集中在 gradle/libs.versions.toml(版本目录),改版本只动这一个文件即可。
二、搭建前准备:JDK 21 与环境检查
工程根目录的构建脚本通过 Java Toolchain 强制要求 JDK 21(libs.versions.java.jdk),版本号为 21。请按以下步骤检查环境:
- 安装 JDK 21,并在
JAVA_HOME中指向它; - 安装 Android Studio(Kotlin 版本较新的稳定版即可);
- 确认命令行可用:
java -version
💡 工程内置 Gradle Wrapper,不需要手动安装 Gradle,首次构建会自动下载 Gradle 9.3.1。
三、克隆仓库并导入工程
一行命令克隆仓库:
git clone https://gitcode.com/gh_mirrors/an/AndroidTV-FireTV
然后用 Android Studio 打开项目根目录,等待 Gradle Sync 完成。首次同步会下载依赖,时间较长属正常现象。
四、模块结构解析:多模块如何分工
打开 settings.gradle.kts 可以看到清晰的模块划分,这也是大型 Android 项目的典型实践:
- app:应用主入口,含 UI、DI 模块声明,见 app/build.gradle.kts
- design:设计令牌(颜色、字体、间距),如 design/src/main/kotlin/Tokens.kt
- server:core / jellyfin / emby:服务端 API 层,按协议拆分子模块
- playback:core / media3:exoplayer / session:基于 Media3 的播放器层
- preference:偏好设置存储
这种"按职责切模块"的结构,让 Jellyfin 与 Emby 两套协议可以复用同一套 UI 与播放能力,也是新手学习模块化组织的绝佳样本。
五、Koin 依赖注入:应用启动时发生了什么
Moonfin 使用 Koin 做依赖注入,入口在 app/src/main/java/org/jellyfin/androidtv/di/KoinInitializer.kt。它借助 AndroidX Startup 库,在应用启动阶段自动执行 startKoin,并按需装配 6 个功能模块:
modules(
androidModule,
appModule,
authModule,
playbackModule,
preferenceModule,
utilsModule,
)
每个模块对应 di/ 目录下一个文件,比如 AppModule.kt 负责注册 Repository、ViewModel 等核心服务。相比手动 new 对象或注解处理器,Koin 的声明式写法让"谁依赖谁"一目了然,也便于单元测试时替换实现。
六、Jetpack Compose 与 Leanback 的混合 UI
TV 端 UI 有个特殊点:焦点导航。Moonfin 的解法是双轨制:
- Leanback(
androidx.leanback):负责列表、网格等经典 TV 控件,例如 app/src/main/java/org/jellyfin/androidtv/ui/browsing/ 下的各类浏览页面,保证遥控器焦点体验; - Jetpack Compose:负责按钮、对话框、设置表单等组件化 UI,入口在 app/src/main/java/org/jellyfin/androidtv/ui/base/ 下(Button、Dialog、Form 等基础组件),并在 app/build.gradle.kts 中通过
compose = true开启。
两套体系并行,是 Android TV 应用"渐进迁移 Compose"的现实路径,值得在自研 TV 项目时参考。
七、构建、运行与调试:Flavor 与常用命令
双 Flavor:github 与 playstore
app/build.gradle.kts 定义了 distribution 维度下的两个 Flavor:github(启用 OTA 更新)和 playstore(上架版)。调试版应用会自动追加 .debug 包名后缀,可与正式版共存安装。
常用 Gradle 命令速查
# 构建 debug 安装包
./gradlew assembleGithubDebug
# 运行单元测试(JUnit5 + Kotest)
./gradlew test
# 静态检查(Detekt)
./gradlew detekt
切换 Jellyfin SDK 版本
gradle.properties 中的 sdk.version 支持 default、local、snapshot、unstable-snapshot 四种取值,可用命令行参数临时覆盖,例如跟踪 SDK 主干:
./gradlew assembleGithubDebug -Psdk.version=snapshot
八、发布签名与进阶配置
- 发布签名配置模板见 keystore.properties.template:复制为根目录
keystore.properties并填写四项密钥信息,release 构建才会自动签名; - Lint 规则集中在 android-lint.xml,代码风格由 detekt.yaml 约束,CI 中会并行执行两者;
- Moonfin 独有的功能清单(Jellyseerr 集成、工具栏自定义等)可参考 docs/FEATURES.md。
九、新手常见问题
Q:Sync 时报 JDK 版本错误? 确认 Android Studio 的 Gradle JDK 设为 21(Settings → Build Tools → Gradle),工程已配置 Toolchain 自动下载兜底。
Q:构建失败提示缺少 keystore.properties?
debug 构建不需要签名,直接构建 *Debug 任务即可;该文件只影响 release 签名。
Q:想在模拟器上跑? 选择支持 D-pad 的 TV 模拟器镜像(如 "Android TV" 映像),minSdk 23 的门槛很低,基本都能运行。
搭好环境只是第一步。建议接下来顺着 KoinInitializer → AppModule → 任意一个 Fragment 的阅读路径走一遍,把"依赖注入 + 模块化 + 混合 UI"这条主线串起来,你就具备了向 Moonfin 这类 Jellyfin TV 客户端贡献代码的完整基础。

