Kotlin Multiplatform 入門：構建你的第一個跨平台應用详情 - 多平台,kotlin,jetbrains,跨平台 GeekCat 日志

這是關於 Kotlin Multiplatform 開發博客系列的第二篇文章，我計劃每週更新一篇文章，文章主題可能會以基礎與進階內容交替進行。

引言

本文面向對 Kotlin Multiplatform (KMP) 感興趣的開發者，特別是那些希望探索如何使用單一代碼庫開發跨平台應用的程序員。無論您是移動開發者、前端工程師還是全棧開發者，只要您對提高開發效率和跨平台開發感興趣，瞭解一下並體驗一下 KMP 我想都是值得的。

在本教程中，相對新手向。我們將詳細介紹以下內容:

環境準備
項目初始化
gradle 命令
啓動桌面應用
配置和啓動 Android 應用
配置和啓動 iOS 應用
啓動 Web 應用
設置和啓動服務器應用

環境準備

在開始我們的 KMP 之旅之前，我們需要先搭建好開發環境。

首先我們需要安裝 Android Studio / Xcode / cocoapods。有了這些基礎環境我們便可以體驗 kmp 所有平台的開發。

對於 Windows、Linux 用户，由於系統限制可以跳過 Xcode / cocoapods 的安裝，也因此只能體驗桌面、Android 和 Web 平台的開發。

Android Studio: 這是我們的主要集成開發環境(IDE)。Android Studio 不僅支持 Android 開發，還完美集成了 Kotlin 和 KMP 的支持。
- 下載地址: Android Studio
Xcode (僅限 Mac 用户): 用於 iOS 應用開發和測試。即使你主要使用 Android Studio，Xcode 也是 iOS 開發不可或缺的工具。
- 下載地址: Xcode
CocoaPods (僅限Mac用户): iOS 開發中常用的依賴管理工具。
- 安裝命令: brew install cocoapods

注意: Windows 和 Linux 用户可以跳過 Xcode 和 CocoaPods 的安裝。雖然這意味着你暫時無法開發 iOS 應用，但你仍然可以充分體驗 KMP 在桌面、Android 和 Web 平台的強大功能。

對於 Mac 用户來説，也可以安裝 kdoctor 工具，來進行環境檢查

brew install kdoctor
kdoctor

Environment diagnose (to see all details, use -v option):
[✓] Operation System
[✓] Java
[!] Android Studio
  ! Android Studio (AI-242.23339.11.2421.12483815)
    Bundled Java: openjdk 21.0.3 2024-04-16
    Kotlin Plugin: 242.23339.11.2421.12483815-AS
    Kotlin Multiplatform Mobile Plugin: not installed
    Install Kotlin Multiplatform Mobile plugin - https://plugins.jetbrains.com/plugin/14936-kotlin-multiplatform-mobile
  ! Android Studio (AI-242.21829.142.2421.12366423)
    Bundled Java: openjdk 21.0.3 2024-04-16
    Kotlin Plugin: 242.21829.142.2421.12366423-AS
    Kotlin Multiplatform Mobile Plugin: not installed
    Install Kotlin Multiplatform Mobile plugin - https://plugins.jetbrains.com/plugin/14936-kotlin-multiplatform-mobile
[✓] Xcode
[✓] CocoaPods

Conclusion:
  ✓ Your operation system is ready for Kotlin Multiplatform Mobile Development!

kdoctor 會詳細列出你的環境狀況，包括操作系統、Java版本、Android Studio配置、Xcode和CocoaPods 等。如果有任何問題，它會給出明確的提示和修復建議。

使用 JetBrains KMP 腳手架初始化項目

JetBrains 提供了一個非常方便的在線工具 - Kotlin Multiplatform Wizard，它可以幫助我們快速生成一個包含所有必要配置的 KMP 項目模板。

讓我們一步步來:

打開 Kotlin Multiplatform wizard
在 wizard 界面上，你會看到多個選項，允許你選擇要支持的平台。為了充分展示 KMP 的強大功能，我們這裏選擇所有可用的平台。你可以根據自己的項目需求進行選擇。
配置完成後，點擊下載按鈕。這將生成一個包含所有必要文件和配置的 zip 文件。
下載完成後，解壓這個 zip 文件到你的工作目錄。
使用 Android Studio 打開這個項目目錄。
當你首次打開項目時，Gradle 會開始同步和下載必要的依賴。這個過程可能需要一些時間，取決於你的網速。
如果遇到網絡問題導致同步失敗，可以考慮添加國內的 Maven 鏡像或者配置 Gradle 代理。

