第2章 项目搭建与依赖配置
2.1 本章目标与前置知识
本章将引导你从零搭建一个完整的 Compose 支付演示项目，按照生产级应用的依赖管理标准，依次添加 Material3 主题库、Navigation 导航组件以及 Coil 图片加载库。完成本章后，你的开发环境将具备支持 State Hoisting 所需的全部基础设施。
- 目标项目结构：单一 Module App，基于 Gradle + Kotlin DSL
- 核心依赖：androidx.compose.material3、androidx.navigation.compose、io.coil-kt.coil-compose
- 版本管理：统一使用 BOM (Bill of Materials) 避免版本冲突
2.2 创建 Compose 项目
使用 Android Studio (Arctic Fox 或更高版本) 创建新项目时，选择 Empty Compose Activity 模板。项目创建后，自动生成如下关键文件：
| 文件/目录 | 作用 |
|---|---|
app/build.gradle.kts |
模块级构建脚本，存放依赖声明 |
build.gradle.kts |
项目级构建脚本，用于声明全局 BOM 与插件 |
settings.gradle.kts |
项目模块注册与仓库配置 |
MainActivity.kt |
默认的 Compose Activity 入口 |
ui/theme/ |
Material3 主题文件（可后续替换） |
2.3 添加 Material3 库
Material3 是 Google 推荐的 Material Design 最新实现，通过 BOM 统一管理 Compose 所有库的版本。在 app/build.gradle.kts 中配置如下：
dependencies {
// Compose BOM – 统一版本
val composeBom = platform("androidx.compose:compose-bom:2024.10.01")
implementation(composeBom)
// Material3 核心库
implementation("androidx.compose.material3:material3")
// 可选：Material3 Window Size Class (适配大屏)
implementation("androidx.compose.material3:material3-window-size-class")
}在项目级 build.gradle.kts 的 plugins 块中确保已启用 Compose 编译器插件（版本与 Kotlin 匹配）：
plugins {
id("com.android.application") version "8.2.2" apply false
id("org.jetbrains.kotlin.android") version "1.9.22" apply false
}2.4 配置 Navigation 组件
Navigation for Compose 提供声明式路由和 NavHost 管理。在 app/build.gradle.kts 中添加：
implementation("androidx.navigation:navigation-compose:2.8.3")由于 navigation-compose 未纳入 Compose BOM，需要单独指定版本。注意与 Compose 和 Kotlin 的兼容性，推荐使用官方版本兼容表。
在 MainActivity.kt 中创建 NavController 并绑定 NavHost：
class MainActivity : ComponentActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContent {
PaymentTheme {
val navController = rememberNavController()
NavHost(navController = navController, startDestination = "home") {
composable("home") { HomeScreen(navController) }
composable("payment") { PaymentScreen(navController) }
}
}
}
}
}2.5 引入 Coil 图片加载
Coil 是一款纯 Kotlin 协程驱动的图片加载库，与 Compose 集成非常自然。添加依赖：
implementation("io.coil-kt:coil-compose:2.7.0")Coil 无需额外初始化，但在 Image 中使用时需提供 ImageRequest：
AsyncImage(
model = ImageRequest.Builder(LocalContext.current)
.data("https://example.com/product.png")
.crossfade(true)
.build(),
contentDescription = "产品图片",
modifier = Modifier.fillMaxWidth()
)2.6 完整依赖清单预览
以下为 app/build.gradle.kts 中本章涉及的完整 dependencies 块：
dependencies {
implementation(platform("androidx.compose:compose-bom:2024.10.01"))
implementation("androidx.compose.ui:ui")
implementation("androidx.compose.material3:material3")
implementation("androidx.compose.material3:material3-window-size-class")
implementation("androidx.compose.ui:ui-tooling-preview")
implementation("androidx.navigation:navigation-compose:2.8.3")
implementation("io.coil-kt:coil-compose:2.7.0")
debugImplementation("androidx.compose.ui:ui-tooling")
implementation("androidx.activity:activity-compose:1.9.2")
}2.7 调试与常见错误
| 常见错误 | 原因 | 解决方案 |
|---|---|---|
| Compose 版本不匹配（如 Material3 方法找不到） | BOM 版本过旧或未使用 BOM | 更新 compose-bom 至 2024.10.01 或更高 |
| Navigation 路由无法跳转 | NavController 作用域不当或 composable 未注册 | 确保 composable 块在 NavHost 内部且路由名称一致 |
| Coil 图片加载失败（显示占位图或空白） | 网络权限缺失或 URL 不可达 | 在 AndroidManifest.xml 中添加 <uses-permission android:name="android.permission.INTERNET"/> |
| Kotlin 编译器版本与 Compose 插件不兼容 | kotlin 版本与 compose-compiler 不匹配 | 参考 Compose 兼容性表升级 Kotlin |
2.8 性能与稳定性优化
- BOM 版本锁定：使用固定的 compose-bom 版本号（如 2024.10.01），避免自动升级引入破坏性变更。
- minSdk 要求：Material3 和 Navigation 要求 minSdk 至少为 21，在
build.gradle.kts中显式设置：minSdk = 21。 - Coil 内存缓存：Coil 默认使用 LruCache，无需额外配置。但若加载大量图片，可考虑自定义
ImageLoader并调整磁盘缓存大小。 - Navigation 懒加载：通过
composable(route, arguments) { backStackEntry -> ... }实现懒初始化，避免所有 Screen 在启动时同时加载。
完成以上步骤后，你的开发环境已具备实现 State Hoisting 支付页面的全部依赖基础。下一阶段将利用这些基础设施构建可复用的页面组件。