KMP 新默认项目结构变化清单：4 个原因 + 3 个目标 + 2 个适配 + 1 份迁移指南

KMP 新默认项目结构全解析：5 分钟看懂所有变化

大家好，我是你的 Kotlin 跨平台小助手。 今天来介绍一下 JetBrains 发布的 KMP 的新默认项目结构，相信很多同学打开 IDE 新建项目时都愣了一下：我的 composeApp 呢？ 别慌，这篇给你把所有变化讲清楚，5 分钟看完，照着迁移就行。

先问你三个问题

有没有遇到过这些情况？

❌ 想改个 Android 打包配置，翻了半天 build.gradle.kts 找不到哪段是共用的、哪段是平台的 ❌ 项目要加个 iOS 原生 UI，发现结构全乱了，shared 和 composeApp 要重新拆 ❌ Gradle sync 慢得要死，一个模块里塞了 N 个 source set

如果你中了任何一条，恭喜你——这次的结构变化，就是为你准备的。

今天这篇文章把 KMP 新结构讲透：

• • 4 个变更原因
• • 3 个设计目标
• • 2 种特殊场景如何适配
• • 1 份迁移检查清单

看完直接就能用。

1️⃣ 新旧结构对比：一图看懂

先给你看最直观的变化。

❌ 旧结构（你熟悉的 composeApp）

myProject/
└── composeApp/          # 啥都管的"万能模块"
    ├── src/
    │   ├── androidMain/
    │   ├── commonMain/
    │   ├── desktopMain/
    │   ├── jsMain/
    │   └── iosMain/
    └── build.gradle.kts # 几百行配置，看到头大

旧结构的问题：

• • 一个模块既是 KMP 库，又是 N 个平台的应用入口
• • 所有平台打包配置混在一起
• • 目录嵌套 5 层以上，找文件费劲

✅ 新结构（现在的默认）

myProject/
├── shared/             # 只做一件事：共享代码
│   └── src/
│       ├── androidMain/
│       ├── commonMain/
│       ├── desktopMain/
│       ├── jsMain/
│       └── iosMain/
├── androidApp/         # Android 专属入口
├── desktopApp/         # Desktop 专属入口
├── webApp/             # Web 专属入口
└── iosApp/             # iOS 本来就在这

新结构的好处：

• • 职责清晰，一眼知道代码放哪
• • 每个模块的 build.gradle.kts 瘦身 50% 以上
• • Gradle sync 更快了（别问，问就是并行）

💡 好的架构，应该让你不用思考就知道代码放哪。

2️⃣ 4 个变更原因：JetBrains 不是瞎改的

每次改结构都会有人喊"又折腾"，但这次真不是为了改而改。

原因 1：composeApp 职责太多了

想象一下：一个类里同时写 UI、网络请求、数据存储，你肯定会说这是坏味道。

那一个 Gradle 模块同时做：

• • Kotlin Multiplatform 库配置
• • Android 应用打包
• • Desktop 打包
• • Web 打包

这不是坏味道吗？

拆分后，shared 只管共享代码，各平台 app 管自己的打包。单一职责原则，放到哪都对。

原因 2：iOS 早就不在里面了

发现没有？iOS 因为要用 Xcode，一直都是独立的 iosApp 文件夹。

这就造成了不对称：

• • iOS：在外面，独立模块 ✅
• • Android：在 composeApp 里 ❌
• • Desktop：在 composeApp 里 ❌
• • Web：在 composeApp 里 ❌

现在统一了，所有平台应用都在独立模块，舒服了。

原因 3：⚠️ AGP 9.0 的强制要求

这个是重点，敲黑板。

Android Gradle Plugin 9.0 开始，不再支持在 multiplatform 模块里应用 application 插件。

翻译成人话：你的 Android app 代码，必须放在一个纯 Android 的模块里，不能放在 multiplatform 模块里。

这不是 JetBrains 想改，是 Android 强制要求的。

❗️ 划重点：就算你不想用新结构，只要升级 AGP 9.0，这一步也必须做。

原因 4：和 Amper 保持一致

JetBrains 新出的 Amper 构建工具，因为每个 module 只能有一个 product，天然就是用的"共享库 + 各平台独立应用"的结构。

现在 Gradle 项目也统一了，两种构建工具的用户体验一致，切换成本更低。

3️⃣ 新结构的 3 个设计目标

JetBrains 在设计时，心里装着这 3 个目标：

✅ 目标 1：每个模块职责单一明确

以后新人进项目，你不用解释半小时了：

• • 共享代码 → 放 shared
• • Android 专属 → 放 androidApp
• • Desktop 专属 → 放 desktopApp
• • iOS 专属 → 放 iosApp

就这么简单。

✅ 目标 2：不同配置下结构一致

之前的结构很分裂：

• • 如果你全用 Compose UI → 只有 composeApp
• • 如果你某平台用原生 UI → 多了个 shared

现在不管你怎么选，结构都一样。

选哪些平台、加不加服务端、用不用原生 UI，项目结构的模式永远不变。

