跨平臺之 KMP / KMM 詳解

任何事情，急于求成都是幼稚的幻想，急于求成的結果一定是不成，對此不應該有任何懷疑。

一. KMP 和 Compose Multiplatform

摘要：減少為不同平臺編寫和維護相同業務邏輯代碼所花費的時間，同時又能保留 NA 編程的錄活性和優勢。

在移動應用開發領域，Kotlin Multiplatform Mobile (KMM) 和 Compose Multiplatform 的結合正在成為一種強大的解決方案。它們不僅解決了傳統跨平臺開發中的諸多痛點，還提供了許多獨特的優勢，使得開發者能夠更加高效地構建和維護跨平臺應用。以下是它的主要優勢：

代碼復用
KMM 和 Compose Multiplatform 允許開發者在 Android 和 iOS 之間共享大部分代碼，包括業務邏輯和 UI 組件。
性能優化
與某些其他跨平臺框架不同，KMM 生成的代碼是直接運行在目標平臺的原生環境中的。這意味著開發者可以享受到與原生開發相同的性能和系統級優化。
平臺特性和靈活性
KMM 通過 expect 和 actual 關鍵字，允許開發者為不同的平臺編寫特定的實現。這種靈活性使得開發者可以充分利用各個平臺的特性，而不會妥協于跨平臺的限制。Compose Multiplatform 同樣支持這種靈活性，確保 UI 設計可以根據平臺的需求進行優化。
一致的開發體驗
Kotlin 作為一種現代語言，擁有簡潔的語法和強大的功能特性，深受開發者喜愛。利用 Kotlin 和 Compose Multiplatform，開發者能夠在相同的開發環境中進行多平臺開發，提升了開發者的體驗和生產力。使用 Android Studio 和 Xcode 無縫集成，開發者可以在熟悉的 IDE 中進行跨平臺開發和調試。
現代化的 UI 構建
Compose Multiplatform 基于聲明式編程范式，簡化了復雜的 UI 構建。開發者可以通過簡明的代碼定義動態界面，減少了樣板代碼和 UI 更新的復雜度。這種現代化的 UI 構建方式，不僅使代碼更加清晰和易于維護，還提升了開發效率。

使用 KMM 和 Compose Multiplatform，開發團隊可以在保證高性能和平臺特性的同時，實現代碼的最大復用和開發效率的提升。這種結合不僅為項目帶來了顯著的優勢，還為開發者提供了創新和靈活的開發體驗。

1. 基礎概念

什么是 Kotlin Multiplatform (KMP)?

Kotlin Multiplatform (KMP) 是 JetBrains 提供的一項功能，允許使用 Kotlin 編寫可以在多個平臺上運行的代碼。KMP 的目標是通過共享業務邏輯代碼來減少不同平臺開發的重復工作。KMP 支持的平臺包括但不限于：

JVM：用于服務器端開發以及 Android 開發。

JavaScript：用于前端 Web 開發。

原生平臺 (Native)：如 iOS、Windows、macOS、Linux 等。

什么是 Kotlin Multiplatform Mobile (KMM)?

Kotlin Multiplatform Mobile (KMM) 是專注于移動平臺的一種 KMP 實現。KMM 讓開發者能夠使用 Kotlin 編寫可以在 Android 和 iOS 上運行的共享代碼，主要關注點是在移動設備上的應用開發。簡單來說，KMM 是 KMP 的一個子集或特化實現，專注于移動開發。

什么是 Compose multiform？

Compose Multiplatform 是 JetBrains 開發的一種跨平臺用戶界面 (UI) 框架，它基于 Kotlin 和 Jetpack Compose 的設計理念，旨在通過聲明式編程范式簡化 跨平臺 UI 構建。

什么是 Kotlin/Native、Kotlin/JVM、Kotlin/JS？與 KMP 的關系？

Kotlin 是一種現代化的編程語言，由 JetBrains 開發，支持多平臺開發，包括 JVM、JavaScript 和原生平臺。為了更高效地開發跨平臺應用，Kotlin 提供了三種主要的編譯器后端：Kotlin/JVM、Kotlin/JS 和 Kotlin/Native。

Kotlin/JVM 是最初的 Kotlin 編譯器后端，也是最常用的一種。它將 Kotlin 代碼編譯成可以在 Java 虛擬機 (JVM) 上運行的字節碼。由于 Kotlin 與 Java 高度互操作，Kotlin/JVM 可以直接利用現有的 Java 庫和框架，使得開發者能夠輕松地將 Kotlin 與 Java 項目集成。使用場景有 Android 開發與服務器開發。

Kotlin/JS 將 Kotlin 編譯為 JavaScript 代碼，從而可以在瀏覽器或 Node.js 環境中運行。Kotlin/JS 使得前端開發者可以使用 Kotlin 編寫網頁應用，同時充分利用現有的 JavaScript 庫和框架。使用場景是 Web 前端開發。

Kotlin/Native 將 Kotlin 編譯為原生二進制代碼，可以直接運行在不依賴 JVM 或 JavaScript 引擎的環境中。Kotlin/Native 支持多種平臺，包括 iOS、Windows、MacOS、Linux、嵌入式設備等，甚至于 Android、鴻蒙也可以使用 KN 跨平臺開發（需要編寫 JNI or NAPI 橋接代碼）。KMP 結合了 Kotlin/JVM、Kotlin/JS 和 Kotlin/Native 的優勢，使開發者能夠在統一的代碼庫中，針對不同平臺進行開發，實現跨平臺方案。

