Kotlin Multiplatform 的新默认项目结构
TL;DR · AI 摘要
Kotlin Multiplatform 默认项目结构已更新，以提高模块职责清晰度和与构建系统的兼容性。
核心要点
- 新结构将共享代码与平台特定应用模块分离，提升可维护性。
- Android Gradle Plugin 9.0 要求入口点必须在独立模块中。
- JetBrains 提供了多个示例项目用于参考新结构。
结构提纲
按章节快速跳转。
- §引言
介绍 Kotlin Multiplatform 默认项目结构的更新及其目的。
描述旧结构与新结构之间的主要区别，包括模块划分方式的变化。
解释为何需要对项目结构进行调整，包括配置复杂性和平台支持问题。
列出新结构的设计目标，如模块职责明确、结构一致性等。
思维导图
用一张图看清主题之间的关系。
查看大纲文本（无障碍 / 无 JS 友好）
- Kotlin Multiplatform Project Structure Update
- Old Structure Issues
- Module Responsibilities Overlap
- Platform-Specific Configurations Mixed
- Inconsistent Module Layouts
- New Structure Goals
- Clear Module Responsibilities
- Consistent Across Platforms
- Support for AGP 9.0
- Implementation Details
- Shared Module for Shared Code
- Separate Application Modules (e.g., androidApp, desktopApp)
- Reference Projects Available
金句 / Highlights
值得收藏与分享的关键句。
旧结构中的 `composeApp` 模块承担了多种不同的职责。
Android Gradle Plugin 9.0 要求 Android 应用程序的入口点必须与共享代码位于独立模块中。
我们正在更新我们的示例项目和其他学习材料以匹配这种新结构。
JetBrains 开发的简洁多平台语言
Kotlin Multiplatform 的新默认项目结构
我们正在更新 Kotlin Multiplatform 项目的默认项目结构，旨在让模块职责更清晰，更好地与其他构建系统和框架的惯例保持一致，并反映 Android Gradle Plugin 9.0 中的变更。
你将在我们的工具生成的新建项目、官方文档以及 Kotlin Multiplatform 的示例中看到这个项目结构。
这些变更已经在 KMP 向导中生效，无论是在你的 IDE 中（安装了 Kotlin Multiplatform 插件）还是在 kmp.jetbrains.com 上。我们也在更新我们的示例项目和其他学习材料以匹配这个新结构。你现在就可以参考 kotlinconf-app、KMP-App-Template 或 RSS Reader。
要在 IntelliJ IDEA 中获得对 AGP 9.0 的支持，请更新到 2026.1.2 或更高版本，并使用最新版本的 Android 插件。
这篇文章解释了我们正在进行的变更、我们改变结构的原因，以及你如何更新现有项目。
变更内容
在我们之前的结构中，大多数项目都有一个单一的 composeApp Gradle 模块，它包含一个 Kotlin Multiplatform 库，同时也充当一个或多个平台的应用程序，包含它们的入口点和其他相关配置。
在 _Project_ 视图中，它看起来像这样：
我们的新默认结构有一个 shared 模块，它职责单一且清晰：它是一个包含共享代码的 Kotlin Multiplatform 库。然后，对于每个你希望在共享库代码之上构建可运行应用程序的平台，你将拥有单独的应用程序模块，例如 androidApp、desktopApp 和 webApp。
新结构在 _Project_ 视图中看起来像这样：
我们进行变更的原因
旧结构中的 composeApp 模块承担了多种不同的职责。因此，它包含了很多配置，包括所有平台的特定打包细节。这可能使得难以区分哪些部分是在设置 Kotlin Multiplatform 库，哪些部分是在设置应用程序本身。
如果你选择在某个客户端平台上 _不_ 共享 UI（例如，为你的 iOS 应用程序使用 SwiftUI），旧结构除了 composeApp 之外还包含一个额外的 shared 模块。这是对模块结构的一个重大改变，但它只发生在某些配置中。
在处理 iOS 应用时也存在不对称性。因为它们需要一个使用共享代码的 Xcode 项目，iOS 应用程序已经位于一个单独的 iosApp 文件夹中，而其他基于共享代码构建的应用程序都位于 composeApp 中。
Android Gradle Plugin 9.0 要求 Android 应用程序的入口点与共享代码位于不同的模块中，因为它不再支持在多平台模块中应用 Android 应用程序 Gradle 插件。
最后，我们之前对于基于 Gradle 和基于 Amper 的项目有不同的结构。虽然 Gradle 支持在单个模块中配置多个应用程序，但 Amper 只允许每个模块有一个产品，因此基于 Amper 的项目已经为每个应用程序使用了单独的模块。
新结构的目标
基于以上几点，我们创建新结构时考虑了以下目标：
- 为项目提供一个初始设置，其中每个模块都有 清晰的职责和单一的目的。应该始终清楚给定的代码片段或构建配置应该放在项目中的哪个位置。
- 在向导允许的不同配置之间 尽可能保持结构一致：不同的目标平台集合、是否包含服务器应用程序，以及为客户端选择原生 UI 还是共享 UI。
- 使得 进一步模块化 项目变得容易，以便根据需要从单个多平台模块过渡到多个模块。
适应其他配置
上面的示例展示了在 Android、iOS、桌面和 Web 平台上共享 UI 的 Compose Multiplatform 应用程序的新项目结构。在其他配置中，结构将根据需要以最小的变更进行适应。
使用原生 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/#)