Kotlin Multiplatform 快速入门

通过本教程，您将学习如何构建并运行一个带 Compose Multiplatform UI 的简单 Kotlin Multiplatform 应用。

设置环境

首先从 IDE 和必要的插件开始：

1. 选择并安装 IDE：IntelliJ IDEA 和 Android Studio 都完全支持 Kotlin Multiplatform。

   推荐使用 JetBrains Toolbox App 来安装 IDE。 它可以让您管理多个产品或版本，包括抢先体验计划 (EAP) 和 Nightly 版本。

   对于独立安装，请下载 IntelliJ IDEA 或 Android Studio 的安装程序。

   Kotlin Multiplatform 要求的插件版本至少为 IntelliJ IDEA 2025.2.2 或 Android Studio Otter 2025.2.1。

2. 安装 Kotlin Multiplatform IDE 插件。

   IDE 插件还会安装您的 IDE 尚未安装的任何必要依赖项。

3. 如果您尚未设置 ANDROID_HOME 环境变量，请配置您的系统以识别它：

   Bash 或 ZshWindows PowerShell 或 CMD

   将以下命令添加到您的 .profile 或 .zprofile 中：

   export ANDROID_HOME=~/Library/Android/sdk

   对于 PowerShell，您可以使用以下命令添加持久环境变量（详情请参阅 PowerShell 文档）：

   [Environment]::SetEnvironmentVariable('ANDROID_HOME', '<path to the SDK>', 'Machine')

   对于 CMD，请使用 setx 命令：

   setx ANDROID_HOME "<path to the SDK>"

4. 若要创建 iOS 应用程序，您需要一台安装了 Xcode 的 macOS 主机。 您的 IDE 将在后台运行 Xcode 以构建 iOS 框架。

   在开始处理 KMP 项目之前，请确保至少启动过一次 Xcode，以便它完成初始设置。

   每次 Xcode 更新后，您都需要手动启动它并下载更新的工具包。 Kotlin Multiplatform IDE 插件会进行预检，并在 Xcode 处于非正常工作状态时向您发出警报。

创建项目

IntelliJ IDEAAndroid Studio

使用 IDE 向导创建一个新的 KMP 项目：

1. 在主菜单中选择 File | New | Project。

2. 在左侧列表中选择 Kotlin Multiplatform。

3. 根据需要设置项目名称、位置和其他基本属性。

4. 我们建议选择一个版本的 JetBrains Runtime (JBR) 作为项目的 JDK，因为它提供了重要的修复，特别是能够提高桌面端 KMP 应用的兼容性。 每个 IntelliJ IDEA 分发版中都包含相关的 JBR 版本，因此无需额外设置。

5. 若要创建一个完整的演示，请选择所有可用平台：Android、iOS、Desktop、Web 和 Server。 保留已选中的 Share UI 选项，以便在相应的目标平台上使用 Compose Multiplatform 作为 UI 框架。

   桌面端目标自动包含 Compose Hot Reload 功能，让您在保存代码更改后即可看到 UI 变化。 即使您不打算制作桌面应用，可能也想在项目中添加桌面目标，以加速 UI 代码的迭代。

6. 选择完平台后，点击 Create 按钮并等待 IDE 生成并导入项目。

使用 IDE 向导创建一个新的 KMP 项目：

1. 在主菜单中选择 File | New | New project。

2. 在默认的 Phone and Tablet 模板类别中选择 Kotlin Multiplatform。

   

3. 根据需要设置项目名称、位置和其他基本属性，然后点击 Next。

4. 若要创建一个完整的演示，请选择所有可用平台：Android、iOS、Desktop、Web 和 Server。 保留已选中的 Share UI 选项，以便在相应的目标平台上使用 Compose Multiplatform 作为 UI 框架。

   桌面端目标自动包含 Compose Hot Reload 功能，让您在保存代码更改后即可看到 UI 变化。 即使您不打算制作桌面应用，可能也想在项目中添加桌面目标，以加速 UI 代码的迭代。

5. 选择完平台后，点击 Finish 按钮并等待 IDE 生成并导入项目。

查看预检

您可以通过打开 Project Environment Preflight Checks 工具窗口，确保项目设置没有环境问题： 点击右侧边栏或底部栏上的预检图标