2. KMP 核心原理

》http://www.rzrgm.cn/liqw/p/15416758.html

2.1 特定于平臺的 API 和實現

expect/actual 機制：

KMM 里 expect/actual 機制是非常重要的，因為它提供了一種語法技術來解決平臺相關的問題。舉例來說，當我們需要在業務邏輯中使用設備的 model 號時，我們需要編寫特定平臺的代碼才能實現。這時，expect 就相當于聲明一個協議，它定義了我們期望得到的接口或數據，之后各個平臺都需要獨立地實現這個協議來滿足業務需要。

可能會有人認為這樣寫了兩遍，每個平臺都寫一遍不如讓各個平臺自己去寫。但是，這種方式只需要建設一次，就像一些基礎庫一樣只需要做一次就能在后面被大家共用。這種共用甚至不限于公司界，整個業界都可以共用一組基礎庫。

基本流程如下：在 commonMain 目錄下建立一個 expect 類或 Top-Level 方法 , 類似創建一個協議聲明。分別在 androidMain 和 iosMain 目錄中，創建與 expect 聲明（類名、方法名、參數類型及名稱）完全一致的實現，否則編譯器會報錯。

1）平臺抽象接口設計?

interface Platform { val name: String }

?作用?：定義跨平臺共享的接口規范，聲明所有平臺必須實現的 name 屬性，用于獲取當前運行平臺的名稱（如“Android”“iOS”）?。
?設計邏輯?：通過接口強制各平臺實現統一功能，保障代碼在跨平臺調用時的行為一致性?。

2）多平臺預期聲明?

expect fun getPlatform(): Platform

?expect 關鍵字?：聲明一個需由各平臺?具體實現?的公共函數，遵循 Kotlin Multiplatform 的 expect/actual 機制?。
?函數功能?：調用此函數將返回實現了 Platform 接口的平臺專屬對象，實現?編譯時多態??。

?3）平臺專屬實現示例?

?Android 端實現 (androidMain)?：

actual fun getPlatform(): Platform = AndroidPlatform()

class AndroidPlatform : Platform {
    override val name: String = "Android ${android.os.Build.VERSION.SDK_INT}"
}

?actual 關鍵字?：對應 expect 聲明的具體實現，編譯時根據目標平臺自動匹配?。
?實現細節?：通過 Android SDK 獲取系統版本號，增強平臺特性識別能力?。

?iOS 端實現 (iosMain)?：

actual fun getPlatform(): Platform = IosPlatform()

class IosPlatform : Platform {
    override val name: String = UIDevice.currentDevice.systemName()
}

?平臺交互?：調用 iOS 原生 API UIDevice 獲取設備信息，體現平臺特定代碼隔離原則?。

4）核心設計模式?

?分層架構?：將?平臺無關邏輯?置于 commonMain，?平臺相關實現?隔離在 androidMain/iosMain 等目錄?。
?關注點分離?：通過接口抽象和 expect/actual 機制，實現業務邏輯與平臺特性的解耦，提升代碼復用率?。

該設計是 Kotlin Multiplatform 項目的典型結構，通過標準化的接口與平臺適配層，支撐跨平臺應用的統一功能開發?。

2.2 直接訪問 iOS Framework 的核心原理

KMM 項目中 iosMain 能直接訪問 iOS Framework 的核心原理，主要依賴以下三層技術機制：

2.2.1 跨平臺代碼分層機制

通過 expect/actual 聲明與實現分離：此機制實現?接口統一聲明、平臺獨立實現?的架構?。

2.2.2 CInterop 原生接口綁定

Kotlin/Native 通過 cinterop 工具生成 Objective-C/Swift 綁定的中間層：

1）生成綁定文件?

掃描 iOS Framework 的 .h 頭文件。
自動生成 Kotlin 可調用的 klib 接口文件（包含類/方法映射）?。

2）Swift 兼容處理

Swift 方法需添加 @objc 修飾符，確?？杀?Objective-C 運行時識別?

@objc class DeviceHelper: NSObject {
    @objc static func getModel() -> String { /*...*/ }
}

2.2.3 編譯期代碼轉換

Kotlin/Native 編譯器將代碼轉換為 iOS 可識別的二進制格式：

1）編譯階段?

iosMain 代碼會被編譯為 ?Mach-O 格式?的 Framework 或靜態庫?。
自動嵌入 Kotlin/Native 運行時（約 1MB）以支持跨平臺特性?。

2）產物集成

輸出 .framework 文件，包含：
- 編譯后的二進制代碼。
- Objective-C 頭文件（自動生成）。
- 資源文件（如有）?。
Xcode 工程直接依賴該 Framework 即可調用?。

2.2.4 整體交互流程和技術對比

整體交互流程：

graph TD
    A[Kotlin Common] -->|expect 聲明| B(iosMain)
    B -->|cinterop 綁定| C[iOS Framework]
    C -->|編譯為 Mach-O| D(Xcode 工程)
    D -->|動態鏈接| E(UIKit 等系統框架)

技術優勢對比

