📚 课程目录第1章 Jetpack Compose 简介与开发环境搭建

1. 项目初始化与环境配置

本章从零搭建 Jetpack Compose 支付项目，涵盖 Android Studio 项目创建、Gradle 依赖管理、最低 SDK 设定以及支付 SDK 仓库集成。正确的环境配置是后续页面构建的基石，任何版本冲突或仓库缺失都会导致编译失败或运行时不可用。

1.1 环境概览与原理

Jetpack Compose 基于 Kotlin 语言，最低支持 Android API 21（Android 5.0）。支付 SDK 通常要求 API 21 以上，并依赖 Material 3 组件库。Gradle 插件版本与 Kotlin 版本需严格对齐，否则会出现 @Composable 注解无法识别等问题。

组件	推荐版本（2025 Q1）	最低版本
Android Gradle Plugin	8.5.0	8.2.0
Kotlin	2.0.21	1.9.22
Compose BOM	2025.01.00	2024.09.00
支付 SDK（示例）	2.3.1	2.0.0

版本对齐提示：使用 Compose BOM 统一管理所有 Compose 库版本，避免手动逐个声明造成不一致。

1.2 实现流程

在 Android Studio 中通过模板创建“Empty Compose Activity”。
编辑 gradle/libs.versions.toml（版本目录）定义统一版本。
在 app/build.gradle.kts 中添加 Compose BOM、Material3、支付 SDK 依赖。
设置 minSdk 为 21（或更高，视支付 SDK 要求）。
在 settings.gradle.kts 中添加支付 SDK 的 Maven 或自定义仓库地址。
执行 Gradle Sync，确认无红色错误。

  初始化流程图：下方 SVG 展示了从项目创建到仓库验证的完整链路。

1.3 关键代码与配置

版本目录（gradle/libs.versions.toml）推荐统一管理依赖版本：

[versions]
compose-bom = "2025.01.00"
kotlin = "2.0.21"
agp = "8.5.0"
payment-sdk = "2.3.1"

[libraries]
compose-bom = { group = "androidx.compose", name = "compose-bom", version.ref = "compose-bom" }
material3 = { group = "androidx.compose.material3", name = "material3" }
payment-sdk-core = { group = "com.example.pay", name = "core", version.ref = "payment-sdk" }

[plugins]
android-application = { id = "com.android.application", version.ref = "agp" }
kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }
compose-compiler = { id = "org.jetbrains.kotlin.plugin.compose", version.ref = "kotlin" }

工程级 build.gradle.kts：

plugins {
    alias(libs.plugins.android.application) apply false
    alias(libs.plugins.kotlin.android) apply false
    alias(libs.plugins.compose.compiler) apply false
}

模块级 build.gradle.kts（核心依赖）：

plugins {
    alias(libs.plugins.android.application)
    alias(libs.plugins.kotlin.android)
    alias(libs.plugins.compose.compiler)
}

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

    defaultConfig {
        applicationId = "com.example.payment"
        minSdk = 21
        targetSdk = 35
        versionCode = 1
        versionName = "1.0"
    }
    buildFeatures { compose = true }
}

dependencies {
    implementation(platform(libs.compose.bom))
    implementation(libs.material3)
    implementation(libs.payment.sdk.core)
    // 其他 Compose 依赖（ui、activity-compose 等）由 BOM 统一引入
}

仓库配置（settings.gradle.kts）：

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        // 支付 SDK 私有仓库（示例）
        maven { url = uri("https://maven.payment-example.com/releases") }
    }
}

1.4 调试与常见错误

❌ 错误：Invoke-customs are only supported starting with Android O——通常由于 minSdk 低于 24，但 Compose 要求最低 21。若支付 SDK 使用了 Java 8 特性，需在 compileOptions 中开启 coreLibraryDesugaringEnabled。
❌ 错误：Could not find com.example.pay:core:2.3.1——仓库地址未添加或 URL 拼写错误，检查 settings.gradle.kts 中 maven 仓库的 url 是否可访问。
❌ 错误：⚠️ The Compose Compiler plugin requires Kotlin version——Kotlin 插件与 Compose Compiler 插件版本不匹配。使用别名 org.jetbrains.kotlin.plugin.compose 并确保版本一致。

⚠️ minSdk 选择：支付 SDK 有时会引入 java.nio.file 等 API 21 不存在的类，此时需将 minSdk 提升至 26 或使用 coreLibraryDesugaring。务必查阅支付 SDK 官方文档的 minSdk 约束。

1.5 性能与稳定性优化建议

启用 Gradle 配置缓存（gradle.properties 中添加 org.gradle.configuration-cache=true），减少后续重复解析。
使用 compose.compiler.reportsDestination 生成编译器报告，便于定位不可组合的函数降级。
支付 SDK 通常体积较大，建议在 build.gradle.kts 中配置 ndk { abiFilters "arm64-v8a", "armeabi-v7a" } 以精简 APK。

1.6 本章小结

完成项目初始化后，Gradle Sync 无红色错误即表示环境就绪。接下来可以从 Composable 函数入手设计支付表单布局。切记保持 libs.versions.toml 版本统一，避免后期依赖地狱。