Kotlin Multiplatform实战：星球突击队跨平台移植与Compose Multiplatform实践

这次我们来看一个 Kotlin Multiplatform 移植项目星球突击队。简单讲它原先是一个 Kotlin 写的游戏工程只跑 Android 单端这次做的改造是把整个项目迁到 KMP 架构让核心逻辑在 Android、iOS、桌面端复用而不是每个平台各写一套。先说这个项目的核心特点。第一战斗数值、关卡进度、存档数据这类游戏核心逻辑会被全部抽到共享模块三个平台共用一套编译源。第二UI 层采用 Compose Multiplatform 方案界面绘制代码也能跨端复用不需要像传统 KMP 那样在 iOS 侧用 SwiftUI 重新写一遍页面。第三KMP 对硬件几乎没有门槛普通开发机能完成编译调试不依赖独立显卡真正吃的是内存和磁盘还有 Gradle 构建时的 CPU 占用。第四网络和序列化走 Ktor 加 kotlinx.serialization接口请求、JSON 解析可以统一封装一套代码处理三端网络逻辑。第五整个工程用 Gradle 管理支持通过一条命令批量构建 Android APK、iOS Framework 和桌面端产物。这篇文章会完整走一遍移植流程从 Android 单工程改造为 KMP 多模块工程把核心逻辑迁到 commonMain用 expect/actual 处理平台差异再通过 Compose Multiplatform 复刻游戏主界面最后给出构建、单元测试、真机运行和常见错误排查清单。如果你的手里也有一个 Kotlin 单端项目想低成本覆盖多端这篇可以当作一个参考路线。1. 核心能力速览先把这次移植的范围和技术选型整理成表格方便后面对着操作。能力项说明项目类型Kotlin 游戏项目跨平台移植原工程为 Android 单端共享代码范围战斗逻辑、数值计算、关卡流程、存档解析、网络层UI 方案Compose Multiplatform 共享 UIAndroid/iOS/Desktop 共用绘制代码支持平台Android、iOS、桌面端 JVM具体取决于构建配置里的 target硬件门槛普通开发机即可不依赖独立显卡iOS 构建必须在 macOS 上完成构建工具Gradle Kotlin Multiplatform Plugin Compose Multiplatform Plugin接口能力通过 Ktor 统一封装 HTTP 接口commonMain 里维护请求和返回模型批量任务支持 Gradle 批量构建多平台产物也支持自动化测试多平台运行测试方式commonTest 单元测试 Android/iOS 侧集成测试适合场景已有 Kotlin 单端项目、希望复用业务逻辑覆盖多端的小团队需要注意KMP 的版本号、AGP 版本、Xcode 版本之间存在联动关系。实际移植时建议以当前最新稳定版本为准并保证 Android Studio 和 Kotlin 插件能匹配。避免一上来就追最新版本否则容易踩到编译工具链不一致的坑。2. 适用场景与使用边界在开始改工程之前先判断项目适不适合 KMP 移植这一点往往被很多人忽略。适合做 KMP 移植的项目通常有这几个特征主体代码是 Kotlin业务逻辑占比高UI 层没有大量依赖 Android 私有 API团队希望用尽量少的人力覆盖多端。像“星球突击队”这类游戏项目战斗数值、关卡进度、资源合成、存档解析这些逻辑非常重如果在 Android 写一遍、iOS 再写一遍后续每次调平衡都要同步改两处代码。把数值逻辑抽到 commonMain 后调一次平衡所有端一起生效这是移植的核心收益。不适合上来就做 KMP 移植的场景也要认清。如果项目重度依赖 Android 的 Service、BroadcastReceiver、ContentProvider或者需要在 Native 层做大量 C/C 计算KMP 的共享收益会被平台差异抵消。另外如果团队没有任何 Kotlin 经验不建议把 KMP 当作入门项目因为 expect/actual、sourceSets、Kotlin/Native 编译链路的调试成本不低。使用边界方面有三个点需要提前确认。第一KMP 共享的是代码逻辑不是资源文件图片、音频、字体需要按平台单独管理。第二iOS 编译只能在 macOS 上完成如果团队只有 Windows 环境iOS target 可以先不配先跑 Android 和 Desktop。第三如果原项目来自开源仓库或商业购买移植前必须确认许可证允许改写和分发涉及用户账号、支付、广告 SDK 的模块要特别注意隐私合规不能把未授权的代码或素材带到新工程里。3. 环境准备与前置条件KMP 移植最花时间的往往不是写代码而是把编译环境调通。下面给出一套通用检查清单按顺序过一遍能省不少排查时间。操作系统层面Windows 和 macOS 都可以做 Android 和桌面端开发iOS target 必须在 macOS 上编译。建议用 macOS 作为主力环境这样三个平台都能构建。开发工具建议使用较新的 Android Studio游戏项目的资源编辑和模拟器调试都比较方便Kotlin Multiplatform 插件和 Compose Multiplatform 插件直接在 IDE 的 Marketplace 里安装。JDK 版本建议使用 JDK 17 或更高版本。KMP 插件的编译工序较多命令行构建时容易出现 Gradle 守护进程和 JDK 版本不匹配的问题建议在gradle.properties里统一指定org.gradle.java.home避免 IDE 内构建和命令行构建用的 JDK 不一致。依赖库这一层需要确认几个关键库是否支持 KMP。常见的 KMP 依赖包括kotlinx-coroutines-core 提供协程支持kotlinx-serialization-json 提供 JSON 序列化Ktor 提供网络能力另外还有前文提到的 Compose Multiplatform 提供 UI。Android 侧需要额外的 Android SDK 和构建工具iOS 侧需要 Xcode Command Line Tools。磁盘空间建议至少预留 30GB 以上Android SDK、Gradle 缓存、Kotlin/Native 预编译包都很占空间尤其是第一次编译 iOS target 时Kotlin/Native 会下载跨平台编译链。前置条件确认完成后先不要急着改代码。建议把原 Android 工程完整备份一份确保改造过程中任何一步出错都能回退。用 Git 建一个新分支后续所有 KMP 化的改动都在分支上进行这样可以随时看到改动范围。4. 项目结构设计原 Android 工程通常是单 app 模块加 resources 目录。KMP 改造后建议拆成共享模块加多端壳工程的模式。推荐目录结构如下StarSquad/ ├── shared/ │ ├── build.gradle.kts │ └── src/ │ ├── commonMain/ │ │ ├── kotlin/ │ │ └── composeResources/ │ ├── androidMain/ │ │ └── kotlin/ │ └── iosMain/ │ └── kotlin/ ├── androidApp/ │ ├── build.gradle.kts │ └── src/ ├── desktopApp/ │ ├── build.gradle.kts │ └── src/ ├── iosApp/ │ ├── iosApp.xcodeproj │ └── iosApp/ └── gradle/ └── libs.versions.tomlshared 模块负责放所有可复用逻辑比如游戏核心数值、关卡流程控制、存档解析、网络请求、数据模型。androidApp 是 Android 壳工程职责就是创建 Activity加载 shared 模块提供的 Compose UI。desktopApp 是桌面端入口main 函数里创建窗口同样加载 shared 模块的 UI。iosApp 是 Xcode 工程用 SwiftUI 或 UIKit 作为壳承载 Compose Multiplatform 的界面。shared 模块的 build.gradle.kts 是这次移植的关键配置。下面是一个通用模板实际使用时需要根据项目版本和依赖情况调整plugins { kotlin(multiplatform) id(org.jetbrains.compose) id(org.jetbrains.kotlin.plugin.compose) kotlin(plugin.serialization) } kotlin { androidTarget() listOf( iosX64(), iosArm64(), iosSimulatorArm64() ).forEach { target - target.binaries.framework { baseName Shared isStatic true } } sourceSets { commonMain.dependencies { implementation(compose.runtime) implementation(compose.foundation) implementation(compose.material3) implementation(org.jetbrains.kotlinx:kotlinx-coroutines-core) implementation(org.jetbrains.kotlinx:kotlinx-serialization-json) implementation(io.ktor:ktor-client-core) implementation(io.ktor:ktor-client-content-negotiation) implementation(io.ktor:ktor-serialization-kotlinx-json) } androidMain.dependencies { implementation(io.ktor:ktor-client-okhttp) } iosMain.dependencies { implementation(io.ktor:ktor-client-darwin) } } } android { namespace com.example.starsquad.shared compileSdk 34 defaultConfig { minSdk 24 } }这段配置里需要注意几点。androidTarget 是让共享模块可以被打进 Android 工程iosX64、iosArm64、iosSimulatorArm64 分别对应 iOS 模拟器 Intel 架构、真机架构、模拟器 Apple Silicon 架构如果暂时不做 iOS可以先把这三行注释掉降低构建复杂度。isStatic true 表示生成静态 Framework集成到 Xcode 工程时更简单也避免和一些动态库冲突。sourceSets 里的依赖分平台配置网络引擎在 Android 用 OkHttp在 iOS 用 Darwin这样 Ktor 底层会使用平台原生的网络能力。5. 核心逻辑移植expect/actual 实战工程结构搭好之后开始把游戏逻辑往 commonMain 里搬。纯 Kotlin 代码直接复制过去基本能编译通过真正需要处理的是平台差异部分。KMP 用 expect/actual 机制处理平台差异。开发者在 commonMain 里声明一个预期定义然后在 androidMain、iosMain 里分别给出实际实现。以获取本地存档目录为例// commonMain expect fun getSaveDir(): String// androidMain actual fun getSaveDir(): String { return androidContext().filesDir.absolutePath }// iosMain import platform.Foundation.NSDocumentDirectory import platform.Foundation.NSFileManager import platform.Foundation.NSSearchPathForDirectoriesInDomains actual fun getSaveDir(): String { val directories NSSearchPathForDirectoriesInDomains( NSDocumentDirectory, 1u, true ) return directories.first() as String }androidMain 里使用了androidContext()这需要在 shared 模块中维护一个 Context 注册入口。一个常见的做法是写一个简单的初始化函数// androidMain private lateinit var appContext: Context fun initAndroidContext(context: Context) { appContext context.applicationContext } fun androidContext(): Context appContext在 Android 壳工程的 Application 或 MainActivity 创建时调用initAndroidContext(this)即可。iOS 侧获取文档目录则直接使用 platform.Foundation 提供的 API。除了目录路径游戏里常见的平台差异项还有获取设备时间戳、读取屏幕尺寸、生成唯一设备 ID、检查网络状态、震动反馈等。这些都可以用 expect/actual 逐一套壳。存档解析是游戏项目最值得迁移的模块之一。原来 Android 版如果用的是 SharedPreferences迁移到 KMP 后有两个选择一是保留 Android 侧实现通过 expect/actual 暴露给 commonMain二是在 commonMain 里改用 kotlinx.serialization 把存档序列化成 JSON 文件再通过 expect/actual 只暴露文件读取和写入能力。推荐第二种因为存档格式跨平台统一后后续做断点续传、云存档都会方便很多。下面是一个共享数据模型的例子// commonMain Serializable data class SaveData( val playerName: String, val level: Int, val exp: Long, val items: ListItemData ) Serializable data class ItemData( val itemId: String, val count: Int )对应的存档读写接口可以定义成如下形式// commonMain interface SaveRepository { suspend fun load(): SaveData? suspend fun save(data: SaveData) }然后分别在 Android 和 iOS 侧用文件读写实现这个接口commonMain 里的游戏逻辑无需关心底层是 Access 文件还是 NSFileManager。战斗结算、等级计算、掉落概率这类纯函数逻辑直接整体搬到 commonMain。建议为这部分逻辑配套单元测试因为它在三个平台共用一旦出错影响面最大。数值逻辑搬完后可以先写几个测试用例验证结果与 Android 旧逻辑一致。6. 界面层Compose Multiplatform 方案UI 层是这次移植工作量最大的部分。如果原 Android 项目使用的是 XML 布局那需要先把界面迁移到 Compose再进入 KMP 时代。如果原项目已经是 Compose那迁移到 Compose Multiplatform 要顺畅得多主要工作是替换 Material 组件依赖、处理各平台的点击事件差异、调整窗口尺寸配置。游戏主界面在 Compose Multiplatform 里可以直接共享。以战斗 HUD 界面为例下面的代码在 Android、iOS、Desktop 三端都能编译运行// commonMain Composable fun BattleHudScreen() { var hp by remember { mutableStateOf(100) } var energy by remember { mutableStateOf(50) } Column( modifier Modifier.fillMaxSize().padding(16.dp), verticalArrangement Arrangement.spacedBy(8.dp) ) { Text(text 角色血量: $hp, style MaterialTheme.typography.headlineMedium) Text(text 能量: $energy, style MaterialTheme.typography.bodyLarge) Button(onClick { hp (hp - 10).coerceAtLeast(0) }) { Text(受到攻击) } Button(onClick { energy (energy 5).coerceAtMost(100) }) { Text(回复能量) } } }这段代码只是一个示例没有用到任何平台专属 API所以可以直接放进 shared 模块的 commonMain。游戏里的角色头像、技能图标、血条等都建议用 Compose 的绘制能力重新封装不要依赖 Android Drawable。各平台壳工程的写法有明显差异需要在各自模块里单独维护。Android 壳工程的 MainActivity 如下// androidApp class MainActivity : ComponentActivity() { override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) initAndroidContext(this) enableEdgeToEdge() setContent { AppTheme { BattleHudScreen() } } } }桌面端壳工程是一个简单的 main 函数// desktopApp fun main() application { Window( title 星球突击队, state rememberWindowState(width 480.dp, height 800.dp) ) { AppTheme { BattleHudScreen() } } }iOS 壳工程则需要在 Xcode 里创建一个 SwiftUI 工程然后加载 shared 模块的 Compose 内容一般是通过 UIViewControllerRepresentable 桥接。具体实现会依赖 Compose Multiplatform 版本提供的从属 API建议直接参考对应版本的官方模板。需要特别注意的是Compose Multiplatform 的 iOS 支持虽然已经可用但在渲染性能和内存占用上仍需在真机上做验证尤其是游戏类项目对帧率敏感。如果主界面是由 Canvas 高频重绘的战斗场景建议先在 iOS 真机上跑一次性能测试再决定是共享 UI 还是 iOS 侧改用原生绘制。7. 构建、测试与真机运行代码迁移完成后开始验证各端构建。先构建 Android 产物。在项目根目录执行./gradlew :androidApp:assembleDebug如果编译通过会在 androidApp 模块的 build/outputs/apk/debug 目录下生成 APK 文件。安装到模拟器或真机上重点看两点一是 Compose 界面是否正常渲染二是战斗逻辑在真实交互下是否和旧版本表现一致。iOS Framework 的编译在 macOS 上执行./gradlew :shared:linkDebugFrameworkIosSimulatorArm64这个命令会生成模拟器架构的 Framework供 Xcode 工程导入。真机构建则使用./gradlew :shared:linkDebugFrameworkIosArm64编译产物在 shared/build/bin/iosArm64/debugFramework/Shared.framework。把 Framework 拖入 Xcode 工程后需要在 Build Settings 里配置 Framework Search Paths并在 General 里添加依赖。桌面端构建更简单./gradlew :desktopApp:run这条命令会直接启动桌面窗口适合快速验证界面和逻辑不需要安装模拟器。单元测试是验证迁移正确性的关键手段。在 commonTest 目录下写测试用例// commonTest class BattleLogicTest { Test fun testDamageCalculation() { val result calculateDamage( attack 100, defense 30, crit false ) assertEquals(70, result) } Test fun testLevelUpExperience() { val exp requiredExpForLevel(5) assertTrue(exp requiredExpForLevel(4)) } }然后运行共享模块的全平台测试./gradlew :shared:allTests这个命令会尝试在所有配置的 target 上执行测试。Android target 会启动本地 JVM 测试iOS target 会在 Kotlin/Native 测试框架里运行。注意iOS 模拟器测试需要提前启动一个模拟器实例否则可能报错。实际验证过程中最常见的现象是Android 编译通过、单元测试全绿但 iOS 编译失败或者桌面端 UI 能跑但 iOS 崩溃。所以建议后续每次改动都按照 Linux 单元测试、Android 构建、iOS Framework 构建、真机运行这个顺序逐步验证缩小问题范围。8. 常见问题与排查方法KMP 移植过程中会遇到一些高频问题整理成排查表遇到直接对表操作。问题现象可能原因排查方式解决方案iOS Framework 编译报错Kotlin 版本与 Xcode 版本不匹配查看 Kotlin/Native 编译日志升级或降级 Kotlin 版本对齐 Xcode 支持范围expect 声明缺失实际实现对应平台 sourceSet 目录下没有 actual搜索 expect 关键字在 androidMain 或 iosMain 下补充 actual 实现commonMain 中报找不到 Android API代码放错模块或误用平台类型查看 import 路径把平台相关调用移到 androidMain或用 expect/actual 抽象Compose 预览在 IDE 中不显示Compose Multiplatform 预览支持不完整检查插件版本通过运行 desktopApp 或 Android 工程实时预览Ktor 请求在 iOS 上失败网络引擎选错或缺少权限说明查看 iOS 访问日志检查 Ktor 引擎是否使用 Darwin检查 App Transport Security 配置依赖库下载超时Gradle 访问外网仓库较慢查看构建日志中的下载耗时配置国内镜像仓库统一管理依赖版本桌面端 UI 字体或布局错位平台字体渲染差异对比各端截图使用通用字体家族避免依赖系统独占字体iOS 真机启动崩溃Framework 静态库链接问题或属性列表配置错误查看 Xcode 崩溃日志检查 Framework 配置和 Info.plist 权限字段Gradle 守护进程内存不足多平台构建任务并发太高查看 GC 日志调整 gradle.properties 里的 JVM 参数降低并行度SharedPreferences 迁移后数据丢失原存档格式与新序列化格式不一致检查旧存档文件内容写兼容层读取旧格式转换后再写入新格式其中有两个坑要重点说。第一个是 Kotlin/Native 的缓存问题有时候改完 expect/actual 重新编译还是报旧错误可以清理 Kotlin 构建缓存./gradlew clean rm -rf ~/.konan第二个是 Ktor 引擎选择的问题。网络请求如果一开始在 commonMain 只依赖了 ktor-client-core编译能过但运行时一定会报“找不到引擎”之类的错误。必须按平台分别添加依赖Android 用 OkHttpiOS 用 Darwin。9. 最佳实践与使用建议这次移植给到几条工程化建议按优先级排序。先小范围验证不要一次性搬完所有代码。建议按“数据层 - 数值逻辑 - UI - 平台能力”的顺序推进。第一步先只搬存档模型和数值计算在 commonTest 里写好测试确认跨平台编译没问题后再继续搬网络层和界面。一次性迁移整个项目会让你在排查问题时面对几十个编译错误无法定位根源。保持 commonMain 纯净。commonMain 里只写纯 Kotlin 代码不要出现任何 Android 或 iOS 的 import不要使用 java.io 这种只在 JVM 可用的 API。如果遇到平台相关能力统一用 expect/actual 隔离。这样可以保证三个平台的共享代码完全一致也方便后续接新的平台。依赖版本统一管理。KMP 对版本匹配非常敏感建议用 Gradle Version Cataloglibs.versions.toml管理所有依赖版本。这样升级 Kotlin 版本时只需要改一个文件不用在所有模块的 build.gradle.kts 里手动同步。构建性能优化。KMP 工程的构建链路比普通 Android 工程长可以在 gradle.properties 里开启构建缓存和并行org.gradle.paralleltrue org.gradle.cachingtrue org.gradle.jvmargs-Xmx4096m但也不要把并行度调太高否则开发机的 CPU 会被占满反而拖慢编译。日志和错误上报需要抽象。游戏在三个端运行时崩溃日志的收集方式完全不同Android 用 LogcatiOS 用 os_log桌面端直接输出控制台。建议在 commonMain 里定义日志接口各端提供实际实现让业务代码不要直接写平台日志 API。合规边界要守住。如果游戏涉及用户账号、付费道具、云存档需要明确告知用户数据采集范围并在各平台上架时提供隐私政策。移植过程中如果引用了第三方开源库保留许可证声明不要随意裁剪许可证文本。涉及音效、美术素材的确认素材授权允许跨平台分发后再放入共享模块。10. 总结与进一步方向星球突击队的 KMP 移植最值得抄的作业是把存档、数值、网络这些逻辑从单端代码里剥离出来放进 commonMain再通过 Compose Multiplatform 把界面也变成一份代码。对游戏项目来说数值和存档反复调整的频次很高迁移完成后每次改动都只需要修改一处三端同步生效这是最直接的收益。最先应该验证的功能是存档兼容性。旧用户升级到新版本后原来的进度能不能正常读取这是决定要不要继续 KMP 化的关键指标。移植一开始就要写转换层让旧存档格式和新序列化格式平滑过渡否则后面再补会很被动。最容易踩的坑是 iOS 编译链路。Windows 或 Linux 环境下开发时Android 和桌面端都能正常构建但 iOS 代码接口一旦写错只有到了 macOS 上编译才会暴露周期较长。建议有条件就让团队的 iOS 环境尽早参与编译验证不要等所有代码搬完再上 Xcode。后续可以继续扩展的方向接入 Firebase 或自建服务端做云存档利用共享模块的数值逻辑做联机对战服务端校验把 shared 模块进一步拆成核心逻辑、网络层、UI 组件多个子模块方便引入新平台时按需组合还可以在共享代码上用 Ktor 搭建一个本地调试面板统一查看三端日志和存档数据。整体来说KMP 这套方案的投入产出比在游戏项目里是值得的关键是按模块消化不要一口吃成胖子。