在此工具窗口中，您可以查看与这些检查相关的消息、重新运行检查或更改其设置。

预检命令在 Search Everywhere 对话框中也可用。 双击 键并搜索包含“preflight”一词的命令：

运行示例应用

IDE 向导创建的项目包含为 iOS、Android、桌面和 Web 应用程序生成的运行配置，以及用于运行服务器应用的 Gradle 任务。下面列出了每个平台的具体 Gradle 命令。

AndroidiOSDesktopWeb

要运行 Android 应用，请启动 androidApp 运行配置：

若要手动创建 Android 运行配置，请选择 Android App 作为运行配置模板，并选择模块 [项目名称].androidApp。

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

您需要一台 macOS 主机并安装 Xcode 才能构建 iOS 应用。

如果您为项目选择了 iOS 目标，并在一台安装了 Xcode 的 macOS 计算机上进行了设置，则可以选择 iosApp 运行配置并选择一个模拟设备：

当您运行 iOS 应用时，它会在后台由 Xcode 构建并在 iOS 模拟器中启动。第一次构建会收集用于编译的原生依赖项，并为后续运行预热构建：

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

若要手动创建带 Hot Reload 的桌面运行配置，请选择 Gradle 运行配置模板，并使用以下命令指向 [应用名称]:desktopApp Gradle 项目：

hotRun --mainClass "com.example.demo.MainKt"

使用此配置，您可以运行 JVM 桌面应用：

Web 应用的默认运行配置创建为 webApp [wasmJs]：

若要手动创建 Web 运行配置，请选择 Gradle 运行配置模板，并使用以下命令指向 [应用名称]:webApp Gradle 项目：

wasmJsBrowserDevelopmentRun

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

故障排除

Java 和 JDK

Java 的常见问题：

• 某些工具可能找不到要运行的 Java 版本，或者使用了错误的版本。 要解决此问题：

  • 将 JAVA_HOME 环境变量设置为安装了适当 JDK 的目录。

    我们建议使用 JetBrains Runtime，这是一个支持类重定义的 OpenJDK 分支。

  • 将 JAVA_HOME 内 bin 文件夹的路径添加到 PATH 变量中，以便在终端中使用 JDK 中包含的工具。

• 如果在 Android Studio 中遇到 Gradle JDK 问题，请确保其配置正确：选择 Settings | Build, Execution, Deployment | Build Tools | Gradle。

Android 工具

与 JDK 相同，如果您在启动 adb 等 Android 工具时遇到困难，请确保 ANDROID_HOME/tools、ANDROID_HOME/tools/bin 和 ANDROID_HOME/platform-tools 的路径已添加到您的 PATH 环境变量中。

Xcode

如果您的 iOS 运行配置报告没有可运行的虚拟设备，或者预检失败，请务必启动 Xcode 并查看 iOS 模拟器是否有任何更新。

获取帮助

• Kotlin Slack。获取邀请并加入 #multiplatform 频道。
• Kotlin Multiplatform 工具问题跟踪器。报告新问题。

下一步

详细了解 KMP 项目的结构以及编写共享代码：

• 关于使用 Compose Multiplatform 处理共享 UI 代码的一系列教程：创建您的 Compose Multiplatform 应用
• 关于在带原生 UI 的项目中处理共享代码的一系列教程：创建您的 Kotlin Multiplatform 应用
• 深入研究 Kotlin Multiplatform 文档：
  • 项目配置
  • 处理多平台依赖项
• 了解 Compose Multiplatform UI 框架、其基础知识以及特定于平台的特性： Compose Multiplatform 与 Jetpack Compose 之间的关系。

发现已经为 KMP 编写的代码：

• 我们的示例页面，包含 JetBrains 官方示例以及展示 KMP 能力的精选项目列表。
• GitHub 话题：
  • kotlin-multiplatform，使用 Kotlin Multiplatform 实现的项目。
  • kotlin-multiplatform-sample，使用 KMP 编写的示例项目列表。
• klibs.io – KMP 库搜索平台，目前已索引 2000 多个库，包括 OkHttp、Ktor、Coil、Koin、SQLDelight 等。