特性	KMM 實現方式	傳統跨平臺方案
?API 調用方式?	直接訪問原生 Framework?	通過橋接層間接調用
?性能損耗?	無額外運行時開銷（原生二進制）?	常有解釋器/JIT 損耗
?代碼復用率?	邏輯層 100% 復用，UI 層獨立?	全棧強制統一

這一設計使得 KMM 在保持原生性能的同時，實現了邏輯代碼的跨平臺復用?。

2.3 cinterop 生成中間層時機

Kotlin/Native 的 cinterop 工具生成 Objective-C/Swift 綁定的中間層，其生成時機和觸發條件如下：

2.3.1 生成時機

1）編譯期動態生成?

綁定文件?不會在新建項目時自動生成?，而是在?首次執行構建任務?（如運行 ./gradlew build）時觸發生成流程?。
每次修改 .def 配置文件或原生頭文件后，重新構建時會?增量更新綁定文件??。

2）條件觸發機制?

僅當項目中聲明了 cinterop 依賴且配置了原生框架調用時才會生成

// build.gradle.kts 配置示例  
kotlin {  
    iosX64() {  
        compilations.getByName("main") {  
            cinterops.create("UIKit") {  
                defFile("src/nativeInterop/cinterop/UIKit.def")  
            }  
        }  
    }  
}

此時才會生成對應的 klib 和頭文件?

2.3.2 生成路徑與產物

階段	產物路徑	文件類型
?初始生成?	`build/bin/native/cinterop/`	`.klib` (Kotlin庫)
?編譯后集成?	`build/bin/iosX64/debugFramework/`	`.framework` (二進制)
?頭文件映射?	`build/generated/cinterop/`	`.h` (Objective-C頭文件)?

2.3.3 生成流程對比

項目狀態	綁定文件狀態	觸發動作
新建空項目	? 未生成	需手動配置 `cinterop`
配置原生依賴后	? 生成在構建目錄	執行 Gradle 構建任務
更新頭文件/配置后	? 增量更新	重新編譯?

2.3.4 技術實現原理

1）?構建管道集成?：cinterop 作為 Kotlin/Native 編譯管道的前置步驟，通過 Gradle 插件與構建系統深度集成?。

graph LR  
    A[Gradle Task] --> B(cinterop 解析 .def 文件)  
    B --> C(生成 .klib 和 .h)  
    C --> D(Kotlin/Native 編譯)

2）動態適配機制?：當檢測到 src/nativeInterop/cinterop 目錄下的 .def 配置文件時，自動注冊生成任務?。

2.3.5 總結

?非預生成?：綁定文件不會在新建項目時預生成，需通過構建任務觸發。
?按需生成?：僅在聲明特定平臺（如 iosMain）且配置原生依賴時生成?。
?持續更新?：頭文件或配置變更后，通過重新編譯實現動態更新?

二. KMM 環境搭建

1. KDoctor

kdoctor 是一個用于驗證 Kotlin Multiplatform Mobile (KMM) 開發環境是否正確配置的命令行工具。它會檢查系統上的各種依賴和配置，確保已經安裝并正確配置了所有必要的軟件，例如 Android Studio、Xcode、CocoaPods 等。如果是第一次設置 KMM 環境，強烈建議使用 kdoctor 來確認一切都已正確配置。

安裝 kdoctor

對于 macOS 系統：

確保 Homebrew 已安裝，安裝 kdoctor

brew install kdoctor

使用 kdoctor 進行環境檢查

安裝完 kdoctor 后，通過以下命令檢查 KMM 開發環境：

kdoctor

kdoctor 將檢查以下內容：

JDK：是否安裝了 Java Development Kit。
Android Studio：是否安裝了 Android Studio 和必要的組件。
Xcode：是否安裝了 Xcode 和命令行工具。
CocoaPods：是否安裝了 CocoaPods（用于管理 iOS 依賴）。

運行 kdoctor 后的示例輸出：

$ kdoctor  
[ ? ] Checking the Java version (11.0.8).   
[ ? ] Checking the Android Studio installation.   
[ ? ] Checking the Xcode installation.   
[ ? ] Checking the CocoaPods installation.   
Conclusion:
  ? Your operation system is ready for Kotlin Multiplatform Mobile Development!

如果 kdoctor 報告某些組件未正確安裝或配置，按照指導信息進行相應的操作來解決問題。在這個示例輸出中，kdoctor 表明所有必要的軟件都已正確安裝，已準備好進行 KMM 開發。

2. Kotlin Multiplatform Plugin

在 Android Studio 中安裝 Kotlin Multiplatform 插件：打開 Android Studio，進入 Settings -> Plugins，搜索并安裝 Kotlin Multiplatform 插件，重啟 Android Studio 以激活插件。

三. 項目構建和解析

》https://blog.csdn.net/logicsboy/article/details/128856861

1. 新建 KMM 項目

打開 Android Studio，選擇 New Project。在項目模板中，選擇 Kotlin Multiplatform App。配置項目名稱、保存路徑和包名。

2. 項目架構和配置

生成的 KMM 項目包含 Android 和 iOS 兩個平臺的代碼，以及一個共享代碼模塊：

