Kotlin Multiplatform 项目结构更新：模块化与构建规范优化

我们正在更新 Kotlin Multiplatform (KMP) 项目的默认项目结构，旨在赋予模块更清晰的职责，使其更好地符合其他构建系统和框架的惯例，并反映 Android Gradle 插件 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 库，又作为一种或多种平台的应用程序存在，包含了入口点和其他相关配置。

[LOADING...]

在“项目”视图中，它看起来是这样的：

[LOADING...]

我们新的默认结构包含一个 shared 模块，其职责单一且明确：它是一个仅包含共享代码的 Kotlin Multiplatform 库。然后，对于你想要在共享库代码之上构建可运行应用程序的每个平台，你将拥有独立的应用程序模块，例如 androidApp、desktopApp 和 webApp。

[LOADING...]

新结构在“项目”视图中如下所示：

[LOADING...]

我们为何要进行变更

旧结构中的 composeApp 模块承担了多种不同的职责。结果是它包含了大量的配置，包括所有平台的特定平台打包细节。这使得很难区分哪些部分是在配置 Kotlin Multiplatform 库，哪些部分是在配置应用程序本身。

如果你选择在客户端平台上不共享 UI（例如，为 iOS 应用程序使用 SwiftUI），旧结构会在 composeApp 之外包含一个额外的 shared 模块。这虽然是模块结构的一项重大改变，但仅在特定配置下才会发生。

在 iOS 应用方面也存在不对称性。由于 iOS 应用需要一个使用共享代码的 Xcode 项目，因此它们原本就被放置在单独的 iosApp 文件夹中，而其他基于共享代码构建的应用程序则都位于 composeApp 中。

Android Gradle 插件 9.0 要求 Android 应用程序的入口点必须与共享代码位于不同的模块中，因为它不再支持在多平台模块中应用 Android 应用程序 Gradle 插件。

最后，我们此前针对基于 Gradle 的项目和基于 Amper 的项目采用了不同的结构。虽然 Gradle 支持在单个模块中配置多个应用程序，但 Amper 每个模块仅允许一个产品，因此基于 Amper 的项目已经为每个应用程序使用了独立的模块。

新结构的目标

基于以上几点，我们制定了新结构，并确立了以下目标：

• 为项目提供初始设置，使每个模块都有清晰的职责和单一的用途。对于项目中的任何一段代码或构建配置，都应能明确其放置位置。
• 保持结构尽可能一致，以适配向导所允许的不同配置：不同的目标平台组合、是否包含服务器应用程序，以及客户端选择原生 UI 还是共享 UI。
• 易于进一步模块化，根据需要从单个多平台模块扩展为多个模块。

适配其他配置

上述示例展示了 Compose Multiplatform 应用程序的新项目结构，该应用程序在 Android、iOS、桌面和 Web 平台之间共享 UI。在其他配置中，结构将根据需要进行调整，且改动极小。

包含原生 UI 的配置

Kotlin Multiplatform 支持在共享的 Kotlin 代码之上使用原生 UI。例如，你可以选择为 iOS 应用使用 SwiftUI，而为其他平台使用 Compose Multiplatform。在这种情况下，你将编写所有平台通用的共享业务逻辑代码，以及仅由特定平台使用的共享 UI 代码。

在这种配置下，新结构将拥有两个共享模块而不是一个：sharedLogic 和 sharedUI。sharedLogic 被所有应用程序引用且不包含 Compose 依赖，而 sharedUI 仅被那些使用 Compose Multiplatform 进行 UI 开发的应用程序引用。

[LOADING...]

决定在哪个模块中编写共享代码依然很简单：如果所有平台（包括使用原生 UI 实现的平台）都要使用它，则应放在 sharedLogic 中；如果只有使用 Compose Multiplatform 的平台需要该代码，则应放在 sharedUI 中。

包含服务器的配置

对于同时针对服务器端 Kotlin 的项目，新结构增加了一个 server 模块，并将所有客户端模块移动到嵌套的 app 文件夹中。项目根目录下的额外 core 模块允许你在服务器端和客户端代码之间共享代码，例如模型和验证逻辑。

[LOADING...]

更新现有项目

虽然我们正在更改新创建项目的默认结构，但现有项目并不强制采用完全相同的结构。如果你想将现有项目迁移到符合此新默认结构，可以使用迁移指南，其中展示了如何为每个入口点引入新模块。

请注意，与 Android Gradle 插件 9.0 相关的变更对于所有针对 Android 的现有多平台项目是强制性的。你可以在这篇博文中了解有关这些变更的更多信息以及如何更新你的项目。

若要在 IntelliJ IDEA 中获得 AGP 9.0 的支持，请升级至 2026.1.2 或更高版本，并使用最新版本的 Android 插件。

立即开始使用 KMP

若要使用更新后的结构创建新项目，请前往 kmp.new 或在你的 IDE 中使用 Kotlin Multiplatform 向导（在安装了 Kotlin Multiplatform 插件 的 IntelliJ IDEA 和 Android Studio 中均可用）。

如果你想查看新结构的实际应用示例，请参考 kotlinconf-app、KMP-App-Template 或 RSS Reader。