Kotlin Multiplatform 開発環境セットアップと CI/CD 完全ガイド

2026年4月28日

お得なお知らせ

スポンサードリンク

AI時代のキャリア構築

プログラミング学習、今日から動き出す

「何から始めるか」で止まっている人こそ、無料説明会や本で自分に合うルートを30分で確定できます。

Enjoy Tech!｜月額制でWeb系に強い▶ (Kindle本)ＩＴエンジニアの転職学｜後悔しないキャリア戦略▶

▶ AIコーディング環境なら実践Claude Code入門（Amazon）が実務で即使える入門書です。Amazonベストセラーにも選ばれていますよ。

Contents

1 開発環境のセットアップ
- 1.1 JDK 17+ と Android Studio Giraffe/2024.1.2 のインストール
  - 1.1.1 手順
- 1.2 Kotlin プラグイン 2.0 以降の適用方法
  - 1.2.1 手順
2 KMP プロジェクトの新規作成
- 2.1 Kotlin Multiplatform プラグインの有効化（ウィザード使用）
  - 2.1.1 手順
- 2.2 対象プラットフォームの推奨構成
3 Gradle Kotlin DSL と依存関係管理
4 iOS ビルドと Xcode 連携
5 既存プロジェクトへの KMP 追加と CI/CD
6 まとめ（簡潔版）

スポンサードリンク

開発環境のセットアップ

JDK 17+ と Android Studio Giraffe/2024.1.2 のインストール

ポイント：Kotlin Multiplatform（以下 KMP）を快適に動かすには、JDK 17 以上と Android Studio Giraffe（バージョン 2024.1.2）を組み合わせるのが公式推奨です。

項目	推奨理由
JDK 17	Kotlin 2.0 系コンパイラは Java 17 のモジュールシステムに最適化され、Gradle 8.x と完全互換です。
Android Studio Giraffe	IDE に組み込まれた Gradle 8.x プラグインが最新で、KMP 用テンプレートやコード補完が標準装備されています。

手順

JDK の入手
AdoptOpenJDK、Azul Zulu、または Oracle JDK から「JDK 17 LTS」をダウンロードし、インストーラの指示に従ってインストール。
JAVA_HOME を環境変数に設定（例：export JAVA_HOME=$(/usr/libexec/java_home -v 17)）。
Android Studio の取得
公式サイト https://developer.android.com/studio から Giraffe / 2024.1.2 をダウンロード。
インストールウィザードの「Standard」オプションで完了させ、起動後に Help → Check for Updates で最新パッチが適用されていることを確認。

まとめ：JDK 17 と Android Studio Giraffe をインストールすれば、KMP 開発に必要な公式ツールチェーンはすぐに利用可能です。

Kotlin プラグイン 2.0 以降の適用方法

ポイント：Kotlin プラグインが 2.0 未満だと、最新のコンパイラ API・IR バックエンドが使えず、commonMain のコードが期待通りにビルドできません。

手順

IDE → Settings → Plugins を開く（macOS は Preferences）。
Marketplace で「Kotlin」を検索し、バージョンが 2.0.0 以上か確認。
必要に応じて Update をクリックし、IDE 再起動後に反映されます。

まとめ：プラグインを 2.0 以降に保つだけで、Gradle Kotlin DSL と連携した最新 KMP 機能がすべて利用できます。

KMP プロジェクトの新規作成

Kotlin Multiplatform プラグインの有効化（ウィザード使用）

ポイント：Android Studio の KMP ウィザード が自動で plugins { kotlin("multiplatform") } と Gradle ラッパーを生成してくれます。

手順

手順	操作
1	New Project → Kotlin Multiplatform App を選択
2	「Multiplatform Settings」画面で「Use Kotlin Multiplatform plugin」にチェック（デフォルトオン）
3	必要なプラットフォームを次の表に従って選択

対象プラットフォームの推奨構成

2026 年時点で最も汎用的なのは android, iosSimulatorArm64, jvm, js (IR) の 4 ターゲットです。

ターゲット	主な利用シーン
`android`	実機・エミュレータ向け Android アプリ
`iosSimulatorArm64`	Apple Silicon シミュレータ（高速）
`jvm`	デスクトップ、サーバー側ロジックのテスト
`js(IR)`	ブラウザ + Node.js 用フロントエンド

まとめ：ウィザードで上記 4 ターゲットを一括選択すれば、プロジェクト構造が自動生成され、すぐにビルドできます。

