2. 开发环境搭建

Kotlin Multiplatform（KMP）的工程能力横跨 JVM、Android、iOS 与原生平台，因此它的开发环境不是“装一个 IDE”那么简单，而是由 JDK、Android Studio、Xcode、Kotlin 插件、KMP 项目模板、Gradle 配置以及模拟器/真机调试环境共同组成的一条工具链。任何一个环节版本不匹配，都会在同步、编译或运行阶段以看似无关的报错暴露出来。本章按“先装底层运行时，再装 IDE 与插件，最后打通调试通道”的顺序展开，并给出可直接对照执行的版本与配置示例。

一、先确定版本基线，再动手安装

KMP 对版本非常敏感，建议先锁定一组经过验证的基线，再逐项安装。以下是一组合理的示例基线（示例参数，实际请以官方兼容性说明为准）：

组件建议版本作用
JDK17（LTS）Gradle 与 Kotlin 编译运行的基础
Android StudioLadybug 或更新Android 端开发与 KMP 插件宿主
Kotlin 插件与 Kotlin 版本一致，如 2.0.xIDE 语法支持与 Gradle 同步
Xcode15.x 及以上iOS 编译、模拟器与真机调试
Gradle8.x（由 wrapper 固定）多平台构建与依赖管理

关键原则是：JDK 版本由 Gradle 决定，Kotlin 插件版本由项目决定，Xcode 版本由 iOS 目标决定。三者不要各自“装最新”，而要以项目模板的兼容矩阵为准。

二、JDK 与 Android Studio 的安装要点

JDK 推荐使用 17 LTS。安装后需确认 JAVA_HOME 指向 JDK 根目录，并把 bin 加入 PATH。验证命令：

java -version
# 期望输出类似：openjdk version "17.0.11" 2024-04-16
echo $JAVA_HOME   # macOS/Linux
echo %JAVA_HOME%  # Windows

Android Studio 安装时勾选 Android SDK、SDK Platform-Tools 与 Android Emulator。安装完成后在 Settings → Languages & Frameworks → Kotlin 中确认 Kotlin 插件已启用，并在 Settings → Build → Build Tools → Gradle 中选择“使用 Gradle wrapper”，避免使用本机全局 Gradle 造成版本漂移。Android SDK 路径建议不含中文与空格，否则 NDK 与 Gradle 偶发路径解析失败。

三、Xcode 与 iOS 工具链

macOS 上从 App Store 安装 Xcode 后，必须执行一次命令行工具切换，否则 KMP 的 iOS 编译任务找不到 xcodebuild：

sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
xcodebuild -version
# 期望输出：Xcode 15.x

随后在 Xcode 中登录 Apple ID，并在 Settings → Accounts 添加开发者账号。若只跑模拟器，免费账号即可；若要真机调试，需要在 Signing & Capabilities 中配置 Team 与自动签名。iOS 真机还需在设备上开启“开发者模式”，并在首次连接时信任该电脑。

四、KMP 项目模板与 Gradle 配置

推荐用 Kotlin Multiplatform Wizard 生成模板，选择 Android + iOS 目标，得到 composeApp（共享 UI）与 iosApp（iOS 壳工程）结构。核心配置集中在 gradle/libs.versions.toml 与各模块的 build.gradle.kts。示例版本目录：

[versions]
kotlin = "2.0.21"
agp = "8.5.2"
compose = "1.7.0"

[libraries]
kotlinx-coroutines = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-core", version = "1.9.0" }

[plugins]
kotlinMultiplatform = { id = "org.jetbrains.kotlin.multiplatform", version.ref = "kotlin" }
androidApplication = { id = "com.android.application", version.ref = "agp" }

共享模块的 build.gradle.kts 需要声明目标平台与源集：

kotlin {
    androidTarget()
    iosX64(); iosArm64(); iosSimulatorArm64()
    sourceSets {
        commonMain.dependencies {
            implementation(libs.kotlinx.coroutines)
        }
    }
}

配置完成后点击 Sync Now。若同步失败，优先检查三处：JDK 是否为 17、AGP 与 Gradle 是否匹配、local.properties 中 sdk.dir 是否指向正确 SDK。同步成功后，./gradlew tasks 应能列出 assembleDebug、linkDebugFrameworkIosSimulatorArm64 等任务。

五、模拟器与真机调试环境

Android 端在 Device Manager 中创建 AVD，建议选 API 34、Pixel 7 机型，并开启硬件加速。iOS 端在 Xcode 的 Simulator 中选择 iPhone 15。真机调试时，Android 需开启 USB 调试并用 adb devices 确认设备已授权；iOS 需在 Xcode 中选中设备并完成签名。运行共享代码时，Android 走 assembleDebug 安装 APK，iOS 走 Xcode 运行 iosApp 方案，两者共用 commonMain 中的业务逻辑。

KMP 开发环境工具链与调试通道 JDK 17 LTS JAVA_HOME / PATH Gradle 运行基础 Android Studio SDK / Platform-Tools Kotlin 插件宿主 Xcode 15.x xcode-select 切换 iOS 编译与签名 Kotlin 插件 版本与 Kotlin 一致 语法与同步支持 KMP 项目模板 + Gradle 配置 libs.versions.toml 版本集中管理 build.gradle.kts 目标平台与源集 Gradle Wrapper 固定 8.x 版本 Sync Now 同步校验 Android 调试通道 AVD 模拟器 API 34 / Pixel 7 USB 真机 adb devices 授权 assembleDebug → 安装 APK → Logcat iOS 调试通道 Simulator iPhone 15 真机调试 Team 签名 / 开发者模式 Xcode Run → iosApp 方案 → 控制台日志 commonMain 共享业务逻辑，两端复用

六、常见环境问题与排查顺序

环境问题往往表现为“同步失败”“找不到 SDK”“签名错误”三类。建议按以下顺序排查：

  • Gradle 同步失败：先看 JDK 是否为 17，再看 AGP 与 Gradle 版本是否匹配，最后检查网络代理与仓库地址。
  • 找不到 Android SDK：确认 local.properties 中 sdk.dir 路径正确，且 Android Studio 已安装对应 SDK Platform。
  • iOS 编译报 xcodebuild 错误：执行 xcode-select --switch 切换命令行工具，并确认 Xcode 已同意许可协议。
  • 真机无法安装：Android 检查 USB 调试与设备授权；iOS 检查 Team、Bundle ID 唯一性与设备信任状态。
建议把 JDK、Kotlin、AGP、Gradle、Xcode 五个版本记录在项目 README 中，团队统一使用同一组基线，可显著减少“我这里能跑、你那里报错”的环境差异问题。

完成以上步骤后，一个可用的 KMP 环境应具备：./gradlew tasks 正常列出多平台任务、Android 模拟器可安装运行、iOS 模拟器可编译启动、真机调试通道已授权。此时再进入共享代码编写，才能把精力集中在业务逻辑而非环境修复上。

← 上一章 📖 返回目录 下一章 →