要点

这条路线面向想把 KMP 学到”能独立交付一个双端应用”的人，共六个阶段，按每天 1-2 小时业余时间口径约 6-8 周走完。它本身就是一条串站内文章的线：每个阶段的资源优先指向本站 KMP 系列——开山篇、语法要点、参考字典、双端待办实战——站内没有的才引官方文档。每个阶段有明确的”做出什么”与验收标准，”了解了 xx”不算产出。

这张路线适合谁

前置知识一句话说死：Kotlin 语法过关（类、协程 suspend、Flow 用过），用 Compose 写过至少一个单端页面，并且——想做 iOS 阶段就必须有一台 Mac，Xcode 工具链没有替代品。不会的话先补三篇再回来：Kotlin / Compose 环境搭建、Kotlin 语法要点、第一个 Compose 应用。Swift 侧只需要”读得懂”的程度（本系列 iOS 代码以 Swift 接线为主），需要深入时再走Swift / SwiftUI 环境搭建与Swift 学习路线。

已有 Flutter / React Native 经验的人要主动卸载一个习惯：KMP 的默认形态是共享逻辑、各端原生 UI，”一套代码出两端 UI”是 Compose Multiplatform 才提供、且要付代价的选项（见开山篇的两条路线对比）。

总览

阶段 0：前置，不写一行 KMP

学什么：Kotlin 数据类与集合操作、suspend 函数与 Flow 消费、Compose 的 state 驱动（对照站内 Composable 与状态）。产出验收：一个单端 Compose 页面能输入、追加、勾选列表项，旋转屏幕不丢状态。卡点：协程只在教程里见过——协程与 Flow 基础一篇够用，阶段 3 起共享层全是 suspend 和 Flow。

阶段 1：认知与第一个共享层

学什么：KMP 的定位判断（共享什么、不共享什么，两条路线怎么选）；源集目录结构与”commonMain 对每个目标各编译一次”；官方 wizard（kmp.jetbrains.com）建工程。资源：开山篇建立认知，向导生成的工程先跑 Android 目标。产出：commonMain 里一个纯 Kotlin 的”任务模型 + 仓库接口 + commonTest 单测”，被 Android 端调用跑通。验收：故意在 commonMain 里 import 一个 android.* 类，确认编译失败——机制要先”撞”一次。卡点：没有 Mac——这一阶段就确认，别拖到阶段 4。

阶段 2：expect/actual 与平台差异

学什么：expect/actual 三形态与四条规则；actual typealias 顶替平台现成类；中间源集（iosMain）的用途；@Throws 与 iOS 互操作注解。资源：语法要点吃透机制，条目速查用参考字典的关键字组。产出：一个 PlatformInfo 页——共享 ViewModel 调 expect 声明的设备信息能力，Android/iOS 各自 actual，两端各显示系统版本。验收：删掉 iOS 的 actual，编译失败并点名缺哪个目标。卡点：actual 签名对不上——同包同名同签名逐字核对，默认参数只写 expect 一侧。

阶段 3：数据与网络进共享层

学什么：Ktor client 的 core 与平台引擎分离（androidMain 放 android 引擎、iosMain 放 darwin 引擎）；kotlinx-serialization 的 @Serializable 与 Json 配置；DataStore 多平台与文件路径的传递。资源：官方 Ktor + SQLDelight 教程打底，坐标速查见参考字典的多平台库组。产出：拉一个真实公开 API 的列表页，数据层全在 commonMain，UI 用各端原生（Android 用 Compose，iOS 用 SwiftUI）分别消费。验收：断网时列表页有缓存或兜底行为，两端一致。卡点：引擎放错源集——运行时才报”找不到引擎”，按字典的坑列自检。

阶段 4：全共享 UI（Compose Multiplatform）

学什么：CMP 的工程形态与 ComposeUIViewController；Xcode 的 Run Script 接线与常见构建坑；统一 @Preview 与桌面目标的可选加入。资源：双端待办实战照做一遍，然后脱离文章独立重写（换成记账、习惯打卡都行）。产出：一个双端可安装的应用，UI 与数据层全共享。验收：文末验收清单两端全绿；平台目录合计行数不超过 30 行。卡点：iOS 构建报错几乎都在 Xcode 侧（脚本阶段顺序、Sandboxing、模拟器架构），不在 Kotlin 侧。

阶段 5：互操作与上线

学什么：Swift 侧调用 Kotlin API 的类型映射与 @Throws；XCFramework 与 CocoaPods 两条集成路线的取舍；CI 上 macOS runner 的必要性与缓存策略；Play Console 与 App Store 的分发流程（以官方文档为准）。资源：kotlinlang.org 的 Obj-C 互操作与分发文档。产出：给阶段 4 的应用接一项真原生能力（本地通知或相机权限流程），双端出可分发包。验收：iOS 侧能 catch 到 Kotlin 抛出的 NSError；CI 全绿出包。卡点：上架审核与签名问题与 KMP 无关——按各平台官方文档走，别在共享层里找原因。

避坑清单

• 不要一上来全共享 UI。先统一逻辑层验证收益，再逐屏上 CMP；反过来做的项目通常在第一个 iOS 性能坑退回原生。
• 不要把 Android 直觉搬进 commonMain。java.time、反射、JVM 库都不存在，先查语法要点的对照表再写；”Android 能编译”不算数。
• 不要让 expect/actual 超过两位数。契约按目标数量倍增，几十个 expect 说明差异没抽象掉，每加一端还一遍债。
• 不要拖到最后才碰 iOS 环境。Xcode 版本、模拟器架构、签名证书都有磨合成本，阶段 1 就把 Mac 与 Xcode 备齐。
• 不要追求共享率 KPI。百分之百共享通常意味着用最别扭的方式绕平台差异，actual 层留白反而是长期成本更低的选择。

学完之后

六个阶段做完，你手里有一个双端应用和一套可复用的判断：这块逻辑要不要共享、这个平台差异放 actual 还是放入口组装、这个数据量该不该上数据库。往深走三条路：一是给应用加真需求（推送、深链、Widget），在真问题里撞互操作；二是对照其他跨端方案看同一张地图——React Native 学习路线是”JS 一套 UI”的画法，与 KMP 的”逻辑共享 + UI 各端”逐项对照着读收益最大；三是 Kotlin 语言本身继续加深，回Kotlin / Compose 基础知识参考字典与Kotlin / Compose 学习路线。

版本核实（以官方文档为准）：截至本文（2025-07-22）Kotlin 稳定线为 2.2（2.1.x 存量项目同样适用），KMP 自 Kotlin 1.9.20（2023-11）稳定，Compose Multiplatform 1.8 线且 iOS 目标自 1.8.0（2025-05）稳定；路线涉及的默认层级模板、expect/actual 规则、DataStore 多平台、统一 @Preview 均为官方文档现行内容，具体版本以 kotlinlang.org 发布页为准。