一个不太好听的事实：大多数跨端方案的死因不是"性能不行"或"UI不原生"，而是——线上出了问题，团队花了三天定位 crash 到底发生在共享层还是平台层。

我们在讨论 Flutter、React Native、KMP 的时候，注意力几乎永远锁在渲染引擎、热更新、包体积这些"明面上的指标"。但真正决定一个跨端方案能不能在生产环境活下来的，是另一套东西：crash 能不能跨平台归因？共享库的 API 文档有没有自动生成？异步任务在 iOS 和 Android 的调度行为一致吗？

这些问题不性感，但致命。今天就聊聊这场"隐形战争"。

一、可观测性：跨端方案的"暗区"

先说个场景。你用 KMP 写了一个网络请求 + 本地缓存的共享模块，iOS 和 Android 各自调用。某天线上 crash 率飙升，Bugly 上看到一堆 Kotlin 的 stacktrace——但它们来自 iOS 端，经过 Kotlin/Native 编译后的符号表几乎不可读。你知道 crash 在共享层，但不知道是哪一行，更不知道当时的业务状态。

这不是假设，这是真实痛点。跨端可观测性（Observability）面临三个核心挑战：

挑战一：符号化断裂。 Kotlin/Native 编译产物的 dSYM 和 Android 的 mapping.txt 是两套体系。一个 crash 如果发生在 commonMain 的代码里，iOS 端和 Android 端的 stacktrace 长得完全不一样，关联到同一段源码需要额外的映射层。Flutter 的情况好一些——Dart VM 的 stacktrace 在双端一致——但 platform channel 调用链一断，就回到了同样的困境。

挑战二：业务上下文丢失。 传统的 Crash Reporting 工具是平台维度的：Crashlytics 管 Android，Sentry 管 iOS。跨端共享层的日志、用户行为路径、自定义属性，在这两个体系里各自为政。你很难在一个面板上看到"这个用户在 iOS 上触发了共享模块 A 的异常，同时 Android 上同一模块的错误率也在上升"。

挑战三：性能归因模糊。 一个页面卡了 200ms，是 Dart 渲染引擎的问题？是 platform channel 的序列化开销？还是原生侧的 GPU 合成慢了？Flutter 的 DevTools 给了不少工具，但线上环境的性能归因远不如开发阶段清晰。KMP 的情况更复杂——共享逻辑层没有统一的 tracing 接口，你需要自己在 commonMain 里埋点，然后分别对接 Android 的 Trace 和 iOS 的 os_signpost。

二、Kotzilla SDK：KMP 可观测性的第一个认真回答

本周 Android Weekly #723 重点提到了 Kotzilla SDK，这是目前我看到的第一个认真回答"KMP 可观测性怎么做"的方案。说说它做对了什么。

Kotzilla 的核心思路是：既然 KMP 的共享层用 Koin 做依赖注入已经是事实标准，那可观测性就应该从 DI 容器切入。它的 SDK 直接 hook 了 Koin 的模块解析过程，自动采集：

• 模块初始化耗时（包括懒加载触发时机）

• 依赖解析链路（谁依赖谁，解析顺序）

• 共享层 crash 的完整上下文（包括 DI scope 状态）

接入方式非常轻：

// commonMain - build.gradle.kts
kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("io.kotzilla:kotzilla-sdk:1.x.x")
            implementation("io.insert-koin:koin-core:3.5.x")
        }
    }
}

// 初始化（commonMain）
fun initApp() {
    startKoin {
        // Kotzilla 自动 hook，无需额外配置
        modules(appModule)
    }
    // 开启可观测性上报
    KotzillaSDK.start(
        apiKey = "your-project-key",
        config = KotzillaConfig {
            enableCrashReporting = true
            enablePerformanceTracing = true
            // 采样率，生产环境建议 0.1
            samplingRate = 0.1f
        }
    )
}

真正有价值的地方在于它的 crash 归因能力。当共享层发生异常时，Kotzilla 不只是给你一个 stacktrace，而是同时给出：

• 当前 Koin scope 里所有已解析依赖的状态快照

• 异常发生前最近 N 次依赖解析事件（类似 breadcrumb）

