Compose Multiplatform Desktop Hot Reload 配置

问题背景 Link to heading

需要为 Kotlin Multiplatform 项目配置 Compose Desktop 的热重载功能，以提升开发效率。

官方资料 Link to heading

官方文档：https://github.com/JetBrains/compose-hot-reload，现在还是Alpha版

配置过程 Link to heading

1. 添加热重载插件 Link to heading

在 composeApp/build.gradle.kts 中添加插件：

plugins {
    alias(libs.plugins.kotlinMultiplatform)
    alias(libs.plugins.androidApplication)
    alias(libs.plugins.composeMultiplatform)
    alias(libs.plugins.composeCompiler)
    id("org.jetbrains.compose.hot-reload") version "1.0.0-alpha05"  // 添加这行
}

2. 配置 Foojay 解析器以自动提供 JetBrains Runtime Link to heading

重要：Compose Hot Reload 功能必须运行在 JetBrains Runtime (JBR) 上。JBR 是 OpenJDK 的一个特殊分支，支持增强的类重定义功能，这是热重载所必需的。

在项目的 settings.gradle.kts 文件中添加：

plugins {
    id("org.gradle.toolchains.foojay-resolver-convention") version "0.9.0"
}

添加此插件后，Gradle 工具链可以自动下载和设置兼容的 JetBrains Runtime，无需手动安装。Compose Hot Reload Gradle 插件会声明其对 JBR 的需求，而 Foojay 解析器插件则会帮助 Gradle 工具链自动查找并下载满足此需求的 JetBrains Runtime。

3. 配置热重载任务 Link to heading

使用 ComposeHotRun 类型的任务：

tasks.register<ComposeHotRun>("runHot") {
    mainClass.set("xyz.emuci.easyqc.MainKt")
}

其中 mainClass 需要提供完全限定类名（包名+类名）。Kotlin 文件被编译后，文件名会转换为相应的类名，按照 Kotlin 的命名约定，main.kt 文件会编译为 MainKt 类。例如，对于位于 src/desktopMain/kotlin/com/example/app/main.kt 的文件，其完全限定类名应为 com.example.app.MainKt 。

4. 解决 JDK 依赖问题 Link to heading

配置了 Foojay 解析器，可能会报错：

Failed to calculate the value of task ':composeApp:runHot' property 'javaLauncher'.
Cannot find a Java installation on your machine (Mac OS X 15.3.2 x86_64) matching: {languageVersion=21, vendor=JetBrains, 
implementation=vendor-specific}

错误详情：

Some toolchain resolvers had provisioning failures: foojay (Unable to download toolchain matching the requirements ({languageVersion=21, 
vendor=JetBrains, implementation=vendor-specific}) from 'https://api.foojay.io/disco/v3.0/ids/98d36508a72a380b6e0ec39201e064d3/redirect', due to: Could 
not get resource 'https://api.foojay.io/disco/v3.0/ids/98d36508a72a380b6e0ec39201e064d3/redirect'.)

出现这个问题的首要解决步骤是检查是否已经正确配置了 JVM 工具链。在 composeApp/build.gradle.kts 中添加：

kotlin {
    jvmToolchain(21)
}

这一配置通常能解决大多数 JDK 依赖问题。如果问题仍然存在，可能需要进一步考虑：

配置必要的 JVM 参数
手动安装 JetBrains Runtime 21（见下文安装选项）

最终配置 Link to heading

完整的 composeApp/build.gradle.kts 配置：

plugins {
    alias(libs.plugins.kotlinMultiplatform)
    alias(libs.plugins.androidApplication)
    alias(libs.plugins.composeMultiplatform)
    alias(libs.plugins.composeCompiler)
    id("org.jetbrains.compose.hot-reload") version "1.0.0-alpha05"
}

kotlin {
    jvmToolchain(21)
}

tasks.register<ComposeHotRun>("runHot") {
    mainClass.set("xyz.emuci.easyqc.MainKt")
    jvmArgs.set(listOf("-Djdk.module.illegalAccess=permit"))
}

JetBrains Runtime 21 安装选项 Link to heading

如果自动下载失败，可以尝试以下手动安装方法：

直接下载：
- 访问 https://github.com/JetBrains/JetBrainsRuntime/releases
- 下载对应系统版本的 JBR 21
使用 SDKMAN 安装：

sdk install java 21-jetbrains
sdk use java 21-jetbrains

使用 IntelliJ IDEA 自带的 JBR：
- 位置通常在 IntelliJ IDEA.app/Contents/jbr（macOS）
- 设置 JAVA_HOME 指向此目录

运行方式 Link to heading

配置完成后，使用以下命令运行：

./gradlew :composeApp:runHot

总结 Link to heading

通过这次配置，我们：

学习了 Compose Desktop 热重载的配置方法
了解了 JetBrains Runtime 对热重载功能的重要性
配置了自动下载 JBR 的 Foojay 解析器
理解了 Kotlin 文件到类的映射规则
解决了可能出现的 JDK 版本依赖问题
成功实现了热重载功能

热重载功能的正确配置大大提升了开发效率，使我们能够实时预览代码修改的效果。