Kotlin Multiplatform 快速入門

透過本教學，您可以讓一個簡單的 Kotlin Multiplatform 應用程式快速啟動並運行。

設定環境

Kotlin Multiplatform (KMP) 專案需要特定的環境，但大多數要求會透過 IDE 中的預檢（preflight checks）清楚說明。

從 IDE 和必要的插件開始：

1. 選擇並安裝 IDE。 IntelliJ IDEA 和 Android Studio 都支援 Kotlin Multiplatform，因此您可以使用您偏好的 IDE。

   JetBrains Toolbox App 是安裝 IDE 的推薦工具。 它允許您管理多個產品或版本，包括 搶先體驗計畫 (EAP) 和每夜發佈 (Nightly releases)。

   對於獨立安裝，請下載 IntelliJ IDEA 或 Android Studio 的安裝程式。

   Kotlin Multiplatform 所需的插件需要 IntelliJ IDEA 2025.1.1.1 或 Android Studio Narwhal 2025.1.1。

2. 安裝 Kotlin Multiplatform IDE 插件 (不要與 Kotlin Multiplatform Gradle 插件混淆)。

   適用於 Windows 或 Linux 上 IDE 的 Kotlin Multiplatform 插件尚未提供。 但在這些平台上它也不是嚴格必要的： 您仍然可以依照本教學生成並運行 KMP 專案。

3. 為 IntelliJ IDEA 安裝 Kotlin Multiplatform IDE 插件也會安裝所有必要的依賴項（如果您尚未安裝它們）（Android Studio 已綁定所有必要的插件）。

   如果您正在 Windows 或 Linux 上使用 IntelliJ IDEA，請確保手動安裝所有必要的插件：

   • Android
   • Android Design Tools
   • Jetpack Compose
   • Native Debugging Support
   • Compose Multiplatform for Desktop IDE Support (僅在您沒有 Kotlin Multiplatform 插件時才需要)。

4. 如果您尚未設定 ANDROID_HOME 環境變數，請配置您的系統以識別它：

   Bash 或 ZshWindows PowerShell 或 CMD

   將以下命令新增到您的 .profile 或 .zprofile 中：

   export ANDROID_HOME=~/Library/Android/sdk

   對於 PowerShell，您可以使用以下命令新增一個持久環境變數（詳情請參閱 PowerShell 文件）：

   [Environment]::SetEnvironmentVariable('ANDROID_HOME', '<path to the SDK>', 'Machine')

   對於 CMD，請使用 setx 命令：

   setx ANDROID_HOME "<path to the SDK>"

5. 若要建立 iOS 應用程式，您需要一台安裝了 Xcode 的 macOS 主機。 您的 IDE 將在底層運行 Xcode 以建構 iOS 框架。

   在開始使用 KMP 專案之前，請確保至少啟動一次 Xcode，以便它完成初始設定。

   每次 Xcode 更新時，您都需要手動啟動它並下載更新的工具。 Kotlin Multiplatform IDE 插件會執行預檢，當 Xcode 狀態不正確而無法工作時會提醒您。

建立專案

在 macOS 上

在 macOS 上，Kotlin Multiplatform 插件在 IDE 內部提供了一個專案生成精靈：

IntelliJ IDEAAndroid Studio

使用 IDE 精靈建立新的 KMP 專案：

1. 在主選單中選擇 檔案 | 新增 | 專案。
2. 在左側列表中選擇 Kotlin Multiplatform。
3. 根據需要設定專案的名稱、位置和其他基本屬性。
4. 我們建議選擇一個版本的 JetBrains Runtime (JBR) 作為您專案的 JDK，因為它提供了重要的修復，特別是為了提高桌面 KMP 應用程式的相容性。 每個 IntelliJ IDEA 發行版中都包含相關版本的 JBR，因此無需額外設定。
5. 選擇您希望作為專案一部分的平台：
   • 所有目標平台都可以設定為從一開始就使用 Compose Multiplatform 共用 UI 代碼（不包含 UI 代碼的伺服器模組除外）。
   • 對於 iOS，您可以選擇兩種實作方式之一：
     • 共用 UI 代碼，使用 Compose Multiplatform，
     • 完全原生的 UI，使用 SwiftUI 製作並與具有共用邏輯的 Kotlin 模組連接。
   • 桌面目標包含 Compose Hot Reload 功能的 Alpha 版本，它允許您在更改相應代碼後立即看到 UI 變更。 即使您不打算製作桌面應用程式，您可能也會想使用桌面版本來加速編寫 UI 代碼。

選擇完平台後，點擊 建立 (Create) 按鈕，等待 IDE 生成並匯入專案。

Kotlin Multiplatform IDE 插件嚴重依賴 K2 功能，沒有它將無法如描述般運作。 因此，在開始之前，請確保 K2 模式已啟用： 設定 | 語言與框架 | Kotlin | 啟用 K2 模式。

使用 IDE 精靈建立新的 KMP 專案：

1. 在主選單中選擇 檔案 | 新增 | 新增專案。

2. 在預設的 手機和平板 範本類別中選擇 Kotlin Multiplatform。

   

3. 根據需要設定專案的名稱、位置和其他基本屬性，然後點擊 下一步 (Next)。

4. 選擇您希望作為專案一部分的平台：

   • 所有目標平台都可以設定為從一開始就使用 Compose Multiplatform 共用 UI 代碼（不包含 UI 代碼的伺服器模組除外）。
   • 對於 iOS，您可以選擇兩種實作方式之一：
     • 共用 UI 代碼，使用 Compose Multiplatform，
     • 完全原生的 UI，使用 SwiftUI 製作並與具有共用邏輯的 Kotlin 模組連接。
   • 桌面目標包含熱重載（hot reload）功能的 alpha 版本，它允許您在更改相應代碼後立即看到 UI 變更。 即使您不打算製作桌面應用程式，您可能也會想使用桌面版本來加速編寫 UI 代碼。