• 双端统一的 event ID，可以在 dashboard 上关联同一用户在 iOS/Android 的行为

这解决了前面说的"业务上下文丢失"问题。当然，它的局限也很明显——强依赖 Koin。如果你的 KMP 项目用的是手动依赖注入或者 Kodein，Kotzilla 帮不上忙。但考虑到 Koin 在 KMP 生态里的统治地位（Kotlin Multiplatform 官方 samples 几乎全部使用 Koin），这个押注算合理。

对比一下其他方案的可观测性成熟度：

维度	Flutter	React Native	KMP
统一 Crash Reporting	Crashlytics 官方支持	Sentry RN SDK 成熟	Kotzilla / 自建
符号化一致性	Dart stacktrace 双端一致	JS stacktrace 一致	需手动映射
性能 Tracing	DevTools + Firebase Perf	Flipper / React Profiler	平台各自接入
DI 层可观测	无标准方案	无标准方案	Kotzilla

KMP 在可观测性上确实起步最晚，但 Kotzilla 这种从 DI 容器切入的思路，反而可能比 Flutter/RN 的"套一层 SDK"方式更深入。

三、文档工具链：Dokka V2 解决了一个被忽视十年的问题

写跨端共享库的人都知道一个痛苦：你在 commonMain 里写了一个接口，iOS 同事问你"这个方法参数是什么意思"，你说"看代码注释"。iOS 同事说"我看到的是 Objective-C 的头文件，注释没了"。

KMP 共享库的文档生成一直是个灾难。Dokka V1 勉强能给 JVM/Android 目标生成 KDoc，但对 Kotlin/Native（iOS）和 Kotlin/JS（Web）的支持残缺不全。更要命的是，当你写了一个 expect/actual 声明时，V1 生成的文档会把各平台的实现散落在不同页面，无法整体理解一个 API 的全貌。

Dokka V2 把这个问题正面解决了。核心变化：

统一的多目标文档页面。 一个 expect fun 和它所有 actual 实现会出现在同一个页面，用标签页切换平台。这看起来是个小改动，但对于库的使用者来说，终于能在一个地方看清楚"这个 API 在 Android 上长这样，在 iOS 上长那样"。

Gradle 插件重写。 V2 的 Gradle 配置大幅简化：

// build.gradle.kts
plugins {
    id("org.jetbrains.dokka") version "2.0.0"
}

dokka {
    // V2 自动检测所有 KMP targets，无需手动配置
    dokkaPublications.html {
        // 输出目录
        outputDirectory.set(layout.buildDirectory.dir("docs"))
    }
    
    // 自定义源码链接（GitHub/GitLab）
    dokkaSourceSets.configureEach {
        sourceLink {
            localDirectory.set(projectDir.resolve("src"))
            remoteUrl("https://git.example.com/repo/tree/main/src")
            remoteLineSuffix.set("#L")
        }
    }
}

V1 时代，配置一个多目标的 Dokka 任务需要手动列出每个 source set，还经常因为 Kotlin/Native 的编译模型导致 Gradle 任务失败。V2 把这些全自动化了。

API 兼容性报告。 这是 V2 新增的能力——当你升级共享库版本时，Dokka V2 可以对比两个版本的 public API，自动生成 breaking change 列表。对于维护跨端 SDK 的团队来说，这个功能堪称救命。之前要么靠人肉 review，要么用 metalava（Android 专属），现在 Dokka V2 在 KMP 全平台通用。

说句公道话：Flutter 在这方面做得一直不错，dartdoc 从一开始就是一等公民，pub.dev 上的包文档质量普遍较高。React Native 依赖 TypeScript 的类型声明和 JSDoc，工具链成熟但碎片化。KMP 的 Dokka V2 算是补上了短板，但追上 Flutter 的文档体验还需要生态跟进。

四、协程运行时：一致性比性能更重要

kotlinx.coroutines 1.11.0-rc01 本周发布，这个版本值得展开说说，因为它触碰了跨端开发的一个核心痛点：异步行为在不同平台上到底一不一样？

先看一段 commonMain 的代码：

