构建并运行 Kotlin Multiplatform 应用程序
Kotlin Multiplatform (KMP) 使用 Gradle 作为其构建系统。 适用于 IntelliJ IDEA 和 Android Studio 的 KMP IDE 插件 提供了进一步的支持,能够自动创建定制的运行配置、处理 Compose Hot Reload 集成等。
构建并运行 KMP 应用程序
要构建您的 KMP 应用,只需 Gradle 和 Java。 然而,IntelliJ IDEA 和 Android Studio 为 KMP 开发提供了许多便利性功能, 涵盖从管理环境到编写构建脚本以及多平台代码的方方面面。
您可以使用同一个 IDE 在任何受支持的平台上运行应用程序:
- Android 应用运行在可用的 Android 虚拟设备(Android Virtual Devices)上。
- iOS 应用运行在 Device Hub 中可用的 iOS 模拟器上 (您需要一台装有 Xcode 的 macOS 计算机才能在 Apple 目标平台上运行应用)。
- 桌面应用运行在系统 JVM 上。
- Web 应用在默认浏览器中运行。
KMP IDE 插件提供的运行配置比通用的 Gradle 构建任务更高效: 它们仅触发相应目标的构建,而默认的 Gradle 构建任务始终会构建所有目标的调试版(Debug)和发布版(Release)。
在 Android 模拟器上运行应用程序
默认运行配置会自动建议可用 Android 虚拟设备的列表。 如果没有可用设备,或者您想模拟其他设备,可以使用 Android 设备管理器进行配置 (在 IntelliJ IDEA 中,选择 View | Tool Windows | Device Manager, 或参考 Android Studio 指南)。
Android Studio 中的设备管理器通常提供更广泛的可用设备集, 但创建设备后,该设备在系统范围均可用——包括 IntelliJ IDEA 中的运行配置。
设备创建完成后,便会立即在运行配置中可用。
- 在运行配置列表中,选择 androidApp。
- 选择您的 Android 虚拟设备,然后点击 Run:

IDE 会运行该应用;如果所选虚拟设备处于关机状态,则会自动启动它。
在真实 Android 设备上运行
要使硬件 Android 设备在 KMP 运行配置中可用,请对其进行配置并连接到您的计算机。
配置正确后,它将与虚拟设备一起显示在可用设备列表中。
在 iOS 模拟器上运行应用程序
如果尚未在初始设置过程中启动过 Xcode,请在运行 iOS 应用之前启动它。 安装 iOS 平台支持: 在 Xcode 中,检查 Xcode | Settings | Components,确保至少安装了一个 iOS 模拟器。
在 Kotlin Multiplatform IDE 中,在运行配置列表中选择 iOS 条目, 并从旁边的列表中选择模拟设备, 然后点击 Run:

在真实 iOS 设备上运行
您可以在真实 iOS 设备上运行多平台应用程序。在开始之前, 您需要设置与您的 Apple ID 关联的 Team ID。
设置 Team ID
若要首次为项目设置新的 Team ID,请在 Xcode 中打开项目 (File | Open Project in Xcode):
在左侧的 Project 导航器中,选择 iosApp。
在 Targets 下选择 iosApp,并切换到 Signing & Capabilities 选项卡。
在 Team 列表中,选择您的团队。
如果您尚未设置团队,请使用 Team 列表中的 Add an Account 选项并按照 Xcode 中的说明操作。
确保 Bundle Identifier 唯一,并且已成功分配 Signing Certificate(签名证书)。
在 Xcode 中设置团队后,即可在 IntelliJ IDEA 中设置或更改团队:
编辑 iosApp 的运行配置:

切换到 Options 选项卡,并在 Development team 下拉菜单中进行必要的更改,然后点击 OK。
运行应用
使用线缆连接 iPhone。如果您已在 Xcode 中注册该设备,IntelliJ IDEA 应会在运行配置列表中显示它。运行对应的 iosApp 配置。
如果您尚未在 Xcode 中注册 iPhone,请遵循 Apple 的建议。 简而言之,您应当:
- 使用线缆连接 iPhone。
- 在 iPhone 上,前往 Settings | Privacy & Security 启用开发者模式。
- 在 Xcode 中,转到顶部菜单并选择 Window | Devices and Simulators。
- 如果未显示 iPhone 已连接,请点击左下角的加号并选择该设备。
- 按照屏幕上的说明完成配对流程。
在 Xcode 中注册 iPhone 后,当您选择 iosApp 运行配置时,它就会出现在 IntelliJ IDEA 的可用设备列表中。
在桌面上运行应用程序
在运行配置列表中选择 desktopApp [hot] 🔥 并点击 Run:

默认情况下,应用在启动时会同时运行 Compose Hot Reload。 这使得在手动保存包含更改的文件时,几乎能即时重新加载 UI。
运行 Web 应用程序
Web 目标的默认选项包括:
- webApp[js]:运行 Kotlin/JS 应用程序。
- webApp[wasmJs]:运行 Kotlin/Wasm 应用程序。
Web 应用程序会在默认浏览器中自动打开, 并且默认可通过 http://localhost:8080/ 访问。
如果端口 8080 不可用,构建将使用其他端口。 您可以在 Gradle 构建控制台中搜索 Project is running at 找到实际端口。

Web 目标的兼容模式
您可以为 Web 应用程序启用兼容模式,以确保它能够开箱即用地在所有浏览器上运行。 在该模式下,现代浏览器将使用 Wasm 版本,而较旧的浏览器则回退到 JS 版本。 该模式通过针对 js 和 wasmJs 目标的交叉编译来实现。
要为 Web 应用程序启用兼容模式:
通过选择 View | Tool Windows | Gradle 打开 Gradle 工具窗口。
在 ComposeDemo | Tasks | compose 中,选择并运行 composeCompatibilityBrowserDistribution 任务。
Gradle JVM 至少需要 Java 11 才能成功加载任务;对于一般的 Compose Multiplatform 项目,我们建议至少使用 Java 17。

或者,您也可以在终端中从根项目目录运行以下命令:
bash./gradlew composeCompatibilityBrowserDistribution
Gradle 任务完成后,兼容的工件将生成在 Web 应用程序模块目录中,例如: webApp/build/dist/composeWebCompatibility/productionExecutable。 您可以使用这些工件为 js 和 wasmJs 目标发布应用程序。