現在，讓我們來看一下項目的結構，特別是 composeApp 模塊，這是我們多平台應用的核心:

composeApp
├── build.gradle.kts
└── src
    ├── androidMain
    ├── commonMain
    ├── desktopMain
    ├── iosMain
    └── wasmJsMain

你會注意到，src 目錄下有多個子目錄，每個都對應一個特定的平台:

commonMain: 這裏存放所有平台共享的代碼。這是KMP的精髓所在，你可以在這裏編寫一次代碼，然後在所有平台上運行。
androidMain: Android 特定的代碼。
desktopMain: 桌面應用 (如 Windows， macOS， Linux) 特定的代碼。
iosMain: iOS 特定的代碼。
wasmJsMain: Web 應用特定的代碼。

除了 composeApp 模塊，你還會看到一個 shared 模塊，它的結構與 composeApp 類似。shared 模塊通常用於存放可以在多個模塊間共享的代碼，而 composeApp 依賴於shared。這種結構允許你進一步模塊化你的應用，提高代碼的可維護性和複用性。

在 composeApp 的 build.gradle.kts 文件中，你會看到類似這樣的依賴聲明:

commonMain.dependencies {
    implementation(projects.shared)
}

這行代碼表示 composeApp 模塊依賴於 shared 模塊。這種設置允許你在 shared 模塊中定義共享的數據模型、業務邏輯或工具類，然後在 composeApp 中使用它們。

理解這個項目結構對於充分利用KMP的優勢至關重要。它允許你最大化代碼複用，同時仍然為每個平台提供定製化的實現。

項目 gradle 命令

Gradle 是 KMP 項目的構建工具，它提供了許多有用的命令來幫助我們構建、測試、運行和發佈多平台應用。
首先，讓我們看一下項目根目錄下的 build.gradle.kts 文件:

plugins {
    // this is necessary to avoid the plugins to be loaded multiple times
    // in each subproject's classloader
    alias(libs.plugins.androidApplication) apply false
    alias(libs.plugins.androidLibrary) apply false
    alias(libs.plugins.jetbrainsCompose) apply false
    alias(libs.plugins.compose.compiler) apply false
    alias(libs.plugins.kotlinJvm) apply false
    alias(libs.plugins.kotlinMultiplatform) apply false
}

這些插件為我們的 KMP 項目提供了必要的功能支持，如Android應用開發、Jetpack Compose UI框架、Kotlin 多平台支持等等。

我們可以通過 gradle tasks 查看這些插件提供的所有命令

輸出如下

Android tasks
-------------
androidDependencies - Displays the Android dependencies of the project.
signingReport - Displays the signing info for the base and test modules
sourceSets - Prints out all the source sets defined in this project.

Application tasks
-----------------
run - Runs this project as a JVM application
runShadow - Runs this project as a JVM application using the shadow jar
startShadowScripts - Creates OS specific scripts to run the project as a JVM application using the shadow jar

... 輸出過長忽略

這些任務涵蓋了從構建到測試，再到運行和部署的各個方面，當我們需要某些功能時，便可以基於此按需查找。

雖然我們可以在命令行中運行這些 Gradle 任務，但我個人更推薦使用 IDE 來執行這些任務。使用IDE有以下優勢

更好的項目隔離: IDE可以為每個項目維護獨立的配置，避免全局設置可能帶來的衝突。
更直觀的界面: IDE提供圖形化界面，使任務執行更加直觀和方便。
更好的調試支持: 當遇到問題時，IDE提供更詳細的日誌和調試工具。

啓動桌面應用

讓我們來啓動我們的第一個平台應用 - 桌面應用。這將展示 KMP 如何無縫地將我們的代碼轉換為可在 Windows、macOS 和 Linux 上運行的應用程序。

你可能會嘗試直接通過 IDE 運行主函數來啓動應用，實際上這並不能成功執行。這是因為 KMP 應用需要在運行前進行大量的預處理工作，而 IDE 本身並沒有預置這些功能。