Kmm/  
 ├── .gradle/ # 構建緩存文件
 ├── .idea/ # IDE 配置和元數據
 ├── android/ # Android 殼工程
 ├── gradle/  # gradle 環境管理
 ├── ios/     # iOS 殼工程
 ├── shared/  # 共享代碼（業務、UI組件、資源）模塊
 │   ├── build/
 │   ├── src/  
 │   │   ├── commonMain/ # 共享邏輯  
 │   │   ├── androidMain/  # Android 平臺代碼  
 │   │   ├── iosMain/     # iOS 平臺代碼  
 │   ├── build.gradle.kts
 │   ├── shared.podspec
 ├── .gitignore/ # Git 配置文件
 ├── build.gradle.kts/ # Gradle 構建工具的核心配置文件
 ├── gradle.properties/ # Gradle 構建工具的核心配置文件
 ├── gradlew/ # Gradle Wrapper 的啟動腳本
 ├── gradlew.bat/ # Gradle Wrapper 的啟動腳本
 ├── local.properties/ # 存儲本地敏感配置禁止提交到版本控制
 └── settings.gradle.kts/ # Gradle 構建系統的核心配置文件

.gradle 文件夾是 ?Gradle 構建工具?在運行過程中生成的緩存和臨時文件目錄，主要用于加速構建流程和管理項目依賴。

.idea IDE 配置和元數據，Android Studio 基于 IntelliJ IDEA 開發，所有項目（包括 KMM）在首次打開時都會自動生成 .idea 目錄，用于加載和存儲配置?。

android 移動安卓殼工程。

gradle gradle 環境管理。

gradle-wrapper.jar?：Gradle 環境啟動器，實現版本自動化管理 ?。負責根據 gradle-wrapper.properties 中定義的版本自動下載并安裝指定版本的 Gradle?。
?gradle-wrapper.properties?：定義所需的 Gradle 版本和下載源，保障跨環境一致性。

ios 移動 iOS 殼工程。

share 共享代碼模塊，目前僅包含業務邏輯，還可以添加 UI 組件、資源等。

.gitignore 是 Git 版本控制系統中一個 ?純文本配置文件?，用于指定 Git 倉庫中需要 ?永久忽略跟蹤? 的文件或目錄。它的核心作用是 ?過濾無需納入版本控制的文件?（如臨時文件、編譯產物、本地環境配置等），避免這些文件被意外提交到倉庫中。

build.gradle.kts

KMM（Kotlin Multiplatform Mobile）項目中，build.gradle 文件是 ?Gradle 構建工具?的核心配置文件，用于定義項目的構建規則、依賴關系和插件設置。

gradle.properties

在 KMM（Kotlin Multiplatform Mobile）項目中，gradle.properties 文件是 ?Gradle 構建工具的核心配置文件?，用于定義全局屬性、控制構建行為以及優化構建性能。

.gradlew .gradlew.bat

在新建 Kotlin Multiplatform Mobile (KMM) 項目時，生成的 ?.gradlew?（Unix/Linux/macOS）和 ?.gradlew.bat?（Windows）文件是 ?Gradle Wrapper 的啟動腳本?。它們的作用是統一項目的構建環境，確保開發者無需預先安裝特定版本的 Gradle，也能正確構建項目。

local.properties 存儲本地敏感配置禁止提交到版本控制。

settings.gradle

在 Kotlin Multiplatform Mobile (KMM) 項目中，settings.gradle 是 ?Gradle 構建系統的核心配置文件?，主要負責定義項目結構、管理子模塊和配置構建行為??。

四. 配置文件詳解

1. build.gradle

在 KMM（Kotlin Multiplatform Mobile）項目中，build.gradle 文件是 ?Gradle 構建工具?的核心配置文件，用于定義項目的構建規則（邏輯）、模塊級依賴關系和插件設置、任務等構建邏輯，屬于代碼的一部分。以下是它在 KMM 項目中的具體作用：定義構建邏輯、依賴關系。

1.1 `build.gradle` 的作用

Gradle 使用 build.gradle 文件來配置：

?項目級設置?：定義整個項目的構建規則、公共插件、倉庫和依賴版本。
?模塊級設置?：針對每個子模塊（如共享模塊、Android App、iOS 框架）配置構建規則。
?多平臺支持?：聲明 Kotlin Multiplatform 的目標平臺（Android、iOS、JVM 等）。
?依賴管理?：聲明項目所需的庫（如 Kotlin 標準庫、第三方庫）。

1.?2 KMM 項目的典型結構

一個 KMM 項目通常包含以下 build.gradle 文件。

1.2.1 項目根目錄的 `build.gradle`

?作用?：全局配置，定義構建工具、以及所有子模塊共享的規則。

?示例：

// 根項目的 build.gradle
// 構建工具本身，構建初始化階段
buildscript {
    repositories {
        google()
        mavenCentral()
    }
    dependencies {
        // 定義全局使用的 Gradle 插件版本（如 Android 插件、Kotlin 插件）
        classpath "com.android.tools.build:gradle:7.0.4"
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:1.6.10"
    }
}

// 所有子模塊共享的配置，配置模塊的業務依賴倉庫地址，項目配置階段。項目模塊的實際依賴（如 implementation、api）應寫在?模塊級? build.gradle 中，而非 allprojects 塊內
allprojects {
    repositories {
        google()
        mavenCentral()
    }
}