✅ 目标 3：易于进一步模块化

项目小的时候，一个 shared 就够了。

项目大了以后呢？ 想拆成 :shared:core、:shared:feature-home、:shared:feature-profile...

新结构下，这些拆分都很自然。旧结构下，你还要纠结 composeApp 拆不拆、怎么拆。

💡 金句：好的架构，在项目增长时不会逼你重构。

4️⃣ 2 种特殊配置如何适配

新结构不是死的，会根据你的选择自适应。

场景 A：用原生 UI（如 SwiftUI）

如果你的 iOS 用 SwiftUI，其他平台用 Compose Multiplatform：

myProject/
├── sharedLogic/    # 所有平台共用，不含 Compose
│   └── 业务逻辑、数据层、网络请求...
├── sharedUI/       # 仅 Compose 平台用，含 Compose
│   └── UI 组件、导航、主题...
├── androidApp/     # 用 sharedUI + sharedLogic
├── desktopApp/     # 用 sharedUI + sharedLogic
└── iosApp/         # 只用 sharedLogic，UI 用 SwiftUI 写

判断规则：

所有平台都会用到的代码 → 放 sharedLogic 只有 Compose 平台需要的代码 → 放 sharedUI

场景 B：项目包含服务端代码

如果你的项目是全栈 Kotlin，还要写服务端：

myProject/
├── core/           # 前后端共享
│   └── 数据模型、验证逻辑、API 接口定义...
├── server/         # 服务端代码
└── app/            # 所有客户端都在这
    ├── shared/
    ├── androidApp/
    ├── desktopApp/
    └── iosApp/

客户端代码统一放进 app 文件夹，避免和服务端混在一起。

5️⃣ 现有项目迁移指南

好消息：迁移不是强制的。

5.1 迁移政策

✅ 旧项目可以继续用旧结构

• • 新结构只影响通过 Wizard 新创建的项目
• • 现有项目没人逼你改，想什么时候改什么时候改

❌ 但有个例外

• • AGP 9.0 相关变更是强制的
• • 只要你的项目用 Android + KMP，升级 AGP 9.0 就必须把 Android 入口移到独立模块

说白了就是：完全不想改也行，但 AGP 9.0 那部分你迟早得动。

5.2 迁移 3 步走

想完全迁移到新结构？按这个清单来：

• •Step 1：创建 androidApp 模块，把 Android application 配置和入口代码移过去
• •Step 2：创建 desktopApp、webApp 等模块，把各平台入口移过去
• •Step 3：composeApp 改名为 shared，只保留 library 配置

5.3 IDE 版本要求

要获得完整支持，记得升级：

• •IntelliJ IDEA 2026.1.2 或更新
• •安装最新版 Android 插件

6️⃣ 官方示例 + 参考资源

想看看别人怎么写的？这 3 个官方项目可以参考：

其他有用链接：

• • 🔗 创建新项目：kmp.new[4]
• • 🔗 官方迁移指南：Multiplatform Project Structure[5]
• • 🔗 AGP 9.0 迁移指南：Update your projects for AGP9[6]

📋 最后：10 项自检清单

看完这篇，检查一下你掌握了多少：

• • 能说出新旧结构的核心区别
• • 知道为什么要把 composeApp 拆开
• • 理解"单一职责"在架构中的应用
• • 明白 iOS 结构不对称的问题怎么解决的
• • 知道 AGP 9.0 是强制要求，其他是可选的
• • 记住了新结构的 3 个设计目标
• • 知道原生 UI 场景下如何拆 sharedLogic 和 sharedUI
• • 知道有服务端时如何组织目录
• • 知道迁移的 3 个步骤
• • 收藏了官方示例项目链接

✍️ 写在最后

每次技术变更，都会有人喊"又学新东西"。

但你仔细想想：这次的变化，其实是把我们私下里早就会做的最佳实践，变成了官方默认而已。

有经验的 KMP 开发者，早就开始拆模块了，现在只不过是 JetBrains 帮你把模板做好了而已。

好的工具，会把大家都觉得对的事，变成默认选项。

从这个角度看，KMP 越来越成熟了。

今天的分享就到这里。后续我会持续为大家带来实用的技术干货和前沿的技术资讯。如果你对工具链探索感兴趣，我会在公众号「DevLlama」持续分享前端工程化、构建优化等实战经验，欢迎关注，不要错过任何精彩内容！

支持我们，点赞或分享到朋友圈！

引用链接

[1] GitHub: https://github.com/JetBrains/kotlinconf-app/ [2] GitHub: https://github.com/Kotlin/KMP-App-Template [3] GitHub: https://github.com/Kotlin/kmp-production-sample [4] kmp.new: https://kmp.new [5] Multiplatform Project Structure: https://kotlinlang.org/docs/multiplatform/multiplatform-project-recommended-structure.html [6] Update your projects for AGP9: https://blog.jetbrains.com/kotlin/2026/01/update-your-projects-for-agp9/