第2章：项目环境搭建 — Android Studio 配置、Gradle 依赖、Kotlin 版本要求与 Material 3 组件库导入

环境搭建是支付 UI 与 Material 3 主题集成的基石。本章从 Android Studio 版本要求入手，逐步完成 Gradle 依赖注入、Kotlin 版本匹配、Material 3 组件库导入，并验证环境可行性。所有操作均围绕 Material 3（Material You）动态配色 + 支付功能模块 的协同开发场景展开。

2.1 环境依赖总览

下表列出本次课程推荐的开发环境最低与建议版本，确保 Material 3 组件编译通过且不产生 API 降级警告。

2.2 Android Studio 配置关键项

打开 Android Studio → File → Settings（macOS: Preferences），按以下步骤确保编译工具链正确。

1. SDK Manager：安装 Android SDK Platform 34（或35）、SDK Build-Tools 34.0.0+；避免仅安装最新预览版。
2. Kotlin 插件：确认 Kotlin 插件版本 ≥ 1.8.20，且与项目级 build.gradle.kts 中的 Kotlin 版本一致。
3. Gradle JDK：推荐 JDK 17（Embedded 或 Oracle OpenJDK 17）；JDK 11 可能导致 AGP 8.x 编译警告。
4. Experimental Features：若使用 Compose 预览，需启用 Enable Compose UI design tools preview support（File → Settings → Experimental → Compose）。

2.3 Gradle 依赖与版本声明

以下展示项目级及模块级 build.gradle.kts 完整配置。请严格按顺序添加，并注意版本变量统一管理。

2.3.1 项目级 build.gradle.kts

// project/build.gradle.kts
plugins {
    id("com.android.application") version "8.7.3" apply false
    id("org.jetbrains.kotlin.android") version "2.0.21" apply false
    id("org.jetbrains.kotlin.plugin.compose") version "2.0.21" apply false
}

2.3.2 模块级 build.gradle.kts

// app/build.gradle.kts
plugins {
    id("com.android.application")
    id("org.jetbrains.kotlin.android")
    id("org.jetbrains.kotlin.plugin.compose")
}

android {
    namespace = "com.example.payment_ui"
    compileSdk = 35

    defaultConfig {
        applicationId = "com.example.payment_ui"
        minSdk = 26
        targetSdk = 35
        versionCode = 1
        versionName = "1.0"
    }

    buildFeatures {
        compose = true
    }

    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }

    kotlinOptions {
        jvmTarget = "17"
    }
}

dependencies {
    // Compose BOM — 统一管理 Compose 版本
    val composeBom = platform("androidx.compose:compose-bom:2024.12.01")
    implementation(composeBom)

    // Material 3 核心库
    implementation("androidx.compose.material3:material3:1.3.1")
    // Material 3 动态配色支持 (Android 12+)
    implementation("androidx.compose.material3:material3-adaptive:1.0.0-rc01")

    // Compose UI 基础
    implementation("androidx.compose.ui:ui")
    implementation("androidx.compose.ui:ui-graphics")
    implementation("androidx.compose.ui:ui-tooling-preview")
    implementation("androidx.compose.material:material-icons-extended")
    implementation("androidx.activity:activity-compose:1.9.3")

    // 支付业务通常需要 Lifecycle + ViewModel
    implementation("androidx.lifecycle:lifecycle-viewmodel-compose:2.8.7")

    // 调试工具
    debugImplementation("androidx.compose.ui:ui-tooling")
    debugImplementation("androidx.compose.ui:ui-test-manifest")
}

2.4 Kotlin 版本要求与编译器配置

Kotlin 2.0+ 引入了 Compose 编译器插件，需在项目中显式启用 org.jetbrains.kotlin.plugin.compose。若仍使用 Kotlin 1.9.x，需额外配置 composeCompiler 扩展块。

关键检测点：

• gradle-wrapper.properties 中 Gradle 版本 ≥ 8.2
• 项目级 plugins 中 kotlin 与 compose 版本一致
• 模块级 kotlinOptions.jvmTarget 必须与 compileOptions 中的 Java 版本一致（均设为 17）