// 根項目自身?（非子模塊）	根項目需單獨使用的插件或依賴	根項目解析階段。若根項目無特殊依賴需求，可省略單獨 repositories 塊，避免冗余
repositories {
    mavenCentral()
}

1.2.2 共享模塊的 `build.gradle`

?作用?：配置跨平臺代碼的構建規則（如 Android 和 iOS 的共享邏輯）。

?示例：

// 共享模塊的 build.gradle
plugins {
    id 'org.jetbrains.kotlin.multiplatform'
}

// 定義目標平臺：聲明編譯目標、啟用多平臺特性、配置平臺專屬依賴
kotlin {
    // 定義多平臺目標
    android()  // Android 平臺
    iosArm64 { // iOS 設備（ARM64）
        binaries.framework { // 生成 iOS 框架
            baseName = "Shared"
        }
    }
    sourceSets {} // 源集配置
}

// Android 特定配置
android {
    compileSdkVersion 31
    defaultConfig {
        minSdkVersion 21
        targetSdkVersion 31
    }
}

// 依賴聲明
dependencies {
    // 公共依賴（所有平臺共享）
    commonMain.dependencies {
        implementation "org.jetbrains.kotlin:kotlin-stdlib-common"
    }
    // Android 專屬依賴
    androidMain.dependencies {
        implementation "org.jetbrains.kotlin:kotlin-stdlib"
    }
}

1.2.3 Android App 模塊的 `build.gradle`

?作用?：配置 Android 應用的構建規則。

?示例：

plugins {
    id 'com.android.application'
    id 'kotlin-android'
}

android {
    compileSdk 31
    defaultConfig {
        applicationId "com.example.kmmapp"
        minSdk 21
        targetSdk 31
    }
}

dependencies {
    implementation project(":shared")  // 依賴共享模塊
    implementation "androidx.core:core-ktx:1.7.0"
}

1.2.4 iOS 模塊的配置?

說明?：iOS 代碼通常通過共享模塊生成的框架（.framework）集成到 Xcode 項目，無需單獨的 build.gradle。

?1.3 關鍵配置解析?

1）多平臺目標聲明?

通過 kotlin { ... } 塊定義支持的平臺：

kotlin {
    android()       // Android 平臺
    iosArm64()      // iOS 真機 (ARM64)
    iosSimulatorArm64() // iOS 模擬器 (Apple Silicon)
    jvm()           // JVM 平臺（可選）
}

2) 依賴分類?\定義依賴項

KMM 支持按平臺細分依賴：

dependencies {
    // 公共依賴（所有平臺共享）
    commonMain.dependencies {
        implementation "io.ktor:ktor-client-core:2.0.0"
    }
    // Android 專屬依賴
    androidMain.dependencies {
        implementation "io.ktor:ktor-client-android:2.0.0"
    }
    // iOS 專屬依賴
    iosMain.dependencies {
        implementation "io.ktor:ktor-client-ios:2.0.0"
    }
}

3) iOS 框架生成?

配置共享模塊生成 iOS 可用的框架：

kotlin {
    iosArm64 {
        binaries.framework {
            baseName = "Shared"  // 框架名稱
            export(project(":shared")) // 導出其他模塊（可選）
        }
    }
}

4) 定義插件 Plugins?

plugins {
    id("com.android.application")
    kotlin("android")
}

1.?4 常見問題與解決

1) 依賴解析失敗?

?表現?：Could not resolve ... 錯誤。
?解決：
- 檢查倉庫是否包含 google() 和 mavenCentral()。
- 確保網絡可以訪問倉庫（國內可嘗試阿里云鏡像）。

2) 插件版本沖突?

?表現?：Unsupported Kotlin plugin version。

?解決：統一 Kotlin 插件版本：

// 根項目的 build.gradle
classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:1.6.10"

3) iOS 構建失敗?

?表現?：Framework not found。
?解決?：
- 運行 ./gradlew :shared:packForXcode 重新生成框架。
- 在 Xcode 中清理構建緩存（Product > Clean Build Folder）。

1.?5 總結?

build.gradle 在 KMM 項目中是構建流程的核心控制器?，負責：

定義多平臺目標和編譯規則。
管理跨平臺依賴。
集成 Android 和 iOS 的構建配置。
生成 iOS 框架供 Xcode 使用。

通過合理配置 build.gradle，你可以實現一套代碼在 Android 和 iOS 之間的高效共享，同時保持平臺特定邏輯的靈活性。

2. gradle.properties

在 KMM（Kotlin Multiplatform Mobile）項目中，gradle.properties 文件是 ?Gradle 構建工具的核心配置文件?，用于定義全局屬性（變量）、控制構建環境（Gradle 運行參數，主要用于定義行為和優化構建性能）。它在 Android Studio 項目中扮演以下關鍵角色。

2.1 ?配置 Gradle 構建環境

通過 gradle.properties，你可以調整 Gradle 本身的運行參數：

?JVM 內存分配：優化構建速度，避免內存溢出。

# 增加 Gradle 堆內存
org.gradle.jvmargs=-Xmx4096m -Dfile.encoding=UTF-8

?啟用構建緩存?：加速重復構建。
```
# 開啟緩存
org.gradle.caching=true
```

