各位 Compose 刘德华，早上好！

你是否在项目中频繁遭遇 UI 卡顿，却找不到具体是哪段代码导致的？是否曾经为一次看似微小的状态更新而导致全屏重组而抓狂？本篇文章将帮助你精准定位这些“慢代码”，并提供实用的修复方案。让你的 Compose 应用重新焕发流畅。

两篇文章侧主要不同。互为补充，各位刘德华可以任意采摘。

从 View 到 Compose：性能思路的转变

性能调整往往聚焦于减少布局层级、调整 onMeasure 与 onDraw 的执行耗时还有减少过度绘制。而 Compose 性能模型的主要理念非常直观：跳过不必要的工作。

完全跳过该函数的执行过程。正是这种被称为“跳过”的调整方式，赋予了 Compose 默认的高性能。

但如果你的代码里潜藏了不易察觉的不稳定参数。跳过机制会失效，导致 UI 在无形中被迫频繁重组，从而出现卡顿、掉帧等问题。

看不见的重组浪费

在 Compose 中，每当组合函数读取的状态发生变化时该函数就有可能被重新执行。状态一旦更新，Compose 会遍历 UI 树。并让所有依赖该状态的组合函数重新执行。要让这个过程保持高效，关键就在于跳过机制：

• 参数必须是稳定类型——编译器确信该值任何可观察状态改变都会主动通知 Compose。
• 参数值必须通过 equals 判断与之前相等

痛点：只要有一个参数不稳定。即使其他全部满足条件，也会导致整个组件及其子树失去跳过机会，触发级联重组。

我们来看一个以 List 传递数据的列表界面：

@Composable
fun ItemList {
LazyColumn {
items { item ->
ItemCard
}
}
}

Kotlin 中 List 只是一个接口。因为 MutableList 一样实现了它。 编译器无法确信其不可变性，于是将 items 判定为不稳定。若未开启强跳过模式，父组件状态改变时整个列表都会被重新组合。即便列表数据本身未变，

如何判定稳定性

C​ompile‑time 稳定性标签规则概览：

• 天生稳定类型：Kotlin 基本类型（)、。,函数类型还有枚举类。
• 推断稳定的数据类：If all properties are declared as
• C​ontains any ,mutable collections or comes from a module not processed by Compose compiler.

The compiler generates a static field named

// 编译器生成示例
@StabilityInferred
data class User {
companion object {
val `$stable`: Int = // 位掩码表示此类已被标记为 Stable
}
}

If type is generic。mask records which type arguments affect stability . This enables precise skipping decisions even for generic containers.

稳定性检测工具——让隐藏的问题浮出水面

A manual audit quickly becomes infeasible in large codebases. The **Compose Stability Analyzer** offers a comprehensive suite of visual tools to surface unstable parameters before y hurt performance.

ID​E 插件实时反馈

• 绿点： 所有参数均 Stable，可安全跳过。
• 黄点： 部分参数依赖泛型，需要运行时判断。
• 红点： 至少有一个 Unstable 参数，会导致不可避免的重组。

The tooltip on hover lists each parameter’s stability status and exact reason ”). This immediate feedback lets you fix issues while coding instead of after y cause jank in production.

@TraceRecomposition – 运行时追踪真相

The annotation instruments a composable so that every recomposition is logged along with its parameters:

@TraceRecomposition
@Composable
fun ProductList(
再看items，List,onItemClick: -> Unit
) { /* ... */ }

If recomposition exceeds threshold,Logcat emits:

D/Recomposition: ProductList
├─ items: List unstable
├─ onItemClick: Function1 stable
└─ Unstable parameters:

This pinpointed log tells you exactly which argument broke skipping。enabling rapid targeted fixes.

检测报告 – 无插件也能生成分析结果

If you prefer not to install plugins,you can still generate a compiler stability report via Gradle:

./gradlew :app:composeCompilerReport
# 报告文件位于 build/compose-reports/stability.txt

The report lists every composable with its skippable status and highlights unstable parameters—great for CI checks and legacy code audits.

如何让类型变得 Stable

不可变集合——优先考虑方案

Kotlin 标准库中的集合接口默认是不稳定的，因为编译器无法确认它们背后不是可变实现。解决办法是使用官方提供的不变集合库：