// commonMain
suspend fun fetchAndProcess(): Result<Data> = coroutineScope {
    val config = async { remoteConfigRepo.fetch() }
    val cache = async { localCacheRepo.load() }
    
    val remoteConfig = config.await()
    val localCache = cache.await()
    
    if (remoteConfig.version > localCache.version) {
        processAndSync(remoteConfig, localCache)
    } else {
        Result.success(localCache.data)
    }
}

这段代码在 Android 上跑得好好的，到 iOS 上偶尔会 crash。原因是 Kotlin/Native 的旧内存模型对协程的并发有严格限制——虽然新内存模型（自 Kotlin 1.7.20 默认启用）已经解决了大部分问题，但在某些边界场景下，Dispatchers.Default 在 Native 和 JVM 上的线程池行为仍然不同。

1.11.0-rc01 的关键改进在于两点：

第一，Dispatchers.Default 的行为更加统一。 JVM 上 Dispatchers.Default 使用一个与 CPU 核数相关的共享线程池，Native 上之前是单独的工作线程。1.11.0 将 Native 的实现对齐到了类似的多线程池模型，这意味着并发行为的一致性大幅提升。

第二，取消传播的边界行为修正。 之前有一类微妙的 bug：在 supervisorScope 里启动的子协程在 Native 上的取消传播行为和 JVM 上不完全一致。1.11.0 修复了这些边界 case。这类问题非常恶心——它们不会在单元测试里暴露，只会在高并发的线上环境偶发。

对比一下三大框架的异步一致性表现：

框架	异步模型	双端一致性	已知陷阱
Flutter	Dart Isolate + Event Loop	高（同一 VM）	Isolate 间通信序列化开销
React Native	JS Event Loop (Hermes)	高（同一引擎）	Bridge 异步回调顺序不保证
KMP	kotlinx.coroutines	中高（1.11 后提升）	Native Dispatcher 行为差异

Flutter 和 RN 的优势在于它们有自己的运行时——Dart VM 和 Hermes 引擎在双端完全相同，异步行为天然一致。KMP 的思路不同，它不带运行时，而是编译到平台原生代码，异步能力依赖 kotlinx.coroutines 在各平台的具体实现。这注定了 KMP 在异步一致性上要花更多功夫。1.11.0 的进步是实质性的，但距离"写完 commonMain 就不用操心平台差异"还有距离。

五、Navigation3 和 Compose Multiplatform：基础设施的 UI 层补完

今天 JetBrains 发布了 Compose Multiplatform v1.11.10-alpha01，引入了 Navigation3 组件。这件事和前面说的基础设施成熟度是一脉相承的。

之前 Compose Multiplatform 的导航方案很混乱：

• 官方的 Jetpack Navigation 是 Android only，不支持多平台

• 社区方案有 Voyager、Decompose、Appyx——各有拥趸，互不兼容

• 团队选型时经常陷入"用哪个导航库"的无意义争论

Navigation3 的设计思路比较务实：

// commonMain - Navigation3 基本用法
@Composable
fun AppNavigation() {
    val backStack = rememberNavBackStack(startRoute = HomeRoute)
    
    NavDisplay(backStack) { route ->
        when (route) {
            is HomeRoute -> HomeScreen(
                onNavigateToDetail = { id ->
                    backStack.add(DetailRoute(id))
                }
            )
            is DetailRoute -> DetailScreen(
                itemId = route.id,
                onBack = { backStack.removeLastOrNull() }
            )
        }
    }
}

// 路由定义（类型安全）
@Serializable
data object HomeRoute

@Serializable
data class DetailRoute(val id: String)

几个值得注意的设计决策：

路由是数据类，不是字符串。 告别了 Jetpack Navigation 那套 navController.navigate("detail/{id}") 的字符串路由。类型安全在多人协作的跨端项目里不是锦上添花，是基本需求。

BackStack 是显式的。 不像 Jetpack Navigation 那样把 back stack 藏在 NavController 内部，Navigation3 把 back stack 暴露为一个可观察的列表。这意味着你可以在 ViewModel 层直接操作导航状态，更容易做单元测试和状态恢复。