?并行執行和多項目構建：

# 并行執行任務
org.gradle.parallel=true
# 多項目構建優化
org.gradle.configureondemand=true

2.2 ?定義項目全局變量

在 gradle.properties 中定義的變量，可以在所有模塊的 build.gradle.kts 或 build.gradle 文件中直接引用，方便統一管理版本號和通用配置：

# 定義公共版本號
kotlin_version=1.8.21
androidGradlePlugin_version=7.4.2

在 build.gradle.kts 中使用：

plugins {  	  kotlin("multiplatform").version(project.property("kotlin_version") as String)
}

2.3 ?控制 KMM 多平臺構建行為

KMM 項目依賴 Kotlin/Native 編譯器，gradle.properties 可以配置 Native 編譯參數：

# 啟用 Kotlin/Native 內存模型（新版本默認啟用）
kotlin.native.binary.memoryModel=strict
# 禁用 iOS 模擬器 arm64 目標（解決 M1/M2 芯片兼容性問題）
kotlin.native.disableCompilerDaemon=true

2.4 ?管理 Android 和 iOS 構建配置

?Android 構建優化：

# 啟用 Android Jetpack Compose
android.enableCompose=true
# 禁用不必要的 Lint 檢查
android.enableBuildCache=true

?iOS 構建配置：

# 指定 Xcode 兼容版本
kotlin.ios.teamId=XXXXXXXXXX

2.?5. ?配置代理和倉庫鏡像

解決國內依賴下載慢的問題：

# 使用阿里云鏡像加速
systemProp.http.proxyHost=mirrors.aliyun.com
systemProp.http.proxyPort=80
systemProp.https.proxyHost=mirrors.aliyun.com
systemProp.https.proxyPort=80

2.6 ?啟用實驗性功能

對于 KMM 或 Kotlin 的實驗性特性，需在此顯式啟用：

# 啟用 Kotlin 新內存管理器（跨平臺內存共享）
kotlin.native.enableExperimentalMemoryManager=true
# 啟用 Jetpack Compose Multiplatform
org.jetbrains.compose.experimental.kotlin.multiplatform=true

2.7 ?解決常見構建問題

通過 gradle.properties 快速修復構建錯誤：

?Kotlin/Native 編譯器版本沖突：
```
kotlin.native.version=1.8.21
```
?禁用 Precompiled Script Plugins（舊版本 Gradle 兼容）：
```
org.gradle.unsafe.allow-incompatible-plugins=false
```

2.8 文件位置與優先級?

?項目級?：<project-root>/gradle.properties
僅影響當前項目。
?全局級?：~/.gradle/gradle.properties
影響所有 Gradle 項目（謹慎使用）。

2.9 KMM 項目典型配置示例

# Gradle 配置
org.gradle.jvmargs=-Xmx4096m -Dfile.encoding=UTF-8
org.gradle.caching=true

# Kotlin 版本
kotlin_version=1.8.21

# Android 配置
android.useAndroidX=true
android.enableCompose=true

# KMM/Native 配置
kotlin.native.binary.memoryModel=strict
kotlin.mpp.enableGranularSourceSetsMetadata=true

# 國內鏡像加速
systemProp.http.proxyHost=mirrors.aliyun.com
systemProp.https.proxyHost=mirrors.aliyun.com

注意事項：

?鍵值對格式?：必須使用 key=value 格式，且不能有多余的空格。
?類型限制?：所有值均為字符串，需在 build.gradle.kts 中按需轉換類型。
?版本兼容性?：部分屬性（如 kotlin.native.binary.memoryModel）需與 Kotlin 版本匹配，否則構建會失敗。

通過合理配置 gradle.properties，你可以顯著提升 KMM 項目的構建性能和跨平臺開發體驗。

3. local.properties

local.properties 是本地開發環境專屬的配置文件?，主要用于存儲與開發者機器強相關的路徑、密鑰等敏感信息，避免將這些內容暴露在版本控制中（禁止提交到版本控制）。以下是其核心功能與使用規范：

3.1 核心作用?

1）配置本地開發環境路徑

定義 Android SDK、NDK 的本地路徑（不同開發者機器路徑不同）?。

sdk.dir=/Users/xxx/Library/Android/sdk  
ndk.dir=/Users/xxx/Library/Android/ndk

用于 Gradle 構建時自動識別 Android 開發環境依賴?。

2）存儲敏感信息?

本地調試密鑰路徑及密碼?：

debug.keystore=/path/to/debug.keystore  
keyAlias=debug  
keyPassword=123456  
storePassword=123456

私有 API 密鑰或其他環境變量（如測試服務器地址）?。

3）隔離團隊協作差異

避免因開發者本地環境差異（如 SDK 路徑）導致構建失敗，文件默認不提交至 Git 等版本控制系統?。

3.2 典型配置內容

?配置項?	?示例值?	?用途?
`sdk.dir`	`/Users/xxx/Library/Android/sdk`	指定 Android SDK 安裝路徑?。
`ndk.dir`	`/Users/xxx/Library/Android/ndk/5.2.9`	指定 NDK 路徑（如需使用 JNI/Native 代碼）?。
`debug.keystore`	`/path/to/debug.keystore`	本地調試 APK 的簽名文件路徑?。
`custom.api.key`	`your_private_key`	自定義 API 密鑰（如地圖服務、支付 SDK）?。