5. 當專案生成後，我們建議選擇一個版本的 JetBrains Runtime (JBR) 作為您專案的 JDK，因為它提供了重要的修復，特別是為了提高桌面 KMP 應用程式的相容性。 每個 IntelliJ IDEA 發行版中都包含相關版本的 JBR，因此無需額外設定。

選擇完平台後，點擊 完成 (Finish) 按鈕，等待 IDE 生成並匯入專案。

在 Windows 或 Linux 上

如果您正在使用 Windows 或 Linux：

1. 使用 web KMP 精靈 生成一個專案。
2. 解壓縮歸檔檔並在您的 IDE 中打開生成的資料夾。
3. 等待匯入完成，然後前往 未定義 部分了解如何建構和運行應用程式。

諮詢預檢

您可以透過打開 專案環境預檢 (Project Environment Preflight Checks) 工具視窗來確保專案設定沒有環境問題：點擊右側邊欄或底部工具欄上的預檢圖示

在此工具視窗中，您可以查看與這些檢查相關的訊息、重新運行它們或更改其設定。

預檢命令也可在 隨處搜尋 (Search Everywhere) 對話框中找到。 按下雙擊 並搜尋包含「preflight」一詞的命令：

運行範例應用程式

IDE 精靈建立的專案包括為 iOS、Android、桌面和 Web 應用程式生成的運行配置，以及運行伺服器應用程式的 Gradle 任務。 在 Windows 和 Linux 上，請參閱下方每個平台的 Gradle 命令。

AndroidiOS桌面Web

若要運行 Android 應用程式，請啟動 composeApp 運行配置：

要在 Windows 或 Linux 上運行 Android 應用程式，請建立一個 Android 應用程式 (Android App) 運行配置，並選擇模組 [專案名稱].composeApp。

預設情況下，它會在第一個可用的虛擬裝置上運行：

您需要 macOS 主機才能建構 iOS 應用程式。

如果您為專案選擇了 iOS 目標並設定了安裝 Xcode 的 macOS 機器， 您可以選擇 iosApp 運行配置並選擇一個模擬裝置：

當您運行 iOS 應用程式時，它會在底層使用 Xcode 建構，並在 iOS 模擬器中啟動。 首次建構會收集編譯所需的原生依賴項，並為後續運行預熱建構：

桌面應用程式的預設運行配置建立為 composeApp [desktop]：

要在 Windows 或 Linux 上運行桌面應用程式，請建立一個 Gradle 運行配置，指向 [應用程式名稱]:composeApp Gradle 專案，並使用以下命令：

desktopRun -DmainClass=com.example.myapplication.MainKt --quiet

透過此配置，您可以運行 JVM 桌面應用程式：

Web 應用程式的預設運行配置建立為 composeApp [wasmJs]：

要在 Windows 或 Linux 上運行 Web 應用程式，請建立一個 Gradle 運行配置，指向 [應用程式名稱]:composeApp Gradle 專案，並使用以下命令：

wasmJsBrowserDevelopmentRun

當您運行此配置時，IDE 會建構 Kotlin/Wasm 應用程式並在預設瀏覽器中打開它：

疑難排解

Java 和 JDK

Java 的常見問題：

• 某些工具可能找不到要運行的 Java 版本或使用了錯誤的版本。 為了解決這個問題：

  • 將 JAVA_HOME 環境變數設定為安裝了適當 JDK 的目錄。

    我們建議使用 JetBrains Runtime， 這是一個支援類別重新定義的 OpenJDK 分支。

  • 將 JAVA_HOME 內的 bin 資料夾路徑附加到 PATH 變數中， 以便 JDK 中包含的工具可在終端機中使用。

• 如果您在 Android Studio 中遇到 Gradle JDK 的問題，請確保其配置正確： 選擇 設定 | 建構、執行、部署 | 建構工具 | Gradle。

Android 工具

與 JDK 相同，如果您在啟動 adb 等 Android 工具時遇到問題， 請確保將 ANDROID_HOME/tools、ANDROID_HOME/tools/bin 和 ANDROID_HOME/platform-tools 的路徑新增到您的 PATH 環境變數中。

Xcode

如果您的 iOS 運行配置報告沒有可運行的虛擬裝置，請確保啟動 Xcode 並查看 iOS 模擬器是否有任何更新。

獲取協助

• Kotlin Slack。獲取 邀請 並加入 #multiplatform 頻道。
• Kotlin Multiplatform 工具問題追蹤器。回報新問題。

接下來

了解更多關於 KMP 專案結構和編寫共用代碼的資訊：

• 一系列關於使用共用 UI 代碼的教學：建立您的 Compose Multiplatform 應用程式
• 一系列關於將共用代碼與原生 UI 結合使用的教學：建立您的 Kotlin Multiplatform 應用程式
• 深入了解 Kotlin Multiplatform 文件：
  • 專案配置
  • 使用多平台依賴項
• 了解 Compose Multiplatform UI 框架、其基礎知識和平台特定功能： Compose Multiplatform 和 Jetpack Compose。

探索已為 KMP 編寫的代碼：

• 我們的 範例 頁面，包含 JetBrains 官方範例以及展示 KMP 功能的精選專案列表。
• GitHub 主題：
  • kotlin-multiplatform，使用 Kotlin Multiplatform 實作的專案。
  • kotlin-multiplatform-sample， 使用 KMP 編寫的範例專案列表。
• klibs.io – KMP 函式庫搜尋平台，迄今已索引超過 2000 個函式庫， 包括 OkHttp、Ktor、Coil、Koin、SQLDelight 等。