2.5 导入 Material 3 组件库后的验证

在 MainActivity.kt 中编写以下代码，验证 Material 3 组件可成功 inflate 且动态配色生效。

// MainActivity.kt
class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContent {
            PaymentAppTheme {
                // 测试 Material 3 组件
                var amount by remember { mutableStateOf("0.00") }

                Scaffold(
                    topBar = {
                        TopAppBar(
                            title = { Text("支付确认") },
                            colors = TopAppBarDefaults.mediumTopAppBarColors(
                                containerColor = MaterialTheme.colorScheme.primaryContainer,
                                titleContentColor = MaterialTheme.colorScheme.onPrimaryContainer
                            )
                        )
                    }
                ) { paddingValues ->
                    Column(
                        modifier = Modifier
                            .padding(paddingValues)
                            .fillMaxSize()
                            .padding(16.dp),
                        horizontalAlignment = Alignment.CenterHorizontally
                    ) {
                        // Material 3 输入框
                        OutlinedTextField(
                            value = amount,
                            onValueChange = { amount = it },
                            label = { Text("金额") },
                            prefix = { Text("¥") },
                            keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Decimal)
                        )
                        Spacer(modifier = Modifier.height(16.dp))
                        // Material 3 按钮
                        Button(
                            onClick = { /* simulate payment */ },
                            enabled = amount.toDoubleOrNull() != null
                        ) {
                            Text("支付")
                        }
                    }
                }
            }
        }
    }
}

运行项目后，若界面正常显示 Material 3 风格的 TopAppBar、OutlinedTextField 和 Button，且色彩跟随系统动态颜色（Android 12+ 壁纸取色），则环境搭建成功。

2.6 典型错误与调试

2.6.1 “Unresolved reference: material3”

原因：material3 依赖未正确添加或 Compose BOM 版本过低（< 2023.10）。
解决：检查 build.gradle.kts 中 dependencies 块是否包含 implementation("androidx.compose.material3:material3")（无版本号则继承 BOM）。确认后点击 File → Sync Project with Gradle Files。

2.6.2 “Cannot inline bytecode built with JVM target 1.8 into bytecode that is being built with JVM target 17”

原因：依赖库编译时使用 JVM 1.8，而当前项目设为 17。此错误通常因 Kotlin 版本 < 1.6 或 Gradle 插件未同步。
解决：统一设置 kotlinOptions.jvmTarget = "17" 和 compileOptions {... JavaVersion.VERSION_17}。若仍报错，升级 Kotlin 插件至 2.0+。

2.6.3 “Dynamic colors not available on this device”

原因：Material 3 动态配色仅支持 Android 12+（API 31+）。

• 若测试设备为 Android 11 以下，代码中需提供 fallback 主题。
• 检查 PaymentAppTheme 是否包裹在 dynamicColor = true 参数内。

// 在 PaymentAppTheme 定义处
MaterialTheme(
    colorScheme = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S && dynamicColor) {
        dynamicLightColorScheme(context)
    } else {
        lightColorScheme()  // 自定义降级
    }
)

2.7 环境搭建流程图

以下 SVG 展示了从项目创建到 Material 3 组件验证的完整流程，并标注了关键决策点。

2.8 部署前环境检查清单

在执行第3章的支付 UI 具体布局开发前，请逐项核对以下环境健康指标：

• ✅ Android Studio 内 Build → Clean Project 后无红色波浪线
• ✅ 在 terminal 执行 ./gradlew assembleDebug 无编译错误
• ✅ MainActivity.kt 中的 PaymentAppTheme 引用不可见红色（需定义主题文件）
• ✅ 真机或模拟器上运行后，按钮/输入框色彩随系统动态取色变化
• ✅ 若使用 Android Studio 旧版本（2022.3），已手动升级 AGP 至 8.1+

至此，支付 UI 项目的 Material 3 开发环境已完全搭建完毕。下一环节将正式进入主题配色方案的设计与动态配色代码实现。