3.3 ?在 KMM 項目中的使用方式

1）?讀取配置?

在 build.gradle 中通過代碼讀取配置（以 Android 模塊為例）?：

def localProperties = new Properties()  
localProperties.load(new FileInputStream(rootProject.file("local.properties")))  

android {  
    signingConfigs {  
        debug {  
            storeFile file(localProperties["debug.keystore"])  
            storePassword localProperties["storePassword"]  
            keyAlias localProperties["keyAlias"]  
            keyPassword localProperties["keyPassword"]  
        }  
    }  
}

2）動態注入環境變量

通過 Gradle 參數傳遞 local.properties 中的值到代碼中（如 API 密鑰）?：

android {  
    defaultConfig {  
        buildConfigField "String", "API_KEY", "\"${localProperties["api.key"]}\""  
    }  
}

在代碼中通過訪問：

BuildConfig.API_KEY

3.4 ?最佳實踐?

?禁止提交至版本控制

將 local.properties 加入 .gitignore，防止敏感信息泄露?。
?提供模板文件

?創建 local.properties.template 并提交，指導團隊成員復制后填寫本地路徑?。
?統一環境管理

?團隊協作時，通過文檔說明配置項含義及填寫規范（如 SDK 版本要求）?。

3.5 與 `gradle.properties` 的區別

?對比項?	`local.properties`	`gradle.properties`
?作用范圍?	僅本地環境生效	全局項目生效（所有開發者共享）?。
?典型內容?	SDK 路徑、密鑰等敏感信息	JVM 內存、構建緩存開關、插件版本?。
?是否共享?	否	是

總結?：local.properties 是 KMM 項目中用于隔離本地環境差異的核心文件，通過存儲敏感信息和機器特定路徑，確保團隊協作時構建流程的穩定性和安全性?

4. settings.gradle

在 Kotlin Multiplatform Mobile (KMM) 項目中，settings.gradle 是 ?Gradle 構建系統的核心配置文件?，主要負責定義項目結構、管理子模塊和配置構建行為??。以下是其核心作用：

4.1 聲明項目包含的模塊

?核心功能：通過 include 函數明確項目中包含哪些子模塊（如共享代碼模塊、Android/iOS 平臺模塊）?。示例代碼?（KMM 典型配置）：
```
// 包含共享模塊、Android 和 iOS 平臺模塊
include ':shared', ':androidApp', ':iosApp'
```
?多平臺適配?：在 KMM 中，通常將跨平臺邏輯放在 shared 模塊，并通過 include 聲明其與平臺模塊的關聯?。

4.2 定義模塊路徑

?調整模塊路徑：若模塊不在默認路徑下（如將 iOS 模塊放在 ios 目錄），需通過 project 函數指定路徑?。示例：
```
include ':shared', ':androidApp'
// 指定 iOS 模塊路徑
project(':iosApp').projectDir = new File('ios/application')
```

4.3 配置插件和倉庫

?插件版本管理：在 KMM 中，需統一 Kotlin 插件版本以兼容多平臺構建?。示例：

pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
    // 指定 Kotlin 和 Android 插件版本
    plugins {
        id 'org.jetbrains.kotlin.multiplatform' version '1.9.20'
        id 'com.android.application' version '8.1.0'
    }
}

4.4 管理依賴解析策略

?統一依賴倉庫：聲明全局倉庫地址（如 Maven Central、Google 倉庫），確保所有模塊使用相同的依賴源?。示例?：
```
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
    }
}
```

4.5 KMM 項目中的特殊作用

?多平臺模塊協調?：確保共享模塊（shared）與平臺模塊（androidApp、iosApp）的依賴關系正確傳遞?。
?構建環境隔離?：通過插件管理避免不同平臺（如 Android 和 iOS）的構建沖突?。

總結：settings.gradle 在 KMM 項目中是多模塊和多平臺構建的基石?，通過聲明模塊、管理路徑和統一配置，確?？缙脚_代碼與原生模塊的高效整合?。其配置直接影響 Gradle 如何識別和組織項目結構，是跨平臺開發的關鍵文件之一。

5. gradlew

在新建 Kotlin Multiplatform Mobile (KMM) 項目時，生成的 ?.gradlew?（Unix/Linux/macOS）和 ?.gradlew.bat?（Windows）文件是 ?Gradle Wrapper 的啟動腳本?。它們的作用是統一項目的構建環境，確保開發者無需預先安裝特定版本的 Gradle，也能正確構建項目。以下是詳細解析：

5.1 Gradle Wrapper 的核心作用

?環境一致性?：無論開發者本地安裝的 Gradle 版本是什么，項目都通過 Wrapper 使用 ?gradle-wrapper.properties? 中指定的 Gradle 版本進行構建，避免版本沖突。
?零配置運行?：新克隆項目的開發者無需手動安裝 Gradle，直接運行 Wrapper 腳本即可自動下載并配置正確的 Gradle 版本。

5.2 文件的作用?

文件名	平臺	功能
`gradlew`	Unix/Linux/macOS	Shell 腳本，用于執行 Gradle 命令（如 `./gradlew build`）
`gradlew.bat`	Windows	批處理腳本，功能同上（如 `gradlew.bat build`）
`gradle/wrapper/` 目錄	所有平臺	包含 Wrapper 的核心文件（如 `gradle-wrapper.jar` 和 `gradle-wrapper.properties`）

