Kotlin Multiplatform 新默认项目结构
TL;DR · AI 摘要
JetBrains 更新 Kotlin Multiplatform 默认项目结构，提升模块职责清晰度和构建一致性。
核心要点
- 新结构将共享代码与平台应用分离，提高可维护性。
- Android Gradle Plugin 9.0 要求入口点独立于共享代码。
- 支持 Amper 和 Gradle 的项目结构统一，减少配置复杂度。
结构提纲
按章节快速跳转。
- §引言
JetBrains 更新 Kotlin Multiplatform 默认项目结构以提升模块职责清晰度和构建一致性。
- §变化内容
新结构将共享代码与平台应用分离，每个模块有明确职责。
- §变更原因
旧结构导致模块职责不清，且不兼容 Android Gradle Plugin 9.0。
- §目标
新结构旨在提供清晰的模块职责和统一的构建流程。
思维导图
用一张图看清主题之间的关系。
查看大纲文本（无障碍 / 无 JS 友好）
- Kotlin Multiplatform 项目结构更新
- 模块职责分离
- 共享代码模块
- 平台应用模块
- 兼容性改进
- Android Gradle Plugin 9.0
- Amper 构建系统
金句 / Highlights
值得收藏与分享的关键句。
新结构将共享代码与平台应用分离，确保每个模块有明确职责和单一目的。
Android Gradle Plugin 9.0 要求 Android 应用的入口点独立于共享代码。
新结构统一了基于 Gradle 和 Amper 的项目，减少了配置复杂度。
标题: Kotlin 多平台的新默认项目结构 | Kotlin 博客
URL 来源: https://blog.jetbrains.com/kotlin/2026/05/new-kmp-default-structure
Markdown 内容:
JetBrains 开发的简洁多平台语言
Kotlin 多平台的新默认项目结构
2026年5月15日
我们正在更新 Kotlin 多平台项目的默认项目结构，以使模块职责更清晰、更好地与其他构建系统和框架使用的约定保持一致，并反映 Android Gradle Plugin 9.0 中的变更。
您将在我们的工具生成的新建项目、官方文档以及 Kotlin 多平台示例中看到这个项目结构。
这些变更已经在 KMP 向导中生效，无论是在您的 IDE 中（安装了 Kotlin 多平台插件）还是在 kmp.jetbrains.com 上。我们也在更新示例项目和其他学习材料以匹配这个新结构。您已经可以查看 kotlinconf-app、KMP-App-Template 或 RSS Reader 作为参考。
要在 IntelliJ IDEA 中获得对 AGP 9.0 的支持，请更新到 2026.1.2 或更高版本，并使用最新版本的 Android 插件。
这篇文章解释了我们将要进行的变更、我们为何改变结构，以及如何更新现有项目。
变更内容
在我们之前的结构中，大多数项目都有一个单一的 composeApp Gradle 模块，它包含一个 Kotlin 多平台库，并充当一个或多个平台的应用程序，包含它们的入口点和其他相关配置。
在 _Project_ 视图中，这看起来像：
我们的新默认结构有一个 shared 模块，具有单一清晰的职责：它是一个包含共享代码的 Kotlin 多平台库。然后，对于每个您想在共享库代码之上构建可运行应用程序的平台，您将有单独的应用模块，如 androidApp、desktopApp 和 webApp。
新结构在 _Project_ 视图中看起来像这样：
我们为何进行变更
旧结构中的 composeApp 模块有几个不同的职责。因此，它包含大量配置，包括所有平台的平台特定打包细节。这可能使得难以区分哪些部分在设置 Kotlin 多平台库，哪些部分在设置应用程序本身。
如果您选择 _不_ 在客户端平台上共享 UI（例如，为您的 iOS 应用使用 SwiftUI），旧结构除了 composeApp 外还包含一个额外的 shared 模块。这是对模块结构的重大改变，但它只发生在某些配置中。
在 iOS 应用方面也存在不对称性。因为它们需要一个使用共享代码的 Xcode 项目，iOS 应用程序已经位于单独的 iosApp 文件夹中，而基于共享代码构建的其他应用程序都位于 composeApp 中。
Android Gradle Plugin 9.0 要求 Android 应用程序的入口点与共享代码位于不同的模块中，因为它不再支持在多平台模块中应用 Android 应用程序 Gradle 插件。
最后，我们之前对基于 Gradle 和基于 Amper 的项目有不同的结构。虽然 Gradle 支持在单个模块中配置多个应用程序，但 Amper 只允许每个模块一个产品，因此基于 Amper 的项目已经为每个应用程序使用单独的模块。
新结构的目标
基于以上几点，我们创建了新结构，并牢记以下目标：
- 为项目提供初始设置，其中每个模块都有 清晰的职责和单一目的。应该始终清楚给定的代码片段或构建配置应该放在项目中的哪个位置。
- 在向导允许的不同配置之间 尽可能保持结构一致：不同的目标平台集合、是否有服务器应用程序，以及为客户端选择原生或共享 UI。
- 使 进一步模块化 变得容易，根据需要从单个多平台模块发展到多个模块。
适应其他配置
上面的示例展示了 Compose 多平台应用程序的新项目结构，该应用程序在 Android、iOS、桌面和 Web 平台之间共享其 UI。在其他配置中，结构将根据需要调整，变更最小。
使用原生 UI 的配置
Kotlin Multiplatform 支持在共享 Kotlin 代码基础上使用原生 UI。例如，您可以选择在 iOS 应用中使用 SwiftUI，而在其他平台使用 Compose Multiplatform。这种情况下，您需要编写被所有平台使用的共享业务逻辑代码，以及仅被特定平台使用的共享 UI 代码。
在这种配置中，新的结构将包含两个共享模块而非一个：sharedLogic 和 sharedUI。sharedLogic 被所有应用程序使用且不依赖 Compose，而 sharedUI 仅被那些使用 Compose Multiplatform 作为 UI 的平台使用。
决定将共享代码放在哪个模块仍然很简单：如果所有平台（包括使用原生 UI 实现的平台）都会使用该代码，则应放入 sharedLogic；如果只有使用 Compose Multiplatform 的平台需要该代码，则应放入 sharedUI。
包含服务器的配置
对于同时面向服务端 Kotlin 的项目，新结构会添加一个 server 模块，并将所有客户端模块移至嵌套的 app 文件夹中。项目根目录中的额外 core 模块允许您在服务端和客户端代码之间共享代码，例如模型和验证逻辑。
更新现有项目
虽然我们正在更改新创建项目的默认结构，但现有项目无需采用完全相同的结构。如果您希望将现有项目迁移至这一新的默认结构，可以参考迁移指南，其中展示了如何为每个入口点引入新模块。
请注意，对于所有面向 Android 的现有多平台项目，与 Android Gradle Plugin 9.0 相关的更改是强制性的。您可以在这篇博客文章中了解更多关于这些更改的信息以及如何更新项目。
要在 IntelliJ IDEA 中获得对 AGP 9.0 的支持，请更新至 2026.1.2 或更高版本，并使用最新版本的 Android 插件。
立即开始使用 KMP
要创建具有更新结构的新项目，请访问 kmp.new 或在您的 IDE 中使用 Kotlin Multiplatform 向导（在 IntelliJ IDEA 和安装了 Kotlin Multiplatform 插件的 Android Studio 中均可用）。
如果您想查看新结构的实际示例，请参考 kotlinconf-app、KMP-App-Template 或 RSS Reader。
[](https://blog.jetbrains.com/kotlin/2026/05/new-kmp-default-structure#)