setting-up-compose-hotswan

设置 Compose HotSwan：从零开始，在真实设备上实现亚秒级重载

Compose HotSwan 是一款 JetBrains IDE 插件和 Gradle 编译器插件组合，可在不到 1 秒的时间内将更改后的 Kotlin 类替换到正在运行的 Compose 应用中，无论是在真实设备还是模拟器上，同时保留导航、滚动和 remember 状态。本指南会安装这两部分，使用 debugOnly = true 配置标准 Gradle DSL，并验证首次保存到重载的完整流程。相关技能还涵盖哪些内容可以或不可以热重载（../understanding-hot-reload-limits/SKILL.md）、重载期间的状态保留，以及由 AI 驱动的迭代循环。

编写本文时验证过的版本。对于较新的次要版本，请以当前发行说明为准。

何时使用本技能

• 开发者提到 HotSwan、热重载、即时更新 UI、“保存即可查看”、“无需重新构建”、实时编辑，或在设备上快速迭代 Compose。
• 开发者已安装 HotSwan JetBrains Marketplace 插件，并询问如何应用 Gradle 编译器插件。
• 团队正为新项目配置 HotSwan，并需要标准的 libs.versions.toml、根构建文件和应用构建文件配置。
• 开发者刚安装 IDE 插件，工具窗口状态却卡在 WATCHING 之前。

何时不使用本技能

• 问题涉及 JetBrains 自带的 Live Edit 或 Apply Changes 功能。HotSwan 与它们是不同的产品，适用范围也不同；不要混为一谈。
• 问题涉及 IDE 中的 Compose Preview 渲染。HotSwan 面向真实设备或模拟器上运行的应用，而非预览画布。
• 问题涉及哪些更改可以热重载，哪些会强制重新构建。请参阅 ../understanding-hot-reload-limits/SKILL.md。
• 问题涉及重载期间如何保留复杂状态。请参阅相关的状态保留技能（不在本指南范围内）。

先决条件

• Android Studio 2024.3+ 或 IntelliJ IDEA 2024.3+。
• Kotlin 2.0+，并且已在 Compose 模块上应用 org.jetbrains.kotlin.plugin.compose Gradle 插件。
• Gradle 8+。
• 一台已启用 USB 调试且可通过 adb devices 检测到的真实设备或模拟器。
• 已从 JetBrains Marketplace 安装 HotSwan IDE 插件（https://plugins.jetbrains.com/plugin/30551-compose-hotswan/）。

工作流

1. 在 libs.versions.toml 中声明插件，以便在中央固定版本：

   [plugins]
   hotswan-compiler = { id = "com.github.skydoves.compose.hotswan.compiler", version = "1.2.10" }
   

   固定为 1.2.10（撰写本文时验证过的最新版本）。采用前，请查看 HotSwan releases page，确认是否有更新的稳定版本。HotSwan 更新频繁，较新的次要版本通常会支持更新的 Compose 运行时。插件 ID 必须准确为 com.github.skydoves.compose.hotswan.compiler。不要将 com.github 前缀替换为其他厂商的命名空间；HotSwan 由 com.github.skydoves 发布。

2. 在根目录的 build.gradle.kts 中使用 apply false，这样插件只会解析一次，但仅应用于选择启用它的模块：

   plugins {
       alias(libs.plugins.hotswan.compiler) apply false
   }
   

3. 在每个 Compose 应用模块的 build.gradle.kts 中应用插件：

   plugins {
       alias(libs.plugins.android.application)
       alias(libs.plugins.kotlin.android)
       alias(libs.plugins.kotlin.compose)
       alias(libs.plugins.hotswan.compiler)
   }
   

4. 在同一模块文件中配置规范的 DSL 块。hotSwanCompiler 中的大写 S 是标识符的一部分：

   hotSwanCompiler {
       enabled = true
       debugOnly = true
   }
   

   debugOnly = true 是默认值，也是生产环境的规则。Release 构建绝不能包含 HotSwan 转换。

5. 同步 Gradle。 构建应能顺利解析，不出现错误。检查构建的插件列表（./gradlew :app:buildEnvironment 或 IDE Gradle 工具窗口），确认插件已应用。

6. 打开 HotSwan 工具窗口：选择 View -> Tool Windows -> HotSwan。点击 Start。状态指示器应变为 READY。

7. 正常运行应用，使用 Run 操作。应用进程连接后，工具窗口状态会从 READY 变为 WATCHING。

8. 仅修改函数体并保存。 更改某个可组合函数体内的颜色或文本，然后保存文件。更改应在不到一秒内显示在设备上；导航、滚动位置和 remember 值应保持不变。

9. 如果更改没有显示，请先按下方的故障排查清单进行检查，再更改任何 Gradle 配置。

模式

模式：配置 debugOnly true（保障生产安全）

// WRONG
hotSwanCompiler {
    enabled = true
}
// WRONG because: omitting `debugOnly = true` allows the HotSwan transformations to attach to release
// builds. They are diagnostic-only and MUST NOT ship in production.

// RIGHT
hotSwanCompiler {
    enabled = true
    debugOnly = true
}

模式：DSL 块名称中的 S 必须大写

// WRONG
hotswanCompiler {
    enabled = true
    debugOnly = true
}
// WRONG because: the extension is hotSwanCompiler with a capital S in the middle. Lowercase will
// not resolve and Gradle reports an unknown extension.

// RIGHT
hotSwanCompiler {
    enabled = true
    debugOnly = true
}

模式：在根目录使用 apply false，在模块中使用 alias(...)