5.3 核心文件解析?

1）?gradle-wrapper.properties?

位于 gradle/wrapper/gradle-wrapper.properties，定義了 Gradle 的下載地址和版本?：

# 指定使用的 Gradle 發行版類型（通常是 'bin' 或 'all'）
distributionType=bin
# 指定 Gradle 版本（必須與項目兼容）
distributionUrl=https\://services.gradle.org/distributions/gradle-8.4-bin.zip

?bin?：僅包含運行時（體積小，適合大多數場景）。
?all?：包含文檔和源碼（適用于需要調試 Gradle 的場景）。

2）?gradle-wrapper.jar?

位于 gradle/wrapper/gradle-wrapper.jar，是 Wrapper 的核心實現，負責 ?下載并安裝指定版本的 Gradle?。

5.4. 如何使用 Wrapper 腳本？

1）?Unix/Linux/macOS?

# 運行構建命令
./gradlew build

# 清理構建緩存
./gradlew clean

# 更新 Gradle 版本（修改 gradle-wrapper.properties 后）
./gradlew wrapper --gradle-version=8.5

2）Windows?

# 運行構建命令
gradlew.bat build

# 清理構建緩存
gradlew.bat clean

5.5 為何需要提交這些文件到版本控制？

?確保一致性?：所有開發者使用相同的 Gradle 版本和配置。
?簡化協作?：新成員無需手動安裝或配置 Gradle，直接運行 Wrapper 即可。

5.6 常見問題?

1）?Q1：gradlew 權限被拒絕？

?解決方法：賦予執行權限：
```
chmod +x gradlew
```

2）Q2：如何更新 Gradle 版本？

修改 gradle-wrapper.properties 中的 distributionUrl。
運行 Wrapper 任務以下載新版本：
```
./gradlew wrapper --gradle-version=8.5
```

3）Q3：gradlew 文件被誤刪怎么辦？

?恢復方法：重新生成 Wrapper；

》https://coderyuan.com/2021/05/28/KMM-2/

》https://cloud.tencent.com/developer/article/1909223

》https://news.qq.com/rain/a/20230324A04YF900

posted @ 2025-06-06 17:36 背包の技術閱讀(99) 評論(0) 收藏舉報

刷新頁面返回頂部

Kerwin

YOU CAN DO IT.

跨平臺之 KMP / KMM 詳解

一. KMP 和 Compose Multiplatform

1. 基礎概念

2. KMP 核心原理

2.1 特定于平臺的 API 和實現

2.2 直接訪問 iOS Framework 的核心原理

2.2.1 跨平臺代碼分層機制

2.2.2 CInterop 原生接口綁定

2.2.3 編譯期代碼轉換

2.2.4 整體交互流程和技術對比

2.3 cinterop 生成中間層時機

2.3.1 生成時機

2.3.2 生成路徑與產物

2.3.3 生成流程對比

2.3.4 技術實現原理

2.3.5 總結

二. KMM 環境搭建

1. KDoctor

2. Kotlin Multiplatform Plugin

三. 項目構建和解析

1. 新建 KMM 項目

2. 項目架構和配置

四. 配置文件詳解

1. build.gradle

1.1 build.gradle 的作用

1.?2 KMM 項目的典型結構

1.2.1 項目根目錄的 build.gradle

1.2.2 共享模塊的 build.gradle

1.2.3 Android App 模塊的 build.gradle

1.2.4 iOS 模塊的配置?

?1.3 關鍵配置解析?

1.?4 常見問題與解決

1.?5 總結?

2. gradle.properties

2.1 ?配置 Gradle 構建環境

2.2 ?定義項目全局變量

2.3 ?控制 KMM 多平臺構建行為

2.4 ?管理 Android 和 iOS 構建配置

2.?5. ?配置代理和倉庫鏡像

2.6 ?啟用實驗性功能

2.7 ?解決常見構建問題

2.8 文件位置與優先級?

2.9 KMM 項目典型配置示例

3. local.properties

3.1 核心作用?

1）配置本地開發環境路徑

2）存儲敏感信息?

3）隔離團隊協作差異

3.2 典型配置內容

3.3 ?在 KMM 項目中的使用方式

1）?讀取配置?

2）動態注入環境變量

3.4 ?最佳實踐?

3.5 與 gradle.properties 的區別

4. settings.gradle

4.1 聲明項目包含的模塊

4.2 定義模塊路徑

4.3 配置插件和倉庫

4.4 管理依賴解析策略

4.5 KMM 項目中的特殊作用

5. gradlew

5.1 Gradle Wrapper 的核心作用

5.2 文件的作用?

5.3 核心文件解析?

5.4. 如何使用 Wrapper 腳本？

5.5 為何需要提交這些文件到版本控制？

5.6 常見問題?

公告

1.1 `build.gradle` 的作用

1.2.1 項目根目錄的 `build.gradle`

1.2.2 共享模塊的 `build.gradle`

1.2.3 Android App 模塊的 `build.gradle`

3.5 與 `gradle.properties` 的區別

5.5 為何需要提交這些文件到版本控制？