// 修复前：普通 List 不稳定
data class UiState(
val items: List,val tags: Set,)
// 修复后：Immutable 集合确保绝对不可变
import kotlinx.collections.immutable.ImmutableList
import kotlinx.collections.immutable.ImmutableSet
data class UiState(
val items: ImmutableList,val tags: ImmutableSet,)

If migrating everything at once is impractical,you can add a stability configuration file to force compiler to treat standard collections as stable:

kotlin.collections.List
kotlin.collections.Set
kotlin.collections.Map
# 保存为 stability-config.conf 并在 Gradle 中引用
**Caution:** Declaring mutable collections as stable removes compile‑time safety—if you accidentally pass a `MutableList`。UI updates won’t trigger recomposition.

坚持使用 `val` 属性

A single `var` turns an entire data class into Unstable because its value may change without notifying Compose.

// Before – Unstable due to var properties
data class UserState
// After – All immutable → Stable
data class UserState
The same rule applies across inheritance hierarchies—any `var` in a superclass contaminates subclasses.

@Stable 与 @Immutable 的正确使用

An­no­ta­tion	Description & When to Use It?
@Immutable	Straight‑forward contract that **no observable state ever changes** after construction. Use for pure value objects that truly never mutate.
@Stable	Lighter guarantee – state may change **only via snapshot-aware mechanisms** . Ideal for wrapper classes that expose mutable state safely.

A wrong annotation can be disastrous:

• @Immutable on a mutable object → Compose will skip updates → stale UI.
• @Stable on an object that mutates without snapshots → recompositions may miss changes → subtle bugs.

搞定第三方类型

If a library’s classes lack stability metadata,y’re treated as Unstable by default.

• Add m to stability config whitelist:

com.example.network.models.**
com.squareup.moshi.JsonAdapter
This tells compiler “trust me”,allowing those types to be considered Stable.

Create a thin immutable wrapper around m:
@Immutable
data class StableTimestamp
// Conversion at boundaries
fun Instant.toStable = StableTimestamp)
Wrapping isolates external mutability and gives you full control over stability semantics.
Pitfall: If you forget to update wrapper when underlying model gains new mutable fields。your assumptions become invalid and hidden bugs appear.

稳固 Lambda 捕获参数 

Lambdas are intrinsically Stable,but only when ir captured variables are Stable as well. Capturing an Unstable collection forces compiler to create a new lambda instance on every recomposition.
// Before – captures unstable list → new lambda each time
@Composable
fun Screen {
val viewModel = viewModel 
ItemList(
items = items,onClick = { item -> viewModel.select } ) }
// After – use Immutable collection + stable ViewModel → lambda can be memoized
@Composable
fun Screen {
val viewModel = viewModel 
ItemList(
items = items,onClick = { item -> viewModel.select } ) }
// If you cannot make captures stable,wrap m with remember
val onClick = remember { { item : Item -> viewModel.select } }
With Strong Skipping Mode enabled,Compose prefers reference equality for such Lambdas,giving m anor chance to skip—but relying solely on this fallback hides potential instability in or contexts.

在合适阶段读取状态 — 降低代价 

The composition pipeline consists of three stages:


Composition – reading state here triggers full recomposition .

Layout – only layout pass is rerun when state changes at this stage.

Drawing – just repaints;cheapest impact.


// Bad – reads animation value during composition → heavy recompositions
val offsetDp by animateDpAsState
Box )



// Good – defer reading until drawing phase using graphicsLayer
val offsetPx by animateFloatAsState
Box


Similarly,using Modifier.offset { IntOffset } postpones calculation to layout phase—a win over direct composition‑time values.

derivedStateOf 过滤冗余重组 

// Before – each pixel scroll triggers recomposition
@Composable fun Header {
val showElevation = scrollState.value> 0
Surface 4 .dp else 0 .dp ) {/* …*/}
}



// After – only recompose when logical condition flips
@Composable fun Header {
val showElevation by remember {
derivedStateOf { scrollState.value> 0 }
}
Surface 4 .dp else 0 .dp ) {/* …说起来，*/}
}


derivedStateOf caches its result and emits changes only when structural equality differs. Use it for thresholds,filters or any situation where input changes more often than needed output.

Caution:count + 1
。which adds unnecessary overhead without filtering any recompositions.

：把“慢代码”彻底根除

拥有这套理论 + 工具 + 实践教程，你将在新功能开发和老代码迭代中保持 UI 流畅，即使业务规模增长较快，也能自信地交付高性能、低抖动的 Jetpack Compose 产品。

---