第 2 章：环境搭建与项目创建 - Kotlin Multiplatform 教程

📋 安装要求

开发 KMP 项目（支持 Android + iOS）需要满足以下软硬件要求：

💻 硬件要求

macOS 机器（iOS 开发强制要求）
Apple Silicon (M1+) 推荐，x86 也支持
内存 16GB 推荐（Xcode + Gradle 较重）
存储 50GB 以上空余空间

⚙️ 软件要求

macOS 13 (Ventura) 或更高
JDK 17 或 21（推荐 21）
Android Studio Hedgehog 2023.1.1+
Xcode 15+（iOS 17 SDK）
CocoaPods 或 SPM（iOS 集成）

仅开发 Android 不需要 macOS： 如果你的 KMP 项目只针对 Android，Windows 或 Linux 开发机完全可以。只有需要构建 iOS 目标时，才需要 macOS + Xcode。

☕ 安装 JDK 17+

2.1 使用 SDKMAN（推荐）

        Terminal
# 安装 SDKMAN
curl -s "https://get.sdkman.io" | bash
source "$HOME/.sdkman/bin/sdkman-init.sh"

# 查看可用的 JDK 版本
sdk list java

# 安装 JDK 21 (Temurin 发行版)
sdk install java 21.0.3-tem

# 验证安装
java -version
# 输出：openjdk version "21.0.3" 2024-04-16
    

2.2 使用 Homebrew

        Terminal
# 安装 JDK 21
brew install --cask temurin@21

# 验证
/usr/libexec/java_home -V
    

2.3 配置 JAVA_HOME

        ~/.zshrc
# 添加到 shell 配置文件
export JAVA_HOME=$(/usr/libexec/java_home -v 21)
export PATH=$JAVA_HOME/bin:$PATH
    

🤖 Android Studio 配置

2.4 下载与安装

从 developer.android.com/studio 下载 Android Studio，推荐版本 Meerkat 2024.3.1 或更高。

安装完成后，打开 SDK Manager（Tools → SDK Manager），确保安装：

Android SDK Platform 34（API 34）或更高
Android SDK Build-Tools 34.0.0
Android Emulator
Android SDK Platform-Tools

2.5 配置 Gradle JDK

在 Android Studio 中：Settings → Build, Execution, Deployment → Build Tools → Gradle → Gradle JDK，选择刚安装的 JDK 21。

Gradle 性能优化： 在 ~/.gradle/gradle.properties 中添加以下配置，可明显加快 Gradle 构建速度：

        ~/.gradle/gradle.properties
org.gradle.jvmargs=-Xmx4g -XX:+UseParallelGC
org.gradle.parallel=true
org.gradle.caching=true
kotlin.incremental=true
    

🍎 Xcode 配置

2.6 安装 Xcode

从 Mac App Store 安装 Xcode 15 或更高版本。安装完成后执行：

        Terminal
# 接受 Xcode 许可协议
sudo xcodebuild -license accept

# 安装命令行工具
xcode-select --install

# 验证 Xcode 安装
xcodebuild -version
# 输出：Xcode 15.4  Build version 15F31d
    

2.7 安装 CocoaPods（可选）

如果使用 CocoaPods 集成 KMP Framework（替代 SPM Direct Integration）：

        Terminal
# 安装 CocoaPods
sudo gem install cocoapods

# 验证
pod --version
# 输出：1.15.2
    

🔌 KMP Plugin 安装

在 Android Studio 中安装 Kotlin Multiplatform 插件，该插件提供向导和工具支持。

路径：Settings（⌘,）→ Plugins → Marketplace → 搜索 "Kotlin Multiplatform" → Install

KMM Plugin 已更名： 原来叫 "Kotlin Multiplatform Mobile (KMM)"，现在更名为 "Kotlin Multiplatform"，并扩展支持所有目标平台（不只是移动端）。安装后重启 IDE 生效。

2.8 验证环境（KDoctor）

JetBrains 提供 kdoctor 工具检查 KMP 开发环境是否完整：

        Terminal
# 安装 kdoctor
brew install kdoctor

# 运行检测
kdoctor

# 期望输出（全部 ✓）：
# ✓ Operation System
# ✓ Java (17+)
# ✓ Android Studio
# ✓ Xcode (15+)
# ✓ CocoaPods
    

🧙 KMP Wizard 创建项目

2.9 使用 Web Wizard

访问 kmp.jetbrains.com，这是 JetBrains 官方提供的在线项目生成器。

配置选项：