平台无关的过渡动画。 Navigation3 的 transition API 在 commonMain 定义，各平台使用相同的动画描述，由 Compose 的渲染引擎执行。不需要像 Voyager 那样为 iOS 和 Android 写不同的过渡效果。

放在基础设施视角来看，Navigation3 补上的是 Compose Multiplatform 的最后一块关键拼图。之前的状态是：UI 组件有了（Material3 Multiplatform），状态管理有了（ViewModel Multiplatform），网络有了（Ktor），序列化有了（kotlinx.serialization），DI 有了（Koin），但导航——这个串联所有页面的骨架——是缺失的。现在补上了。

六、基础设施成熟度模型：怎么判断一个跨端方案"可用于生产"

聊了可观测性、文档工具链、协程运行时、导航框架，我想提一个判断框架。选跨端方案时，除了看 Star 数和 benchmark，更应该看基础设施的"成熟度层级"：

L4 - 生产级可观测性
↑
统一 Crash → 跨平台归因、业务上下文、性能 Tracing

L3 - 工程工具链
↑
工具链 → 文档自动生成、API 兼容性检查、CI/CD 模板

L2 - 核心框架齐备
↑
框架层 → UI、导航、网络、存储、DI、状态管理

L1 - 编译运行能力
↑
基础 → 能编译到目标平台、能跑 Hello World

用这个模型来看当前三大方案：

Flutter：L4-（接近满级）。 Crashlytics/Sentry 支持成熟，DevTools 完善，dartdoc 好用，pub.dev 生态繁荣。唯一短板是 platform channel 的可观测性还不够透明。

React Native：L3+。 工具链成熟（TypeScript、Metro、Flipper），Sentry/Datadog 支持好。但 New Architecture（Fabric/TurboModules）的迁移让很多工具链处于过渡状态。

KMP：L2 → L3 的跃迁中。 Navigation3 补上了 L2 的最后短板，Dokka V2 和 Kotzilla 正在推进 L3-L4。这是 KMP 当前最关键的阶段——核心框架刚齐备，工程工具链开始补课。

七、给判断：2026 年选跨端方案，该怎么看基础设施

直接给观点：

如果你的团队 不是因为 Flutter 的 UI 最好或性能最强，而是因为它的基础设施最完整。一个小团队没有精力去填工具链的坑，Flutter 从文档、测试、CI、可观测性到 IDE 支持，全链路成熟度最高。

如果你已有成熟的 Android + iOS 原生代码库，选 KMP。 KMP 的核心优势不是"替代原生"，而是"渐进式共享"。从网络层、数据层开始共享，UI 保持原生——这个路径现在的基础设施终于跟上了。Dokka V2 让你的共享库有文档，Kotzilla 让你能监控，Navigation3 让你未来可以选择 Compose Multiplatform 统一 UI。

如果你的团队以 Web 前端为主，RN 仍然是最务实的选择。 TypeScript 生态的工具链成熟度不是其他方案能比的。New Architecture 的阵痛期正在过去，Hermes 引擎的性能在 2026 年已经不再是瓶颈。

一个通用原则：不要因为"能 Demo"就选一个方案。 能跑起来 Hello World 是 L1，你需要的是 L3 以上。下次评估跨端方案时，试试问这些问题：线上 crash 怎么归因到共享层？共享库的 API 变更怎么追踪？异步行为在双端一致吗？CI 怎么跑多平台测试？

这些问题的答案，比"帧率多少"和"包体积多大"重要得多。

下一步值得探索的方向

两个我还在关注的事情：

一是 Touchlab 那篇《Helping Decision-Makers Say Yes to KMP》提到的"TCO 计算模型"——怎么量化跨端方案的总拥有成本，包括工具链建设、培训成本、线上运维成本。目前行业里缺一个标准化的框架来做这个计算，大多数选型还是靠感觉。

二是 AI 辅助开发对跨端基础设施的影响。Android Studio Panda 4 的 Planning Mode 已经能理解 KMP 项目结构了。如果 AI 能自动生成 expect/actual 的脚手架代码、自动补全跨平台的 API 文档、甚至自动识别双端行为不一致的测试用例——基础设施的"人工补课"阶段可能会大幅缩短。这个方向值得持续观察。

— EOF —