Moonfin 开发环境搭建指南:Kotlin、Koin 依赖注入与 Jetpack Compose + Leanback 工程化实践

原创2026-11-15 14:55:591,858 阅读

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 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。请按以下步骤检查环境:

  1. 安装 JDK 21,并在 JAVA_HOME 中指向它;
  2. 安装 Android Studio(Kotlin 版本较新的稳定版即可);
  3. 确认命令行可用:
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 的解法是双轨制:

两套体系并行,是 Android TV 应用"渐进迁移 Compose"的现实路径,值得在自研 TV 项目时参考。

Moonfin 播放器界面,展示视频播放控制与进度条

七、构建、运行与调试: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 客户端贡献代码的完整基础。

登录后查看全文
AndroidTV-FireTV