Project Name：填写项目名，如 NewsApp
Project ID：Bundle ID，如 com.example.newsapp
Targets：勾选 Android + iOS（必选），可选 Desktop / Web
UI Framework：选择 Compose Multiplatform（共享 UI）或 Do Not Share（各平台独立 UI）
点击 Download 下载 ZIP 压缩包

2.10 也可通过 Android Studio 创建

File → New → New Project → Kotlin Multiplatform App（需安装 KMP Plugin）

推荐使用 Web Wizard：比 IDE 向导生成的项目结构更新，直接使用 Version Catalog 管理依赖，符合最新最佳实践。

📁 项目结构详解

使用 Wizard 生成的 KMP 项目（选择 Android + iOS + Compose Multiplatform）结构如下：

        项目目录树
NewsApp/
├── gradle/
│   ├── libs.versions.toml      # 版本目录（依赖统一管理）
│   └── wrapper/
│       └── gradle-wrapper.properties
│
├── composeApp/               # Android + Desktop + Web UI 模块
│   ├── build.gradle.kts
│   └── src/
│       ├── androidMain/         # Android 特有 UI 代码
│       │   └── kotlin/
│       │       └── MainActivity.kt
│       ├── commonMain/          # 共享 Compose UI
│       │   └── kotlin/
│       │       └── App.kt           # 根 Composable
│       └── iosMain/             # iOS 的 Compose 入口
│           └── kotlin/
│               └── MainViewController.kt
│
├── iosApp/                   # Xcode 项目（iOS 原生壳）
│   ├── iosApp.xcodeproj/
│   └── iosApp/
│       ├── ContentView.swift     # 调用 KMP Framework 的 SwiftUI 视图
│       ├── iOSApp.swift
│       └── Info.plist
│
├── shared/                   # 共享业务逻辑模块
│   ├── build.gradle.kts
│   └── src/
│       ├── commonMain/
│       │   └── kotlin/
│       │       └── Greeting.kt   # 示例共享类
│       ├── androidMain/
│       │   └── kotlin/
│       │       └── Platform.android.kt
│       └── iosMain/
│           └── kotlin/
│               └── Platform.ios.kt
│
├── build.gradle.kts              # 根项目 build 配置
├── settings.gradle.kts           # 模块注册
└── local.properties              # Android SDK 路径（本地，不提交 git）
    

2.11 各模块职责说明

shared/ 共享业务逻辑模块。这里放置所有平台无关的代码：数据模型、Repository、网络请求、数据库操作、ViewModel、业务规则。这是 KMP 项目的核心模块。
composeApp/ 包含 Android 主模块（含 MainActivity）和可选的共享 Compose UI 代码（commonMain 下的 App.kt）。如果选择了 CMP，iOS 也会使用这个模块中的 UI。
iosApp/ 标准的 Xcode 项目，作为 iOS 应用的"壳"。它引用 shared/ 编译产生的 XCFramework（或通过 CocoaPods/SPM），调用 Kotlin 代码。
libs.versions.toml Gradle Version Catalog 文件，统一管理所有依赖库的版本号。避免在多个 build.gradle.kts 中重复声明版本，是 KMP 项目的最佳实践。

⚙️ build.gradle.kts 解析

2.12 libs.versions.toml — 版本目录

        gradle/libs.versions.toml
[versions]
kotlin = "2.0.21"
compose = "1.7.0"
compose-plugin = "1.7.0"
ksp = "2.0.21-1.0.28"
ktor = "3.0.0"
sqldelight = "2.0.2"
koin = "4.0.0"
kotlinx-coroutines = "1.9.0"
kotlinx-serialization = "1.7.3"
kotlinx-datetime = "0.6.1"

[libraries]
ktor-client-core = { module = "io.ktor:ktor-client-core", version.ref = "ktor" }
ktor-client-okhttp = { module = "io.ktor:ktor-client-okhttp", version.ref = "ktor" }
ktor-client-darwin = { module = "io.ktor:ktor-client-darwin", version.ref = "ktor" }
ktor-client-content-negotiation = { module = "io.ktor:ktor-client-content-negotiation", version.ref = "ktor" }
ktor-serialization-kotlinx-json = { module = "io.ktor:ktor-serialization-kotlinx-json", version.ref = "ktor" }

sqldelight-android-driver = { module = "app.cash.sqldelight:android-driver", version.ref = "sqldelight" }
sqldelight-native-driver = { module = "app.cash.sqldelight:native-driver", version.ref = "sqldelight" }