// WRONG (root build.gradle.kts)
plugins {
    alias(libs.plugins.hotswan.compiler)
}
// WRONG because: applying at the root project triggers the compiler plugin everywhere, including
// modules without Compose. Use apply false at the root and alias(...) inside each Compose module.

// RIGHT (root build.gradle.kts)
plugins {
    alias(libs.plugins.hotswan.compiler) apply false
}

// RIGHT (app/build.gradle.kts; Compose module)
plugins {
    alias(libs.plugins.android.application)
    alias(libs.plugins.kotlin.android)
    alias(libs.plugins.kotlin.compose)
    alias(libs.plugins.hotswan.compiler)
}

hotSwanCompiler {
    enabled = true
    debugOnly = true
}

模式：不要在源代码层面依赖 HotSwan

// WRONG
import com.github.skydoves.compose.hotswan.runtime.HotReloadable

@HotReloadable
@Composable
fun Greeting() { Text("Hello") }
// WRONG because: HotSwan is a build-time and IDE-time tool. Production code must not import
// HotSwan runtime classes or annotations; the Gradle plugin attaches transformations during
// compilation without requiring source-level coupling.

// RIGHT
@Composable
fun Greeting() { Text("Hello") }

模式：规范的三文件配置（可直接粘贴）

# gradle/libs.versions.toml
[plugins]
hotswan-compiler = { id = "com.github.skydoves.compose.hotswan.compiler", version = "1.2.10" }

// build.gradle.kts (root)
plugins {
    alias(libs.plugins.android.application) apply false
    alias(libs.plugins.kotlin.android) apply false
    alias(libs.plugins.kotlin.compose) apply false
    alias(libs.plugins.hotswan.compiler) apply false
}

// app/build.gradle.kts
plugins {
    alias(libs.plugins.android.application)
    alias(libs.plugins.kotlin.android)
    alias(libs.plugins.kotlin.compose)
    alias(libs.plugins.hotswan.compiler)
}

hotSwanCompiler {
    enabled = true
    debugOnly = true
}

故障排查

• 点击 Run 后状态仍停留在 READY。 设备尚未连接。运行 adb devices 并确认设备或模拟器已列出；重新连接 USB，或重启模拟器。
• 状态为 WATCHING，但保存后没有重新加载。 此次保存涉及结构性更改（参数、构造函数、接口、内联函数、新资源 ID）。请交叉参阅 ../understanding-hot-reload-limits/SKILL.md，确定边界。
• 重新加载成功，但状态丢失。 此次更改导致级别 2（组合重置）或级别 3（Activity.recreate()）重组。可用后请交叉参阅状态保留相关的同级技能。
• hotSwanCompiler { ... } 块无法解析。 添加插件后没有同步 Gradle。请重新同步；确认该模块使用的 Kotlin 版本为 Kotlin 2.0+；确认别名与 libs.versions.toml 中的条目一致。

强制规则

• 必须设置 debugOnly = true。HotSwan 转换仅用于诊断，绝不能进入发布构建。
• 必须仅在 Compose 模块中应用 Gradle 插件。在根项目中使用 apply false，以免转换非 Compose 模块。
• 不得在源码层面依赖 HotSwan 类。不得添加注解或运行时导入。HotSwan 是构建时和 IDE 时工具；生产代码应保持纯净。
• 不得将 HotSwan 与过时的 Compose Compiler 混用。在添加 HotSwan 之前，请确认 Kotlin 2.0 及以上版本已应用 org.jetbrains.kotlin.plugin.compose。
• 必须在 libs.versions.toml 中锁定 HotSwan 版本，确保项目中的所有 Compose 模块使用同一版本。最新验证通过的版本为 1.2.10；锁定版本前，请查看 hotswan.dev/docs/releases 是否有更新的稳定版本。
• **首选：**开发者熟悉手动热重载后，如果希望让 Claude 通过 MCP 驱动编辑、重载和截图循环，可将 HotSwan 与 AI 迭代循环同级技能（../iterating-with-ai-and-mcp/SKILL.md）结合使用。

验证

• ./gradlew :app:buildEnvironment 列出的已应用插件中包含 com.github.skydoves.compose.hotswan.compiler 插件。
• 使用 Run 启动应用后，HotSwan 工具窗口状态显示为 WATCHING。
• 在可组合项中修改 Text 的颜色并保存文件后，设备上的颜色会在一秒内改变。
• remember 值、滚动位置和导航返回栈均能在修改后保留。
• 发布构建（./gradlew :app:assembleRelease）不包含 HotSwan 转换。请确认已设置 debugOnly = true，或使用 dexdump 检查发布版 dex，确认其中不存在 HotSwan 注入的辅助类。
• 模块中没有生产源码文件导入 com.github.skydoves.compose.hotswan.* 符号（运行 grep -R "com.github.skydoves.compose.hotswan" src/main/ 应返回零条匹配）。

参考资料

• HotSwan JetBrains Marketplace 插件：https://plugins.jetbrains.com/plugin/30551-compose-hotswan/
• HotSwan 版本发布（最新稳定版本的权威来源）：https://hotswan.dev/docs/releases
• HotSwan 文档门户（skydoves/compose-hotswan-web）：https://github.com/skydoves/compose-hotswan-web
• HotSwan Gradle 配置文档：https://github.com/skydoves/compose-hotswan-web（位于 /docs/gradle-configuration 下）
• Compose Compiler Gradle 插件（Kotlin 2.0 及以上版本）：https://developer.android.com/jetpack/androidx/releases/compose-compiler
• 关于可热重载与必须重新构建的改动边界，请参阅同级技能 ../understanding-hot-reload-limits/SKILL.md。