快速上手

相关源文件

本页面内容基于以下源文件生成：

• build.gradle
• app/build.gradle
• gradle.properties
• gradlew
• gradlew.bat
• starrysky/build.gradle
• starrysky/src/main/java/com/lzx/starrysky/SongInfo.kt
• starrysky/src/main/java/com/lzx/starrysky/StarrySky.kt
• starrysky/src/main/java/com/lzx/starrysky/AppLifecycleCallback.kt
• starrysky/src/main/java/com/lzx/starrysky/OnPlayerEventListener.kt

本项目是一个基于 Jetpack Compose 构建的 Android 新闻应用，集成了音乐播放功能模块。项目采用 Kotlin 语言开发，使用 Gradle 进行构建管理，支持 AndroidX 和 Jetifier 转换。

环境准备与项目配置

基础环境要求

项目需要 Java 运行环境支持。根据 Gradle Wrapper 脚本配置，系统会自动检测 JAVA_HOME 环境变量，若未设置则从系统 PATH 中查找 java 命令（gradlew:87-106）。

操作系统支持：

• macOS（Darwin）
• Windows（通过 gradlew.bat）
• Linux/Unix
• Cygwin/MSYS 环境

Gradle 环境配置

项目使用 Gradle Wrapper 确保构建环境一致性。Wrapper 脚本会自动设置 APP_HOME 变量并定位 gradle-wrapper.jar（gradlew:25-41）。

JVM 参数配置：

• 默认 JVM 选项：-Xmx64m -Xms64m（gradlew:47）
• 可通过 JAVA_OPTS 和 GRADLE_OPTS 环境变量传递额外 JVM 参数（gradlew:183）

AndroidX 与项目全局设置

项目启用了 AndroidX 支持库结构，并配置了自动转换第三方库的 Jetifier 功能（gradle.properties:17-19）。

关键配置项：

完整配置参见 gradle.properties:1-21。

依赖版本管理

Compose 与 Kotlin 版本定义

项目在根级 build.gradle 中定义了全局版本变量（build.gradle:3-5）：

groovy
1ext {
2    compose_version = '1.0.5'
3}

核心工具版本：

• Android Gradle Plugin: 7.0.0（build.gradle:12）
• Kotlin Gradle Plugin: 1.5.31（build.gradle:13）

远程仓库配置

项目配置了三个远程仓库源（build.gradle:6-10）：

groovy
1repositories {
2    google()
3    mavenCentral()
4    maven { url 'https://jitpack.io' }
5}

应用模块插件配置

应用模块使用了四个 Kotlin 相关插件（app/build.gradle:1-6）：

groovy
1plugins {
2    id 'com.android.application'
3    id 'kotlin-android'
4    id 'kotlin-kapt'
5    id 'kotlin-android-extensions'
6}

Compose 应用基础配置

SDK 版本设置

应用模块的 Android 配置块定义了编译和目标 SDK 版本（app/build.gradle:8-22）：

Compose 功能启用

项目在 buildFeatures 块中启用了 Compose 支持（app/build.gradle:47-49）：

groovy
1buildFeatures {
2    compose true
3}

Compose 编译器选项配置（app/build.gradle:50-53）：

groovy
1composeOptions {
2    kotlinCompilerExtensionVersion compose_version
3    kotlinCompilerVersion '1.4.32'
4}

编译选项与签名配置

Java 版本兼容性：JavaVersion.VERSION_1_8（app/build.gradle:39-42）

Kotlin JVM 目标：1.8，启用了 IR 编译器后端（app/build.gradle:43-46）

Release 签名配置（app/build.gradle:24-31）：

groovy
1signingConfigs {
2    release {
3        keyAlias 'composenews'
4        keyPassword 'fmt123456'
5        storeFile file('../news')
6        storePassword 'fmt123456'
7    }
8}

核心依赖声明

应用模块依赖了完整的 Jetpack Compose UI 组件栈（app/build.gradle:65-71）：

完整依赖列表参见 app/build.gradle:59-97。

模块化与音频库集成

StarrySky 音乐播放模块

项目包含一个独立的音乐播放库模块 starrysky，配置为 Android Library（starrysky/build.gradle:1-3）：

groovy
1apply plugin: 'com.android.library'
2apply plugin: 'kotlin-android'
3apply plugin: 'kotlin-android-extensions'

模块 SDK 配置（starrysky/build.gradle:5-18）：

ExoPlayer 依赖集成

StarrySky 模块使用 Google ExoPlayer 作为核心播放引擎（starrysky/build.gradle:40-45）：

groovy
1api "com.google.android.exoplayer:exoplayer-core:2.14.1"
2api "com.google.android.exoplayer:extension-mediasession:2.14.1"
3compileOnly ("com.google.android.exoplayer:exoplayer-dash:2.14.1")
4compileOnly ("com.google.android.exoplayer:exoplayer-hls:2.14.1")
5compileOnly ("com.google.android.exoplayer:exoplayer-smoothstreaming:2.14.1")
6compileOnly ("com.google.android.exoplayer:extension-rtmp:2.14.1")

应用模块通过项目依赖方式引入该库（app/build.gradle:77）：

groovy
1implementation project(path: ':starrysky')

SongInfo 数据模型

音频播放核心数据结构 SongInfo 定义了完整的歌曲信息模型（starrysky/src/main/java/com/lzx/starrysky/SongInfo.kt:11-21）：

