Kotlin Multiplatform 快速入门
在本教程中,你将学习如何构建并运行一个带有 Compose Multiplatform UI 的简单 Kotlin Multiplatform 应用。
选择构建工具
本快速入门指南使用 Gradle 在 IDE 中创建并运行新的 Kotlin Multiplatform 项目。 Gradle 既支持新项目,也支持已在使用它的现有项目。 本快速入门指南专为希望将 Kotlin Multiplatform 引入其项目,或仅仅希望使用熟悉环境的 Gradle 用户而设计。
对于全新的项目,你还可以尝试使用 Kotlin Toolchain, 这是 JetBrains 专为 Kotlin Multiplatform 打造的一款工具。 它提供了命令行以及透明的配置格式,非常适合 AI 工作流。
使用 Kotlin Toolchain 开始使用 KMPKotlin Toolchain 是 JetBrains 推出的一款用于构建、测试、运行和发布 Kotlin 项目的工具。 它提供了 CLI 和声明式配置,因此你可以在终端、IDE 或 AI 辅助开发工具中工作: Kotlin Toolchain 允许你的编码 Agent(coding agent)只需极少设置和配置即可从新建项目一路推进到应用发布。环境配置
配置 IntelliJ IDEA 或 Android Studio、ANDROID_HOME 变量以及 Xcode:
选择并安装 IDE:IntelliJ IDEA 和 Android Studio 均完全支持 KMP。
建议使用 JetBrains Toolbox app 安装 IDE。 对于独立安装,请下载适用于 IntelliJ IDEA 或 Android Studio 的安装程序。
为获得最佳效果,请使用最新的稳定版本。
安装 Kotlin Multiplatform IDE 插件。 你可以在插件市场(Settings | Plugins | Marketplace)中找到它, 也可以从插件网页进行安装。
如果尚未设置
ANDROID_HOME环境变量,请配置系统使其识别该变量:将以下命令添加到你的
.profile或.zprofile文件中:shellexport ANDROID_HOME=~/Library/Android/sdk对于 PowerShell,可以使用以下命令添加持久化环境变量 (详情请参阅 PowerShell 文档):
shell[Environment]::SetEnvironmentVariable('ANDROID_HOME', '<path to the SDK>', 'Machine')对于 CMD,请使用
setx命令:shellsetx ANDROID_HOME "<path to the SDK>"要创建 iOS 应用程序,需要一台安装了 Xcode 的 macOS 计算机。 IDE 会在底层运行 Xcode 来构建 iOS 框架。
在开始处理 KMP 项目之前,请确保至少启动过一次 Xcode,以便其完成 初始设置。
每次更新 Xcode 时,都必须手动启动它并下载更新的工具。 Kotlin Multiplatform IDE 插件会进行预检,在 Xcode 配置不正确时向你发出提醒。
创建项目
使用 Kotlin Multiplatform 生成器创建项目:
在主菜单中选择 File | New | Project。
在左侧列表中选择 Kotlin Multiplatform。 根据需要设置 Name 和 Location。 Project ID 会基于名称自动生成。
本页面的其余部分均基于 Gradle 项目进行说明:请确保在 Build system 开关中选中了该项以继续。
要体验所有受支持的平台,请勾选 Android、iOS、Desktop、Web 和 Server。 在 UI implementation 选项中,保持选中 Share UI,以便在对应的目标平台上使用 Compose Multiplatform 作为 UI 框架。
桌面端目标会自动包含 Compose Hot Reload 功能,该功能允许你在保存代码更改时立即看到 UI 变化。 即使你并不打算开发桌面端应用,也可以将桌面端目标添加到项目中,以加快 UI 代码的迭代速度。
点击 Create 按钮,等待 IDE 生成并导入项目。

使用向导创建新项目:
在主菜单中选择 File | New | New project。
在默认的 Phone and Tablet 模板类别中选择 Kotlin Multiplatform。

根据需要设置项目名称、软件包名称和保存位置,然后点击 Next。 Build configuration language 应保持设置为 Kotlin DSL。
要创建一个完整的演示项目,请选择所有可用平台:Android、iOS、Desktop、Web 和 Server。 在有对应选项的地方保持勾选 Share UI,以便在对应的目标平台上使用 Compose Multiplatform 作为 UI 框架。
桌面端目标会自动包含 Compose Hot Reload 功能,该功能允许你在保存代码更改时立即看到 UI 变化。 即使你并不打算开发桌面端应用,也可以将桌面端目标添加到项目中,以加快 UI 代码的迭代速度。
点击 Finish 按钮,等待 IDE 生成并导入项目。

你可以在 shared 模块中找到跨平台共享的代码。 Platform.kt 文件包含一个用于获取平台名称的 expect 声明。
当你在不同平台上运行应用时,可以看到相同的 UI 布局显示着由原生调用提供的不同平台名称。
查看预检结果
为确保项目配置不存在环境问题, 请打开 Project Environment Preflight Checks 工具窗口: 点击右侧边栏或底部栏上的预检图标
。
在此工具窗口中,你可以查看哪些检查已通过、重新运行检查或更改其设置。 通常,只有在检测到问题时该窗口才会自动打开,其余时候保持隐藏。
预检命令也可以在 Search Everywhere 对话框中使用。 双击 Shift 键并搜索包含“preflight”一词的命令:

