Skip to content

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 添加到项目中 ​

可以通过两种方式添加 Compose Hot Reload:

从头创建 ​

本节将指导你在 IntelliJ IDEA 和 Android Studio 中创建包含桌面端目标的多平台项目。创建项目后,系统会自动添加 Compose Hot Reload。

  1. 在快速入门指南中,按照说明设置用于 Kotlin Multiplatform 开发的环境。
  2. 在 IDE 中,选择 File | New | Project。
  3. 在左侧面板中,选择 Kotlin Multiplatform。
  4. 在 New Project 窗口中指定 Name、Group 和 Artifact 字段。
  5. 选择 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 插件。 以下步骤以快速入门指南教程中的项目作为参考。

  1. 引入桌面端目标:创建 desktopApp 目录,定义 main() 函数,并提供 actual 实现。 如果你的项目已经包含桌面端目标,可以跳过此步骤。 参考示例请参阅添加 JVM 入口点。

  2. 在版本目录中更新 Compose Hot Reload 的最新版本(参见 Releases)。 在 gradle/libs.versions.toml 中添加以下代码:

    toml
    composeHotReload = { id = "org.jetbrains.compose.hot-reload", version.ref = "composeHotReload"}

    要了解有关如何使用版本目录跨项目集中管理依赖项的更多信息,请参阅我们的 Gradle 最佳做法。

  3. 在父项目的 build.gradle.kts(ComposeDemo/build.gradle.kts)中,将以下代码添加到 plugins {} 块中:

    kotlin
    plugins {
        alias(libs.plugins.composeHotReload) apply false
    }

    这样可以防止 Compose Hot Reload 插件在各个子项目中被多次加载。

  4. 在包含多平台应用程序的子项目的 build.gradle.kts(ComposeDemo/sharedUI/build.gradle.kts)中,将以下代码添加到 plugins {} 块中:

    kotlin
    plugins { 
        alias(libs.plugins.composeHotReload)
    }
  5. 你的项目必须在 JetBrains Runtime (JBR) 上运行,这是支持增强类重定义的 OpenJDK 复刻。 Compose Hot Reload 可以为你的项目自动配置兼容的 JBR。

    最新的 JetBrains Runtime 仅支持 Java 21: 如果将 Compose Hot Reload 添加到仅兼容 Java 22 或更高版本的项目中, 运行项目会导致链接错误。

    要允许自动配置,请将以下 Gradle 插件添加到 settings.gradle.kts 文件中:

    kotlin
    plugins {
        id("org.gradle.toolchains.foojay-resolver-convention") version "1.2.0"
    }
  6. 点击 Sync Gradle Changes 按钮同步 Gradle 文件:同步 Gradle 文件

使用 Compose Hot Reload ​

  1. 在 desktopApp 源集中,打开 main.kt 文件并更新 main() 函数:

    kotlin
    fun main() = application {
        Window(
            onCloseRequest = ::exitApplication,
            alwaysOnTop = true,
            title = "composedemo",
        ) {
            App()
        }
    }

    通过将 alwaysOnTop 变量设置为 true,生成的桌面端应用将置顶于所有窗口之上,从而更方便修改代码并实时查看更改。

  2. 打开 App.kt 文件并更新 Button 可组合项:

    kotlin
    Button(onClick = { showContent = !showContent }) {
        Column {
            Text(Greeting().greet())
        }
    }

    现在,按钮的文本由 greet() 函数控制。

  3. 打开 Greeting.kt 文件并更新 greet() 函数:

    kotlin
     fun greet(): String {
         return "Hello!"
     }
  4. 打开 main.kt 文件,点击装订区域中的 Run 图标。 选择 Run 'desktopApp' with Compose Hot Reload。

    从装订区域运行 Compose Hot Reload

    桌面应用上的首次 Compose Hot Reload

  5. 修改 greet() 函数返回的字符串,然后保存所有文件(⌘ S / Ctrl+S),即可看到桌面端应用自动更新。

    Compose Hot Reload

    或者,也可以通过按指定的快捷键或点击 Reload UI 按钮显式触发重载。 可以在 Settings | Tools | Compose Hot Reload 页面中修改触发行为。

祝贺你!你已经体验了 Compose Hot Reload 的实际运行效果。现在你可以尝试更改文本、图像、格式设置、UI 结构等内容,而无需在每次更改后都重新启动桌面运行配置。

Experimental

适用于 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 中配置:

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 告知我们。