正確的做法還是需要使用上文提到的 gradle 命令。我們可以輕鬆的查找到相關命令 run - Runs this project as a JVM application

gradle run

執行這個命令後，Gradle 會編譯我們的代碼，處理所有必要的依賴，然後啓動應用。幾秒鐘後，你應該能看到一個窗口彈出，顯示我們的應用界面:

恭喜！你剛剛成功運行了你的第一個 KMP 桌面應用！

雖然命令行運行很方便，但如果我們能直接在 IDE 中點擊運行按鈕豈不是更好？讓我們來保存剛剛執行的運行配置，以便後續可以選擇任務點擊直接執行。

有了這個配置，你就可以像運行普通 Kotlin / Java 應用一樣輕鬆地運行和調試你的 KMP 桌面應用了。

配置和啓動 Android 應用

接下來，讓我們將注意力轉向移動平台，從 Android 開始。KMP 允許我們重用大部分代碼，同時為 Android 平台提供特定的實現。

在運行 Android 應用之前，我們需要確保已經安裝了正確的Android SDK 和工具。

在 Android Studio 中，轉到 Settings/Preferences -> Languages & Frameworks -> Android SDK
在這裏，你可以看到已安裝的SDK版本和工具。確保你至少安裝了一個較新的 Android SDK 版本。
如果需要，SDK Tools 標籤頁安裝額外的工具，如 Android Emulator 和 SDK Platform-Tools。

KMP 項目初始化後，Android Studio 會自動為 composeApp 模塊創建 Android 運行配置。你可以在IDE頂部的運行配置下拉菜單中找到它：

你可以使用真機或者虛擬機啓動 Android 應用。

如果選擇虛擬機，你可以在 Device Manager 中創建一個
如果使用真機，你需要在 Android 設備上啓用開發者選項和 USB 調試。
- 轉到設置 -> 關於手機，連續點擊 "版本號" 7 次以啓用開發者選項。
- 返回到設置主頁，你應該能看到 "開發者選項"
- 在開發者選項中啓用 "USB調試"

更多細節你可以查看官方文檔

運行效果

配置和啓動 iOS 應用

注意：iOS 開發需要 Mac 電腦。如果你使用的是 Windows 或Linux，可以跳過這一部分。

現在讓我們轉向 Apple 的生態系統，看看如何在 iOS 設備上運行我們的 KMP 應用。

打開 iosApp 啓動配置
在 Execution target 下拉菜單中，你可以選擇要運行的iOS 設備或模擬器。如果你連接了真實的 iOS 設備，它也會出現在這個列表中。
使用真機啓動應用，同樣需要開啓開發者模式。這裏以 iPhone 為例，設置 -> 隱式與安全性 -> 開發者模式，可以找到對應開關（系統版本不同可能設置路徑略有不同）。

配置開發者賬號

首次在真機上運行 iOS 應用時，你可能會遇到以下錯誤：

error: Signing for "iosApp" requires a development team. Select a development team in the Signing & Capabilities editor. (in target 'iosApp' from project 'iosApp')
warning: Run script build phase 'Compile Kotlin Framework' will be run during every build because it does not specify any outputs. To address this issue, either add output dependencies to the script phase, or configure it to run in every build by unchecking "Based on dependency analysis" in the script phase. (in target 'iosApp' from project 'iosApp')
** BUILD FAILED **

這是因為 iOS 應用需要有開發者簽名。讓我們來配置它：

打開 Xcode
選擇 Open Existing Project，然後導航到你的 KMP 項目目錄
在 iosApp 文件夾中找到並打開 iosApp.xcodeproj 文件
在 Xcode 中，選擇左側的項目導航器中的 iosApp
在主編輯區域，選擇 Signing & Capabilities 標籤
在 Team 下拉菜單中，選擇你的開發者賬號。如果你還沒有Apple 開發者賬號，需要先在 developer.apple.com 註冊一個

設置完成團隊 ID 後，我們可以重新啓動應用。

你現在已經成功地將同一個 KMP 應用部署到了 Desktop / Android / iOS 平台。

啓動 Web 應用

KMP 的魅力不僅限於移動和桌面平台，它還能幫助我們構建 Web 應用。Web 應用的優勢在於可以用更低的代價觸達用户，讓用户體驗應用的初步功能，吸引用户下載客户端。

