1. Kotlin Multiplatform 项目结构演进背景Kotlin MultiplatformKMP技术自2017年推出以来项目结构经历了多次重大调整。2023年JetBrains官方发布的《Kotlin Multiplatform Compose项目模板》首次引入了全新的标准项目布局这种结构在2024年成为Android Studio新建KMP项目的默认模板。传统KMP项目面临的主要痛点包括源代码集(source sets)命名混乱如androidAndroidTest平台特定代码与共享代码界限模糊构建脚本配置复杂且不一致IDE支持不完善导致的导航困难新结构通过以下设计原则解决这些问题明确分层commonMain/androidMain/iosMain等源代码集严格区分约定优于配置采用标准目录结构减少build.gradle配置工具链集成与Android Studio和Xcode深度整合渐进式迁移保留对旧结构的兼容支持2. 新项目结构核心解析2.1 目录结构规范标准KMP项目现在采用以下目录布局project-root/ ├── build.gradle.kts ├── settings.gradle.kts ├── gradle.properties └── modules/ ├── shared/ # 核心KMP模块 │ ├── build.gradle.kts │ └── src/ │ ├── androidMain/ │ │ ├── kotlin/ # Android平台代码 │ │ └── resources/ │ ├── commonMain/ │ │ ├── kotlin/ # 跨平台共享代码 │ │ └── resources/ │ ├── iosMain/ │ │ ├── kotlin/ # iOS平台代码 │ │ └── resources/ │ └── ...其他平台 ├── androidApp/ # Android应用模块 └── iosApp/ # iOS应用模块关键变化移除main和test等传统Android目录平台代码必须放在对应平台源代码集内资源文件也遵循相同隔离原则2.2 Gradle配置优化新结构对应的build.gradle.kts典型配置kotlin { androidTarget { compilations.all { kotlinOptions { jvmTarget 11 } } } iosX64() iosArm64() iosSimulatorArm64() sourceSets { commonMain.dependencies { implementation(libs.kotlinx.coroutines) } androidMain.dependencies { implementation(libs.androidx.lifecycle) } } }主要改进使用androidTarget替代旧的android块显式声明iOS目标架构依赖项按源代码集严格分组默认启用层次结构(HMPP)项目模型2.3 多平台资源处理资源管理采用新的统一方案kotlin { androidTarget { resourcePrefix shared_ // 避免资源冲突 } sourceSets { commonMain.resources.srcDirs(src/commonMain/resources) androidMain.resources.srcDirs(src/androidMain/res) } }资源访问方式通用资源commonMain/resourcesAndroid特定资源androidMain/resiOS特定资源iosMain/resources3. Android与Compose集成实践3.1 Compose Multiplatform配置在共享模块中添加Compose支持kotlin { sourceSets { commonMain.dependencies { implementation(compose.runtime) implementation(compose.foundation) implementation(compose.material3) } androidMain.dependencies { implementation(libs.androidx.activity.compose) } } }关键注意事项必须使用Compose Multiplatform 1.6版本iOS需要额外配置SKIA渲染器预览功能需在androidMain中实现3.2 平台特定UI适配共享UI组件示例// shared/src/commonMain/kotlin/App.kt Composable expect fun PlatformSpecificComponent() // Android实现 Composable actual fun PlatformSpecificComponent() { AndroidView(/*...*/) } // iOS实现 Composable actual fun PlatformSpecificComponent() { UIKitView(/*...*/) }4. 构建与发布优化4.1 构建缓存配置在gradle.properties中添加kotlin.native.cacheKind.iosX64static kotlin.native.cacheKind.iosArm64static kotlin.native.cacheKind.iosSimulatorArm64static4.2 发布到Maven仓库配置发布脚本示例publishing { publications { createMavenPublication(maven) { groupId com.example artifactId kmp-library version 1.0 from(components[kotlin]) } } }5. 迁移指南与问题排查5.1 从旧结构迁移步骤创建新的源代码集目录结构移动现有代码到对应位置Java/Kotlin代码 → androidMain/kotlin资源文件 → androidMain/res测试代码 → android[Unit/Instrumented]Test更新build.gradle.kts配置同步Gradle并修复编译错误5.2 常见问题解决问题1找不到Android特定依赖解决方案确保依赖声明在androidMain而非commonMain问题2iOS编译失败检查是否正确声明了所有目标架构验证Podfile是否配置了Kotlin框架依赖问题3资源访问失败确认资源文件是否放在正确的源代码集目录检查build.gradle中是否正确定义了资源路径6. 性能优化建议增量编译启用Kotlin增量编译kotlin.incrementaltrue并行构建配置Gradle并行执行org.gradle.paralleltrue缓存策略合理使用构建缓存kotlin.native.cacheKindstatic依赖优化避免在commonMain中引入平台特定库7. 工具链支持7.1 Android Studio配置必备插件Kotlin Multiplatform Mobile 2.0Compose Multiplatform 支持插件推荐设置启用Kotlin编译器守护进程配置Gradle JDK为Java 177.2 Xcode集成要点在Podfile中添加target iosApp do pod shared, :path ../shared end配置Scheme支持模拟器和真机调试启用Kotlin/Native内存管理器