kotlin
1@Parcelize
2class SongInfo(
3    var songId: String = "",       // 音乐ID
4    var songUrl: String = "",      // 音乐播放地址
5    var songName: String = "",     // 音乐标题
6    var artist: String = "",       // 作者
7    var songCover: String = "",    // 音乐封面
8    var duration: Long = -1,       // 音乐长度
9    var decode: Boolean = false,   // 是否需要解码
10    var headData: HashMap<String, String>? = hashMapOf() // header信息
11) : Parcelable, Cloneable

该类实现了 Parcelable 接口以支持跨进程传递，同时支持 Cloneable 克隆功能（starrysky/src/main/java/com/lzx/starrysky/SongInfo.kt:31-40）。

安装与构建步骤

克隆项目

bash
1git clone https://github.com/fmtjava/Jetpack_Compose_News.git
2cd Jetpack_Compose_News

环境检查

确认 Java 环境已正确配置：

bash
1# Linux/macOS
2./gradlew --version
3
4# Windows
5gradlew.bat --version

若出现 JAVA_HOME is not set 错误，需设置 JAVA_HOME 环境变量指向 JDK 安装目录（gradlew:95-98）。

构建项目

推荐路径：使用 Gradle Wrapper 构建

bash
1# Linux/macOS
2./gradlew clean build
3
4# Windows
5gradlew.bat clean build

clean 任务定义在根级构建文件中（build.gradle:19-21）：

groovy
1task clean(type: Delete) {
2    delete rootProject.buildDir
3}

构建输出位置（建议/常见做法，未在仓库证据中出现）**：

• APK 输出目录：app/build/outputs/apk/
• 调试版：app/build/outputs/apk/debug/app-debug.apk
• 发布版：app/build/outputs/apk/release/app-release.apk

Android Studio 导入

1. 打开 Android Studio
2. 选择 File > Open
3. 导航到项目根目录并选择 build.gradle 文件
4. 点击 Open as Project
5. 等待 Gradle 同步完成

运行验证

通过 ADB 安装验证

bash
1# 安装调试版 APK
2adb install app/build/outputs/apk/debug/app-debug.apk
3
4# 查看应用是否安装成功
5adb shell pm list packages | grep com.fmt.compose.myapplication

预期输出（建议/常见做法，未在仓库证据中出现）**：

package:com.fmt.compose.myapplication

应用启动验证

bash
1# 启动应用
2adb shell am start -n com.fmt.compose.myapplication/.MainActivity

构建成功标志

Gradle 构建成功后会显示：

BUILD SUCCESSFUL in Xs

若构建失败，检查以下常见问题。

常见问题与排错

问题 1：JAVA_HOME 未设置

错误信息：

ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.

原因：系统未配置 JAVA_HOME 环境变量（gradlew:102-105）

解决方案：

bash
1# Linux/macOS (Bash)
2export JAVA_HOME=/path/to/jdk
3export PATH=$JAVA_HOME/bin:$PATH
4
5# Windows (Command Prompt)
6set JAVA_HOME=C:\Program Files\Java\jdk-11
7set PATH=%JAVA_HOME%\bin;%PATH%
8
9# Windows (PowerShell)
10$env:JAVA_HOME = "C:\Program Files\Java\jdk-11"
11$env:Path = "$env:JAVA_HOME\bin;$env:Path"

问题 2：Compose 编译器版本不匹配

错误信息：

This version (1.0.5) of the Compose Compiler requires Kotlin version 1.5.31

原因：Kotlin 编译器版本与 Compose 编译器扩展版本不兼容

解决方案：确保 build.gradle 中的版本配置一致：

• Kotlin 插件版本：1.5.31（build.gradle:13）
• Compose 版本：1.0.5（build.gradle:4）

问题 3：Gradle 内存不足

错误信息：

Expiring Daemon because JVM heap space is exhausted

原因：Gradle 守护进程内存配置不足

解决方案：修改 gradle.properties 中的 JVM 参数（gradle.properties:9）：

properties
1# 增加堆内存大小
2org.gradle.jvmargs=-Xmx4096m -Dfile.encoding=UTF-8
3
4# 启用并行构建（可选）
5org.gradle.parallel=true

问题 4：依赖下载失败

错误信息：

Could not resolve all files for configuration ':app:debugCompileClasspath'.

原因：网络问题或仓库源访问受限

解决方案：配置国内镜像源（需要确认，未在仓库证据中出现）：

在 build.gradle 的 repositories 块中添加阿里云镜像：

groovy
1repositories {
2    maven { url 'https://maven.aliyun.com/repository/google' }
3    maven { url 'https://maven.aliyun.com/repository/public' }
4    google()
5    mavenCentral()
6    maven { url 'https://jitpack.io' }
7}

问题 5：Kotlin Android Extensions 过时警告

错误信息：

'kotlin-android-extensions' Gradle plugin is deprecated

原因：插件已被标记为过时

解决方案：考虑迁移到 ViewBinding（需要确认，未在仓库证据中出现）。当前项目仍使用该插件（app/build.gradle:5），但在 Compose 项目中影响较小。

下一步建议

完成环境配置和项目构建后，建议继续探索以下内容：

1. UI 组件结构：查看 app 模块中的 Compose UI 实现，了解 Material Design 组件的使用方式
2. 音乐播放集成：研究 starrysky 模块的 SongInfo 数据模型和播放器 API
3. 网络请求层：分析 Retrofit 和 OkHttp 的配置与使用（app/build.gradle:87-89）
4. 图片加载：了解 Coil Compose 的图片加载实现（app/build.gradle:74）

详细使用指南请参考项目的其他技术文档章节。