Gradle Kotlin DSL と依存関係管理

基本的な `build.gradle.kts` 設定例

plugins {
    kotlin(&quot;multiplatform&quot;) version &quot;2.0.20&quot;
    id(&quot;com.android.application&quot;) version &quot;8.5.0&quot;
}

kotlin {
    android()
    iosSimulatorArm64()
    jvm()
    js(IR) {
        browser()
        nodejs()
    }

    sourceSets {
        val commonMain by getting {
            dependencies {
                implementation(libs.kotlinx.coroutines.core)
            }
        }
        // 各プラットフォーム固有の依存関係は以下に追加
        val androidMain      by getting
        val iosSimulatorArm64Main by getting
        val jvmMain          by getting
        val jsMain           by getting
    }
}

plugins {

kotlin("multiplatform") version "2.0.20"

id("com.android.application") version "8.5.0"

}

kotlin {

android()

iosSimulatorArm64()

jvm()

js(IR) {

browser()

nodejs()

}

sourceSets {

val commonMain by getting {

dependencies {

implementation(libs.kotlinx.coroutines.core)

}

// 各プラットフォーム固有の依存関係は以下に追加

val androidMain by getting

val iosSimulatorArm64Main by getting

val jvmMain by getting

val jsMain by getting

}

plugins ブロックで Kotlin Multiplatform と Android のプラグインを同時に宣言。
kotlin {} 内に対象ターゲットだけ列挙すれば、Gradle が自動的にビルド構成を作ります。

まとめ：上記テンプレートをコピーし、sourceSets の依存関係だけを書き換えるだけでプロジェクト固有の設定が完了します。

`sourceSets` とコード配置のベストプラクティス

ソースセット	用途例
`commonMain`	ビジネスロジック、データモデル、汎用ユーティリティ
`androidMain`	Android SDK 依存 (`Context`, `Activity`)
`iosSimulatorArm64Main`	iOS ネイティブ API（例：`NSURLSession`）
`jvmMain`	デスクトップ/サーバー向けロジック
`jsMain`	ブラウザまたは Node.js 用コード

まとめ：commonMain に置いたコードはすべてのプラットフォームで共有され、足りない実装があるとコンパイルエラーになるため、自然に欠落部分を検出できます。

バージョンカタログ (`libs.versions.toml`) の活用

`gradle/libs.versions.toml`

[versions]
kotlin = &quot;2.0.20&quot;
coroutines = &quot;1.8.0&quot;
androidGradlePlugin = &quot;8.5.0&quot;

[libraries]
kotlinx-coroutines-core = { module = &quot;org.jetbrains.kotlinx:kotlinx-coroutines-core&quot;, version.ref = &quot;coroutines&quot; }

[versions]

kotlin = "2.0.20"

coroutines = "1.8.0"

androidGradlePlugin = "8.5.0"

[libraries]

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

`build.gradle.kts` 側の記述

dependencies {
    implementation(libs.kotlinx.coroutines.core)
}

dependencies {

implementation(libs.kotlinx.coroutines.core)

}

利点
バージョン管理が一元化され、CI の再現性が向上。
ライブラリ追加・バージョン更新は libs.versions.toml のみで完結。

まとめ：Version Catalog を導入すれば、プロジェクト全体の依存関係を一括管理でき、アップデート作業が格段に楽になります。

iOS ビルドと Xcode 連携

CocoaPods と Swift Package Manager の比較（2026 年版）

項目	CocoaPods	Swift Package Manager
設定手順	`pod init` → Podfile に `use_frameworks!` 必要	Xcode 15 の Add Packages から直接 KMP 出力を追加
ビルド速度	初回インストールがやや遅い	統合ビルドなので高速
メンテナンス性	Podfile が肥大化しやすい	Xcode に統合され、依存関係が一元管理
2026 年の推奨度	安定しているが新規は非推奨	Apple Silicon と Xcode 15+ に最適化

結論：新規プロジェクトでは Swift Package Manager (SPM) が推奨されます。既存で CocoaPods を利用中の場合でも、podspec を作成すれば併用可能です。

Xcode 15+ 用プロジェクト設定（フレームワークの埋め込み）

手順

Gradle で iOS フレームワークをビルド
bash ./gradlew :shared:assembleDebugIosSimulatorArm64
→ ビルド成果物は ./build/bin/iosSimulatorArm64/debugFramework に生成されます。
Xcode へフレームワークを追加
Xcode プロジェクトを開き、File → Add Files to ""... を選択。
上記パスの *.framework を選び、Copy items if needed はオフにして Add。
埋め込み設定
ターゲットの General → Frameworks, Libraries, and Embedded Content で追加したフレームワークを Embed & Sign に変更。

注意：macOS 以外（例：Linux の CI ランナー）で iOS ビルドを行う場合は、./gradlew 実行時に -PiosSdkPath=/path/to/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs のように SDK パスを明示的に渡すか、環境変数 DEVELOPER_DIR を設定してください。

macOS 以外でのビルド例（GitHub Actions 用）

- name: Set Xcode path (non‑mac runner)
  run: |
    export DEVELOPER_DIR=/opt/Xcode.app/Contents/Developer   # Xcode がインストールされたディレクトリ
    ./gradlew :shared:assembleDebugIosSimulatorArm64 -PiosSdkPath=$DEVELOPER_DIR/Platforms/iPhoneSimulator.platform/Developer/SDKs

- name: Set Xcode path (non‑mac runner)

run: |

export DEVELOPER_DIR=/opt/Xcode.app/Contents/Developer # Xcode がインストールされたディレクトリ

./gradlew :shared:assembleDebugIosSimulatorArm64 -PiosSdkPath=$DEVELOPER_DIR/Platforms/iPhoneSimulator.platform/Developer/SDKs

まとめ：Gradle で生成したフレームワークを Xcode に Embed & Sign だけ設定すれば、iOS アプリから Kotlin のロジックを呼び出せます。macOS 以外の環境でも SDK パスを明示すれば同様にビルド可能です。

シミュレータ・実機でのテスト手順

共通テストを書いて Gradle から XCTest を生成

kotlin // commonTest/src/commonTest/kotlin/com/example/CalculatorTest.kt class CalculatorTest { @Test fun addition() = assertEquals(4, Calculator.add(2, 2)) }

テストをビルド
bash ./gradlew :shared:iosSimulatorArm64Test
→ build/bin/iosSimulatorArm64/debugTest に XCTest が生成されます。
Xcode で実行
Xcode の Product → Test (⌘U) を選択すると、シミュレータ上でテストが走り結果がコンソールに表示されます。

まとめ：Gradle と Xcode の連携だけで、KMP 共通テストを iOS 環境でもそのまま実行できます。

既存プロジェクトへの KMP 追加と CI/CD

既存 Android アプリへ `shared` モジュールを統合する手順

手順	内容
1	File → New → Module… → Kotlin Multiplatform Library を選び、モジュール名を `shared` として作成。
2	生成された `build.gradle.kts` が前述のテンプレートと合っているか確認（ターゲットやバージョンカタログが正しいこと）。
3	アプリ側 `app/build.gradle.kts` に `implementation(project(":shared"))` を追加。
4	Sync Project with Gradle Files → ビルドエラーが出なければ完了。

まとめ：モジュール追加 → 依存関係宣言 → Sync の 3 手順で、既存 Android アプリに KMP がシームレスに組み込めます。

GitHub Actions + Gradle によるマルチプラットフォーム自動ビルド例

name: KMP CI

on:
  push:
    branches: [ main ]
  pull_request:

jobs:
  build:
    runs-on: macos-14   # Apple Silicon ランナー（Xcode 15 がプリインストール済み）

    env:
      JAVA_HOME: /Applications/Android\ Studio.app/Contents/jbr/Contents/Home
      # 非 macOS 環境で iOS ビルドが必要な場合は下記のように DEVELOPER_DIR を設定
      # DEVELOPER_DIR: ${{ secrets.XCODE_PATH }}

    steps:
      - uses: actions/checkout@v4

      - name: Set up JDK 17
        uses: actions/setup-java@v3
        with:
          distribution: temurin
          java-version: 17

      - name: Install Android SDK
        uses: android-actions/setup-android@v2

      - name: Gradle cache
        uses: gradle/gradle-build-action@v2

      - name: Build all targets
        run: |
          ./gradlew clean \
            :shared:assembleDebugIosSimulatorArm64 \
            :shared:jsBrowserProductionWebpack \
            :app:bundleRelease

      - name: Upload iOS framework
        uses: actions/upload-artifact@v4
        with:
          name: ios-framework
          path: shared/build/bin/iosSimulatorArm64/debugFramework/*.framework

      - name: Upload Android AAR
        uses: actions/upload-artifact@v4
        with:
          name: android-aar
          path: shared/build/outputs/aar/*.aar

on:

push:

branches: [ main ]

pull_request:

jobs:

build:

runs-on: macos-14 # Apple Silicon ランナー（Xcode 15 がプリインストール済み）

env:

JAVA_HOME: /Applications/Android\ Studio.app/Contents/jbr/Contents/Home

# 非 macOS 環境で iOS ビルドが必要な場合は下記のように DEVELOPER_DIR を設定

# DEVELOPER_DIR: ${{ secrets.XCODE_PATH }}

steps:

- uses: actions/checkout@v4

- name: Set up JDK 17

uses: actions/setup-java@v3

with:

distribution: temurin

java-version: 17

- name: Install Android SDK

uses: android-actions/setup-android@v2

- name: Gradle cache

uses: gradle/gradle-build-action@v2

- name: Build all targets

run: |

./gradlew clean \

:shared:assembleDebugIosSimulatorArm64 \

:shared:jsBrowserProductionWebpack \

:app:bundleRelease

- name: Upload iOS framework

uses: actions/upload-artifact@v4

with:

path: shared/build/bin/iosSimulatorArm64/debugFramework/*.framework

- name: Upload Android AAR

uses: actions/upload-artifact@v4

with:

path: shared/build/outputs/aar/*.aar

macos-14 ランナーは Apple Silicon であり、Xcode 15 が標準搭載されているため iOS ビルドがそのまま可能です。
非 macOS のセル（例：Ubuntu）で iOS をビルドしたい場合は、事前に Xcode バイナリを自前で用意し、DEVELOPER_DIR 環境変数でパスを指すようにします。

まとめ：上記 YAML をリポジトリの .github/workflows/ に配置するだけで、Android・iOS・JVM・JS の全ターゲットが自動ビルドされ、成果物（.framework, .aar）がダウンロード可能になります。

トラブルシューティング：よくあるエラーと対策

エラー	主な原因	解決策
`Could not resolve all files for configuration ':shared:iosSimulatorArm64CompileClasspath'`	Version Catalog に未定義のライブラリが記述されている	`libs.versions.toml` を再確認し、`version.ref` が正しいか検証
`Execution failed for task ':shared:linkDebugFrameworkIosSimulatorArm64'`	Xcode SDK パスが古い、または `DEVELOPER_DIR` 未設定	CI では `xcode-select -p` を実行し、期待通りの Xcode バージョンを指すようにする
`ClassNotFoundException: org.jetbrains.kotlin.gradle.plugin.KotlinMultiplatformPluginWrapper`	Kotlin プラグインが破損または古い	Android Studio の Plugins で Kotlin を最新 (2.0+) に更新し、`./gradlew wrapper --distribution-type=all` で Gradle ラッパーを再生成
iOS テスト実行時に “Test bundle failed to load”	フレームワークの埋め込み設定が `Do Not Embed` になっている	Xcode の General → Embedded Content を必ず Embed & Sign に変更

共通予防策

ビルド前に常に ./gradlew clean を実行。
CI ログで --stacktrace --info オプションを付与し、詳細情報を取得。
エラーメッセージをそのまま公式ドキュメントや Kotlin Slack の検索窓に貼り付けて最新の解決策を確認。

まとめ：エラーは「バージョン不整合」か「Xcode 設定ミス」のどちらが多いです。libs.versions.toml と DEVELOPER_DIR の正しさだけでも、ほとんどの問題は防げます。

まとめ（簡潔版）

項目	要点
開発環境	JDK 17+、Android Studio Giraffe/2024.1.2、Kotlin プラグイン 2.0 以上を必ず使用。
プロジェクト作成	ウィザードで `android`, `iosSimulatorArm64`, `jvm`, `js` の 4 ターゲットを選択すれば自動構成完了。
Gradle 設定	Kotlin Multiplatform プラグインと Version Catalog を組み合わせるだけで依存管理が一元化。
iOS 連携	Swift Package Manager が推奨。`./gradlew assembleDebugIosSimulatorArm64` → Xcode の Embed & Sign 設定で完了。macOS 以外は `DEVELOPER_DIR`／`iosSdkPath` を明示的に渡すこと。
既存プロジェクト統合	`shared` モジュールを追加し、`implementation(project(":shared"))` を宣言するだけで完了。
CI/CD	macOS‑14 ランナー + Gradle キャッシュで全ターゲット自動ビルド。成果物は GitHub Actions の artifact として取得可能。
トラブル対策	バージョンカタログと Xcode SDK パスの整合性を保ち、エラー時は公式メッセージ検索で即解決。

この手順をそのままプロジェクトに適用すれば、2026 年時点の最新ツールチェーンで Kotlin Multiplatform を本格的に活用できる開発環境が即座に構築できます。

スポンサードリンク

お得なお知らせ

スポンサードリンク

AI時代のキャリア構築

プログラミング学習、今日から動き出す

「何から始めるか」で止まっている人こそ、無料説明会や本で自分に合うルートを30分で確定できます。

Enjoy Tech!｜月額制でWeb系に強い▶ (Kindle本)ＩＴエンジニアの転職学｜後悔しないキャリア戦略▶

▶ AIコーディング環境なら実践Claude Code入門（Amazon）が実務で即使える入門書です。Amazonベストセラーにも選ばれていますよ。

-Kotlin

comment コメントをキャンセル

: Kotlin

Kotlin Multiplatform 入門：最新KMPでAndroidとiOSをコード共有

Kotlin Multiplatform の基本概念から環境構築、Codelab に沿ったステップ別実装方法、依存関係とテスト戦略までをゼロから解説します。

: Kotlin

Android Studio Flamingoで始めるKotlin/Compose入門と開発手順

Flamingo版Android StudioとOpenJDK17を正しく導入し、KotlinとComposeの基礎からプロジェクト構成、ビルド・リリースまで一連の開発手順をまとめました。

: Kotlin

Jetpack Compose と Coroutines の相性と実践的非同期 UI パターン

Jetpack Compose は UI 再コンポジションや副作用処理に Coroutines を採用し、非同期ロジックと状態管理を統一的に扱えます。本稿では LaunchedEffect・produceState・rememberCoroutineScope・ViewModel の StateFlow/SharedFlow など実践的パターンとコード例を紹介します。

: Kotlin

2024年最新・無料Kotlin学習教材まとめと始め方

Kotlinは無料教材が充実しており、2024年7月更新のリソースだけで初心者がHello, World!アプリを作成できます。

: Kotlin

Kotlin Multiplatform と Flutter の比較：アーキテクチャ・性能・開発効率

KMPはビジネスロジックのみ共有し、FlutterはUIも含めてコードベース全体を単一のウィジェットツリーで共有する点が最大の違いです。

2026年4月限定『おてがる光』キャンペーン概要と最大73,862円割引の全情報

2026年LINEマンガ無料キャンペーン完全ガイド：春・夏・秋の巻と日替わり全話無料

Kotlin Multiplatform 開発環境セットアップと CI/CD 完全ガイド

開発環境のセットアップ

JDK 17+ と Android Studio Giraffe/2024.1.2 のインストール

手順

Kotlin プラグイン 2.0 以降の適用方法

手順

KMP プロジェクトの新規作成

Kotlin Multiplatform プラグインの有効化（ウィザード使用）

手順

対象プラットフォームの推奨構成

Gradle Kotlin DSL と依存関係管理

基本的な build.gradle.kts 設定例

sourceSets とコード配置のベストプラクティス

バージョンカタログ (libs.versions.toml) の活用

gradle/libs.versions.toml

build.gradle.kts 側の記述

iOS ビルドと Xcode 連携

CocoaPods と Swift Package Manager の比較（2026 年版）

Xcode 15+ 用プロジェクト設定（フレームワークの埋め込み）

手順

macOS 以外でのビルド例（GitHub Actions 用）

シミュレータ・実機でのテスト手順

既存プロジェクトへの KMP 追加と CI/CD

既存 Android アプリへ shared モジュールを統合する手順

GitHub Actions + Gradle によるマルチプラットフォーム自動ビルド例

トラブルシューティング：よくあるエラーと対策

共通予防策

まとめ（簡潔版）

JDK 17+ と Android Studio Giraffe/2024.1.2 のインストール

基本的な `build.gradle.kts` 設定例

`sourceSets` とコード配置のベストプラクティス

バージョンカタログ (`libs.versions.toml`) の活用

`gradle/libs.versions.toml`

`build.gradle.kts` 側の記述

既存 Android アプリへ `shared` モジュールを統合する手順