在這一部分，我們將看到如何將我們的應用部署為一個 Web 應用。

運行 Web 應用的過程與桌面應用類似，我們將使用 Gradle 命令：

gradle wasmJsBrowserRun

這個命令會做幾件事：

編譯你的 Kotlin 代碼為 WebAssembly (Wasm)
設置一個本地開發服務器
在默認瀏覽器中打開你的應用

第一次執行命令，你可能會查看到執行卡在：
> Task :kotlinNpmInstall

這個任務可能需要一些時間，因為它在下載必要的依賴。耐心等待，完成後你應該能在瀏覽器中看到你的應用：

Web應用的優勢

將你的 KMP 應用部署為 Web 應用有幾個顯著的優勢：

廣泛的可訪問性：用户無需安裝任何東西就能使用你的應用。
即時更新：你可以隨時更新應用，用户總是使用最新版本。
跨平台兼容性：Web應用可以在任何有現代瀏覽器的設備上運行。

通過 KMP，你可以在保持核心業務邏輯一致的同時，為 Web 平台提供定製的 UI 和功能。這大大提高了開發效率，同時確保了各平台間的一致性。

運行服務器應用

最後，讓我們來看看如何運行 KMP 項目中的服務器應用。服務器端的 Kotlin 應用通常使用 Ktor 框架，這是一個強大而靈活的Kotlin Web 框架。

在KMP項目中，server 模塊通常是一個標準的 Kotlin JVM 應用。它的主要優勢在於可以與客户端應用共享代碼，特別是數據模型和業務邏輯。

打開 server 模塊的 build.gradle.kts 文件，你可能會看到類似這樣的依賴：

dependencies {
    implementation(projects.shared)
    implementation(libs.ktor.server.core)
    implementation(libs.ktor.server.netty)
    // ... 其他依賴
}

注意 implementation(projects.shared) 這一行，它表示服務器模塊依賴於 shared 模塊，這就是我們實現代碼共享的方式。

在 KMP 項目中包含服務器模塊有幾個主要優勢：

代碼共享：服務器和客户端可以共享數據模型、驗證邏輯等。
類型安全：由於使用相同的語言和模型，可以在編譯時捕獲許多潛在錯誤。
開發效率：開發者不需要重複定義，避免不一致的問題，方便全棧開發。

結語

在這篇教程中，我們從環境搭建開始，一步步完成了 KMP 項目的創建和多平台運行。通過實踐我們看到，KMP 不僅能夠顯著提升開發效率，更重要的是它讓跨平台開發變得優雅而自然。
如果你想看到 KMP 在實際項目中的應用，可以參考我的開源項目 CrossPaste。這是一個基於Compose Multiplatform 開發的統一桌面剪貼板工具，支持Windows、macOS 和 Linux 平台。不止可以作為單機的粘貼板管理工具，更重要的是它支持跨設備的複製粘貼，在任意設備間複製粘貼，就像在同一台設備上操作一樣自然流暢。

GeekCat 日志

@guiyanakuang

标签

macos (59)

Kotlin (32)

jetbrains (12)

跨平台 (7)

文件 (3)

多平台 (1)

tray (1)

serializable (1)

桌面應用 (1)

动态

Kotlin Multiplatform 入門：構建你的第一個跨平台應用 - 动态详情

引言

環境準備

使用 JetBrains KMP 腳手架初始化項目

項目 gradle 命令

啓動桌面應用

配置和啓動 Android 應用

配置和啓動 iOS 應用

配置開發者賬號

啓動 Web 應用

Web應用的優勢

運行服務器應用

結語

Add a new 评论

GeekCat 日志

@guiyanakuang

标签

macos (59)

Kotlin (32)

jetbrains (12)

跨平台 (7)

文件 (3)

多平台 (1)

tray (1)

serializable (1)

桌面應用 (1)

动态

Kotlin Multiplatform 入門：構建你的第一個跨平台應用 - 动态 详情

引言

環境準備

使用 JetBrains KMP 腳手架初始化項目

項目 gradle 命令

啓動桌面應用

配置和啓動 Android 應用

配置和啓動 iOS 應用

配置開發者賬號

啓動 Web 應用

Web應用的優勢

運行服務器應用

結語

Add a new 评论

Kotlin Multiplatform 入門：構建你的第一個跨平台應用 - 动态详情