Compose Multiplatform Template 的 Gradle 构建深度剖析从集中版本管理到多目标编译的完整指南【免费下载链接】compose-multiplatform-templateCompose Multiplatform Application project template项目地址: https://gitcode.com/gh_mirrors/co/compose-multiplatform-template本文带你剖析 Compose Multiplatform Template一个用于快速搭建 Android、iOS 和桌面三端应用的官方项目模板背后的 Gradle 构建体系。作为一套 Compose Multiplatform 应用模板它用一套 Kotlin 源码同时编译出 Android、iOS、Windows、macOS、Linux 三端可执行程序核心全在gradle.properties、settings.gradle.kts和shared/build.gradle.kts这三个文件里。读完你会理解集中版本管理与多目标编译这两个概念是如何落地的。 想动手实践可以先获取源码仓库git clone https://gitcode.com/gh_mirrors/co/compose-multiplatform-template一、Gradle 项目全景两个 App 壳 一个 shared 共享模块在 IDE 中打开后你会看到整个模板由三块组成模块角色构建脚本shared唯一写业务 UI 的地方同时编译到四端shared/build.gradle.ktsandroidAppAndroid 应用壳只负责启动 ActivityandroidApp/build.gradle.ktsdesktopApp桌面应用壳只负责启动窗口desktopApp/build.gradle.kts这个结构是理解全部构建配置的前提真正干活的是 shared两个 App 壳几乎只有 20 行配置。二、集中版本管理gradle.properties 是唯一版本源很多项目把依赖版本散落写在各处而这个模板把所有关键版本号集中收拢到根目录的 gradle.properties 中#Versions kotlin.version1.9.21 agp.version8.0.2 compose.version1.5.11 #Android android.compileSdk34 android.targetSdk34 android.minSdk24这一设计的妙处在于升级只需改一个文件比如想把 Kotlin 升到新版只动kotlin.version这一行所有模块自动生效避免版本漂移Android、桌面、iOS 三条链路用的是同一份 Kotlin 和 Compose 版本不会出现A 端 1.9.2、B 端 1.9.21这类诡异问题非构建配置也在这里android.useAndroidXtrue、JVM 内存参数org.gradle.jvmargs-Xmx2048M同样集中管理。对新手来说记住一个心法看到findProperty(android.compileSdk)这样的代码就去 gradle.properties 找答案。三、settings.gradle.kts插件版本如何被钉住settings.gradle.kts 承担了三件大事1️⃣ 声明子模块include(:androidApp) include(:shared) include(:desktopApp)2️⃣ 集中声明插件版本pluginManagement文件里通过extra[kotlin.version] as String把 gradle.properties 中的版本号读出来然后统一绑定kotlin(multiplatform).version(kotlinVersion) id(com.android.application).version(agpVersion) id(org.jetbrains.compose).version(composeVersion)这就是集中版本管理真正生效的地方——插件版本也走同一个版本源。子模块里再写kotlin(multiplatform)时就不用也不能重复写版本号否则 Gradle 会直接报错。3️⃣ 仓库来源统一pluginManagement与dependencyResolutionManagement分别声明了插件仓库和依赖仓库gradlePluginPortal、mavenCentral、google 以及 JetBrains 的 Compose 仓库全项目共享子模块无需各自再写repositories。四、根 build.gradle.ktsapply(false) 的巧妙之处根目录的 build.gradle.kts 只有短短 8 行plugins { kotlin(multiplatform).apply(false) id(com.android.application).apply(false) id(com.android.library).apply(false) id(org.jetbrains.compose).apply(false) }注意apply(false)的注释避免插件在每个子项目的类加载器中被重复加载。这里只是登记插件真正应用发生在各子模块。对新手这是一个很好的习惯示范——根构建脚本保持极薄职责分明。五、多目标编译原理shared 模块一次编译四个目标这是全文最核心的部分。打开 shared/build.gradle.kts你会看到 Kotlin 多平台配置kotlin { androidTarget() jvm(desktop) listOf(iosX64(), iosArm64(), iosSimulatorArm64()).forEach { it.binaries.framework { baseName shared isStatic true } } }多目标编译的底层逻辑可以这样理解源码分层Source SetscommonMain是公共代码本模板里全部 Compose UI 都写在这里androidMain、desktopMain、iosMain是平台适配层源码继承文件里显式声明iosMain dependsOn(commonMain)再让iosX64Main等具体目标级源码集再依赖iosMain形成一棵清晰的继承树各目标各产其物androidTarget()→ 生成 Android LibraryAAR供 androidApp 壳使用jvm(desktop)→ 生成 JVM 字节码供桌面应用运行iosX64/iosArm64/iosSimulatorArm64→ 编译成静态 FrameworkisStatic true供 iOS 工程链接依赖按层注入compose.runtime、compose.foundation、compose.material加在commonMain三端共享的 UI 框架而 Android 特有的androidx.activity加在androidMain桌面特有的compose.desktop.common加在desktopMain。一句话总结同一份 commonMain 代码Kotlin 编译器针对不同目标生成三种产物AAR、JVM 字节码、iOS Framework这就是多目标编译。六、两个 App 壳如何白嫖 sharedandroidApp/build.gradle.kts中androidMain 源码集只有一条关键依赖implementation(project(:shared))同时通过namespace、applicationId和 gradle.properties 里的 SDK 版本完成 Android 配置并用jvmToolchain(17)锁定 Java 17。desktopApp/build.gradle.kts则更简洁引入compose.desktop.currentOs自动匹配 Windows/macOS/Linux 原生渲染再依赖:shared最后通过compose.desktop { application { ... } }指定入口类MainKt并声明可打包成 Dmg、Msi、Deb 安装包。七、Gradle Wrapper保证所有人用同一个 Gradle 版本模板自带gradlew/gradlew.bat脚本真正的版本定义在 gradle/wrapper/gradle-wrapper.propertiesdistributionUrlhttps\://services.gradle.org/distributions/gradle-8.2.1-bin.zip为什么重要Gradle 8.2.1 恰好是同时支持 Kotlin 1.9、Android Gradle Plugin 8.0 的兼容版本。Wrapper 让团队成员、CI 机器无论本机装了什么版本首次运行./gradlew build都会自动下载并锁定 Gradle 8.2.1彻底杜绝我这边能跑、你那边报错。八、构建产物速览一套代码三端同框构建完成后模板的默认代码会在三端呈现一致的界面九、新手常见疑问 FAQQ1为什么子模块不写版本号Gradle 却知道用哪个版本A因为settings.gradle.kts的pluginManagement.plugins块已经统一绑定了版本子模块直接引用插件 ID 即可。Q2我想给项目加一个新平台比如 Linux 桌面要改什么A只需在shared/build.gradle.kts的kotlin { }里加一个目标如linuxX64()并在sourceSets中配置依赖——其他文件基本不用动。Q3gradle.properties 里的kotlin.mpp.androidSourceSetLayoutVersion2是干嘛的A它声明采用新版 Android 源码集目录布局src/androidMain而非旧的src/android与本模板的目录结构配套。总结从这套模板能学到的三个构建习惯习惯对应文件收益版本号集中管理gradle.properties升级零遗漏插件版本在 settings 中统一钉住settings.gradle.kts杜绝版本漂移根脚本 apply(false) 保持极薄build.gradle.kts结构清晰、加载快平台目标声明式集中在 sharedshared/build.gradle.kts新增平台改动最小Compose Multiplatform Template 虽然代码量不大但它的 Gradle 构建组织方式——单一版本源、集中插件管理、声明式多目标编译——正是生产级 KMP 项目的标准姿势。把这套理解迁移到自己的项目里你以后处理多端构建问题就会胸有成竹。【免费下载链接】compose-multiplatform-templateCompose Multiplatform Application project template项目地址: https://gitcode.com/gh_mirrors/co/compose-multiplatform-template创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考