生成项目中的模块
根据你在 Kotlin Multiplatform 向导中选择的平台组合, 在 IDE 导入项目后,你将看到以下模块:
androidApp:用于构建 Android 应用程序的模块。
desktopApp:用于构建桌面端 JVM 应用程序的模块。
iosApp:用于构建 iOS 应用程序的 Xcode 项目。它依赖并使用 shared 模块作为 iOS 框架。
shared:一个 Kotlin Multiplatform 模块,包含 Android、桌面端、iOS 和 Web 应用程序的通用代码。
webApp:用于构建 Web 应用程序的模块,同时支持 Kotlin/JS 和 Kotlin/Wasm。
server 与 core 模块仅针对服务端平台创建: core 保存服务端和客户端应用之间共享的代码; server 用于配置端点。
选中服务端平台后,IDE 会将应用程序入口点归类在
app目录下。 否则,应用模块将直接创建在项目根目录下。
shared 模块会针对每个目标分别进行编译。 例如,在构建 Android 应用时,它会被视为 Kotlin/JVM 模块;在构建 iOS 应用时,则会被视为 Kotlin/Native 模块。
运行示例应用
IDE 向导创建的项目包含了为 iOS、Android、 桌面端和 Web 应用程序自动生成的运行配置,以及用于运行服务端应用的 Gradle 任务。
要启动运行配置,请在 IDE 右上角找到下拉菜单, 然后点击 Run 按钮:
要运行 Android 应用,请启动 androidApp 运行配置:

默认情况下,它会在第一个可用的虚拟设备上运行:

要手动创建 Android 运行配置(Run | Edit Configurations), 请选择 Android App 作为运行配置模板,并选择模块 [project name].androidApp。
你需要一台安装了 Xcode 的 macOS 计算机来构建 iOS 应用。
选择 iosApp 运行配置和模拟设备:

该运行配置会在底层使用 Xcode 构建 iOS 应用,并通过 iOS 模拟器启动它。 首次构建时会收集原生依赖项并缓存构建数据,从而加快后续运行速度:

桌面端应用的默认运行配置创建为 desktopApp [hot] 🔥:

使用此配置,你可以运行 JVM 桌面端应用:

要手动创建支持 Hot Reload 的桌面端运行配置(Run | Edit Configurations), 请选择 Gradle 运行配置模板,并通过以下命令指向 [app name]:desktopApp Gradle 项目:
hotRun --mainClass "com.example.demo.MainKt"默认情况下,会为 Web 创建两个运行配置:webApp [wasmJs] 和 webApp [js]。 两者分别使用 Kotlin/Wasm 或 Kotlin/JS 构建并运行同一个应用:

运行此配置时,IDE 会构建 Kotlin/Wasm 应用并在默认浏览器中将其打开:

要手动创建 Web 运行配置,请选择 Gradle 运行配置模板,并通过 wasmJsBrowserDevelopmentRun 任务指向 [app name]:webApp Gradle 项目;对于 Kotlin/JS 版本,则使用 jsBrowserDevelopmentRun 任务。
故障排除
Kotlin Multiplatform 配置出现的问题通常是由于 Java、Android SDK 或 Xcode 配置不当引起的。
Java 和 JDK
以下是与 Java 配置相关的最常见问题:
- 某些工具可能找不到 Java 安装路径或使用了错误的版本。 要解决此问题,请将
JAVA_HOME环境变量设置为安装相应 JDK 的目录 (我们建议使用 JetBrains Runtime), 然后将JAVA_HOME内的bin文件夹路径追加到PATH变量中。 - 如果在 Android Studio 中遇到 Gradle JDK 的问题,请确保其配置正确: 选择 Settings | Build, Execution, Deployment | Build Tools | Gradle。
Android 工具
如果在启动 adb 等 Android 工具时遇到问题, 请确保已将 ANDROID_HOME/tools、ANDROID_HOME/tools/bin 和 ANDROID_HOME/platform-tools 的路径添加到 PATH 环境变量中。
Xcode
如果你的 iOS 运行配置报告没有可运行的虚拟设备,或者预检失败, 请务必启动 Xcode 并检查是否有 iOS SDK 更新。
获取帮助
- Kotlin Slack:获取邀请并加入 #multiplatform 频道。
- Kotlin Multiplatform Tooling 问题跟踪器:报告新问题。
后续步骤
详细了解 KMP 项目的结构以及编写共享代码:
- 完全共享代码:时区选择器应用:初学者教程,教你如何使用 Compose Multiplatform 处理共享 UI 代码。
- 原生 UI:REST API 请求的共享逻辑:初学者教程,教你如何在具有原生 UI 代码的多平台项目中处理共享代码。
深入了解特定的 Kotlin Multiplatform 用例:
- 处理多平台依赖项
- 围绕多平台工件组织代码和工件
- 了解 Compose Multiplatform UI 框架及其在 Compose 生态系统中的定位:Compose Multiplatform 与 Jetpack Compose 的关系
探索已为 KMP 编写的代码:
- 示例:JetBrains 官方示例以及展示 KMP 功能的精选项目列表。
- GitHub 主题:
- kotlin-multiplatform:使用 Kotlin Multiplatform 实现的项目。
- kotlin-multiplatform-sample:使用 KMP 编写的示例项目列表。
- klibs.io:KMP 库的搜索平台。 它对 GitHub 上的项目以及 Maven Central 上的构件进行索引,支持对搜索结果进行精细筛选, 并提供对 AI 工作流的支持。
