Compose Hot Reload
Compose Hot Reload 可帮助你在开发 Compose Multiplatform 项目时直观地查看并尝试 UI 更改。 与标准 Compose 预览(适用于通过测试数据查看隔离组件)不同,Compose Hot Reload 会直接将代码更改应用到正在运行的应用程序中。
捆绑的 Compose Hot Reload Gradle 插件需要 Kotlin 2.1.20+ 以及与 Java 21 或更早版本兼容的 JVM 目标。 要使用 Compose Hot Reload 的完整功能,建议安装 Kotlin Multiplatform IDE 插件,该插件自 2025.2.2 版本起适用于 IntelliJ IDEA,自 Otter 2025.2.1 版本起适用于 Android Studio。
在我们探索为其他目标添加支持的同时,你已经可以将桌面端应用作为沙盒,在不中断工作流的情况下快速尝试公共代码中的 UI 更改。

将 Compose Hot Reload 添加到项目中
可以通过两种方式添加 Compose Hot Reload:
从头创建
本节将指导你在 IntelliJ IDEA 和 Android Studio 中创建包含桌面端目标的多平台项目。创建项目后,系统会自动添加 Compose Hot Reload。
- 在快速入门指南中,按照说明设置用于 Kotlin Multiplatform 开发的环境。
- 在 IDE 中,选择 File | New | Project。
- 在左侧面板中,选择 Kotlin Multiplatform。
- 在 New Project 窗口中指定 Name、Group 和 Artifact 字段。
- 选择 Desktop 目标并点击 Create。

向现有项目添加
从 Compose Multiplatform 1.10.0 开始,Compose Hot Reload 插件已被捆绑,并且默认对所有包含桌面端目标的项目启用。
如果你的项目已经包含桌面端目标,你可以直接升级到 Compose Multiplatform 1.10.0 或更高版本,开箱即用体验 Compose Hot Reload 功能。
虽然它默认启用,但你仍可以显式声明 Compose Hot Reload 插件以使用特定的旧版本。
Compose Multiplatform 的早期版本
对于使用 1.10.0 之前版本的 Compose Multiplatform 项目,必须配置桌面端目标,然后显式添加 Compose Hot Reload 插件。 以下步骤以快速入门指南教程中的项目作为参考。
引入桌面端目标:创建
desktopApp目录,定义main()函数,并提供actual实现。 如果你的项目已经包含桌面端目标,可以跳过此步骤。 参考示例请参阅添加 JVM 入口点。在版本目录中更新 Compose Hot Reload 的最新版本(参见 Releases)。 在
gradle/libs.versions.toml中添加以下代码:tomlcomposeHotReload = { id = "org.jetbrains.compose.hot-reload", version.ref = "composeHotReload"}要了解有关如何使用版本目录跨项目集中管理依赖项的更多信息,请参阅我们的 Gradle 最佳做法。
在父项目的
build.gradle.kts(ComposeDemo/build.gradle.kts)中,将以下代码添加到plugins {}块中:kotlinplugins { alias(libs.plugins.composeHotReload) apply false }这样可以防止 Compose Hot Reload 插件在各个子项目中被多次加载。
在包含多平台应用程序的子项目的
build.gradle.kts(ComposeDemo/sharedUI/build.gradle.kts)中,将以下代码添加到plugins {}块中:kotlinplugins { alias(libs.plugins.composeHotReload) }你的项目必须在 JetBrains Runtime (JBR) 上运行,这是支持增强类重定义的 OpenJDK 复刻。 Compose Hot Reload 可以为你的项目自动配置兼容的 JBR。
最新的 JetBrains Runtime 仅支持 Java 21: 如果将 Compose Hot Reload 添加到仅兼容 Java 22 或更高版本的项目中, 运行项目会导致链接错误。
要允许自动配置,请将以下 Gradle 插件添加到
settings.gradle.kts文件中:kotlinplugins { id("org.gradle.toolchains.foojay-resolver-convention") version "1.2.0" }点击 Sync Gradle Changes 按钮同步 Gradle 文件:

使用 Compose Hot Reload
在
desktopApp源集中,打开main.kt文件并更新main()函数:kotlinfun main() = application { Window( onCloseRequest = ::exitApplication, alwaysOnTop = true, title = "composedemo", ) { App() } }通过将
alwaysOnTop变量设置为true,生成的桌面端应用将置顶于所有窗口之上,从而更方便修改代码并实时查看更改。打开
App.kt文件并更新Button可组合项:kotlinButton(onClick = { showContent = !showContent }) { Column { Text(Greeting().greet()) } }现在,按钮的文本由
greet()函数控制。打开
Greeting.kt文件并更新greet()函数:kotlinfun greet(): String { return "Hello!" }打开
main.kt文件,点击装订区域中的 Run 图标。 选择 Run 'desktopApp' with Compose Hot Reload。

修改
greet()函数返回的字符串,然后保存所有文件(⌘ S / Ctrl+S),即可看到桌面端应用自动更新。
或者,也可以通过按指定的快捷键或点击 Reload UI 按钮显式触发重载。 可以在 Settings | Tools | Compose Hot Reload 页面中修改触发行为。
祝贺你!你已经体验了 Compose Hot Reload 的实际运行效果。现在你可以尝试更改文本、图像、格式设置、UI 结构等内容,而无需在每次更改后都重新启动桌面运行配置。
适用于 AI Agent 的 MCP 服务器
从 Compose Multiplatform 1.12.0 开始,Compose Hot Reload 包含一个内置的 Model Context Protocol (MCP) 服务器。 该 MCP 服务器允许 AI 编码 Agent 与正在运行的 Compose 应用程序进行交互:触发 Compose Hot Reload、查看呈现的 UI、检查语义结构、模拟用户输入以及读取运行时日志。 对于具有多个窗口的应用程序,Agent 可以列出所有窗口并定位到其中的任意窗口。
这为 AI Agent 在编辑 Compose 代码时闭环了反馈循环。 Agent 无需依赖你在每次编辑后手动检查结果,而是可以自主迭代代码并验证每次更改。
连接 AI Agent
要连接 AI Agent,请将 MCP 客户端配置为运行 hotMcpServer Gradle 任务。 例如,在 .mcp.json 中配置:
{
"mcpServers": {
"compose-hot-reload": {
"command": "./gradlew",
"args": [
"--no-daemon",
"--quiet",
"--console=plain",
"hotMcpServer"
]
}
}
}Gradle 会在所有子项目中搜索任务,并将短名称 hotMcpServer 匹配到特定目标的变体,例如 hotMcpServerJvm 或 hotMcpServerDesktop。
如果模块定义了多个 JVM 目标,请指定完全限定的任务名称以避免歧义::<module>:hotMcpServer<Target>,例如 :app:hotMcpServerDesktop 或 :composeApp:hotMcpServerJvm。
可用的 MCP 工具
MCP 服务器公开了一系列 Agent 可以调用的工具,包括:
reload— 重新编译项目并热重载更改的类。take_screenshot— 捕获应用程序窗口的当前状态。get_semantic_tree— 返回 Compose 语义树,以便 Agent 理解 UI 结构。get_logs— 返回正在运行的应用程序的近期日志输出,包括运行时异常。click、type_text和scroll— 模拟用户输入以测试交互流程。
有关 MCP 工具及其参数的完整列表,请参阅 Compose Hot Reload README。
获取帮助
如果你在使用 Compose Hot Reload 时遇到任何问题,请通过创建 GitHub issue 告知我们。