kotlinx-coroutines-core = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-core", version.ref = "kotlinx-coroutines" }
kotlinx-serialization-json = { module = "org.jetbrains.kotlinx:kotlinx-serialization-json", version.ref = "kotlinx-serialization" }
kotlinx-datetime = { module = "org.jetbrains.kotlinx:kotlinx-datetime", version.ref = "kotlinx-datetime" }

koin-core = { module = "io.insert-koin:koin-core", version.ref = "koin" }
koin-android = { module = "io.insert-koin:koin-android", version.ref = "koin" }

[plugins]
kotlinMultiplatform = { id = "org.jetbrains.kotlin.multiplatform", version.ref = "kotlin" }
androidLibrary = { id = "com.android.library", version = "8.5.2" }
composeMultiplatform = { id = "org.jetbrains.compose", version.ref = "compose-plugin" }
composeCompiler = { id = "org.jetbrains.kotlin.plugin.compose", version.ref = "kotlin" }
kotlinSerialization = { id = "org.jetbrains.kotlin.plugin.serialization", version.ref = "kotlin" }
sqldelight = { id = "app.cash.sqldelight", version.ref = "sqldelight" }
    

2.13 shared/build.gradle.kts

        shared/build.gradle.kts
plugins {
    alias(libs.plugins.kotlinMultiplatform)
    alias(libs.plugins.androidLibrary)
    alias(libs.plugins.kotlinSerialization)
    alias(libs.plugins.sqldelight)
}

kotlin {
    androidTarget {
        compilations.all {
            kotlinOptions { jvmTarget = "17" }
        }
    }

    // iOS 目标（三合一 XCFramework）
    val xcf = XCFramework()
    val iosTargets = listOf(iosX64(), iosArm64(), iosSimulatorArm64())
    iosTargets.forEach {
        it.binaries.framework {
            baseName = "shared"
            xcf.add(this)
        }
    }

    sourceSets {
        commonMain.dependencies {
            implementation(libs.kotlinx.coroutines.core)
            implementation(libs.kotlinx.serialization.json)
            implementation(libs.kotlinx.datetime)
            implementation(libs.ktor.client.core)
            implementation(libs.ktor.client.content.negotiation)
            implementation(libs.ktor.serialization.kotlinx.json)
            implementation(libs.koin.core)
        }
        androidMain.dependencies {
            implementation(libs.ktor.client.okhttp)
            implementation(libs.sqldelight.android.driver)
        }
        iosMain.dependencies {
            implementation(libs.ktor.client.darwin)
            implementation(libs.sqldelight.native.driver)
        }
    }
}

android {
    namespace = "com.example.newsapp.shared"
    compileSdk = 35
    defaultConfig { minSdk = 26 }
}

// SQLDelight 配置
sqldelight {
    databases {
        create("AppDatabase") {
            packageName.set("com.example.newsapp.db")
        }
    }
}
    

▶️ 运行验证

2.14 运行 Android

在 Android Studio 中：

在工具栏选择 composeApp 配置
选择 Android 模拟器（推荐 Pixel 7 API 34）
点击运行按钮（▶）或按 Ctrl+R

        Terminal — 命令行运行
# 构建 Debug APK
./gradlew assembleDebug

# 安装到已连接设备
./gradlew installDebug

# 运行 Android 测试
./gradlew connectedAndroidTest
    

2.15 运行 iOS

方法一（推荐）：在 Android Studio 工具栏选择 iOS 模拟器配置，直接运行。

方法二：先编译 shared Framework，再用 Xcode 运行。

        Terminal
# 编译 iOS 模拟器 Framework
./gradlew :shared:linkDebugFrameworkIosSimulatorArm64

# 打开 Xcode 项目
open iosApp/iosApp.xcodeproj

# 或者构建 XCFramework（用于发布）
./gradlew :shared:assembleXCFramework
    

2.16 验证共享代码运行

项目模板中包含一个 Greeting 类，演示 expect/actual 机制：

        shared/src/commonMain/kotlin/Greeting.kt
class Greeting {
    private val platform = Platform()

    fun greet(): String {
        return "Hello, ${platform.name}!"
    }
}

// Android 运行结果：Hello, Android!
// iOS 运行结果：Hello, iOS!
    

🎯 实践任务

运行 kdoctor，确保所有检查项均为 ✓
使用 KMP Wizard 创建一个名为 HelloKMP 的项目
在 Android 模拟器和 iOS 模拟器上各运行一次，观察 Greeting.greet() 的输出差异
在 shared/commonMain 中添加一个新的 expect 函数，并在 androidMain 和 iosMain 中提供 actual 实现

上一章 ← KMP 简介与生态下一章共享模块架构 →