Kotlin Multiplatform(KMP)으로 크로스 플랫폼 개발을 시작하려는 개발자들을 위한 실전 가이드입니다. 2025년 7월 현재 기준으로 최신 정보를 담았습니다.
KMP란 무엇인가
Kotlin Multiplatform은 단일 코드베이스로 여러 플랫폼(Android, iOS, Desktop, Web)을 타겟팅할 수 있는 기술입니다. 비즈니스 로직은 물론 Compose Multiplatform을 통해 UI까지 공유할 수 있습니다.
개발 환경 설정
필수 도구
- Android Studio Narwhal 2025.1.1 이상 또는 IntelliJ IDEA 2025.1.1.1 이상
- JDK 11 이상 (JDK 15+ 권장)
- Kotlin Multiplatform Plugin (Android Studio에서 자동 설치)
- Xcode (iOS 개발 시, Mac 필수)
중요: 2025년부터 Android Studio에 KMP 프로젝트 생성이 완전히 통합되었습니다. 별도의 웹 마법사나 템플릿을 사용할 필요가 없습니다.
프로젝트 생성
방법 1: Android Studio에서 새 프로젝트 생성 (권장)
- File → New → New Project
- 왼쪽 목록에서 Kotlin Multiplatform 선택
- 프로젝트 정보 입력:
- Name: 프로젝트명 (예: KmpLab)
- Package name: com.example.kmplab
- Save location: 저장 위치
- 타겟 플랫폼 선택:
- Android
- iOS
- Desktop
- Web
- UI 프레임워크 선택:
- Shared UI (Compose Multiplatform) - UI 공유
- Native UI - 각 플랫폼별 네이티브 UI
K2 모드 활성화
Settings → Languages & Frameworks → Kotlin에서 Enable K2 mode 체크박스를 선택해야 합니다.
방법 2: Kotlin Multiplatform Wizard 사용
웹 브라우저에서 빠르게 프로젝트를 생성하고 싶다면 Kotlin Multiplatform Wizard를 사용할 수 있습니다:
- 웹사이트 접속 후 원하는 설정 선택:
- Project Name: 프로젝트명
- Project ID: 패키지명 (예: com.example.kmplab)
- 플랫폼 선택: Android, iOS, Desktop, Web
- UI Framework: Compose Multiplatform 또는 Native UI
- Download 버튼 클릭
- ZIP 파일 다운로드 후 압축 해제
- Android Studio나 IntelliJ IDEA로 프로젝트 열기
이 방법은 IDE를 열지 않고도 웹에서 빠르게 프로젝트 템플릿을 생성할 수 있어 편리합니다. 특히 다양한 설정 조합을 미리 확인하고 싶을 때 유용합니다.
프로젝트 구조 이해하기
프로젝트/
├── composeApp/ # 멀티플랫폼 공통 모듈
│ └── src/
│ ├── commonMain/ # 모든 플랫폼 공통 코드
│ ├── androidMain/ # Android 전용 코드
│ ├── iosMain/ # iOS 전용 코드
│ ├── desktopMain/ # Desktop 전용 코드
│ └── wasmJsMain/ # Web 전용 코드
├── iosApp/ # iOS 앱 프로젝트 (Xcode)
├── server/ # 서버 모듈 (선택사항)
└── gradle/ # Gradle 설정 파일들주요 개념: expect/actual
플랫폼별 구현이 필요한 경우 expect/actual 메커니즘을 사용합니다:
// commonMain에서 선언
expect fun getPlatformName(): String
// androidMain에서 구현
actual fun getPlatformName(): String = "Android"
// iosMain에서 구현
actual fun getPlatformName(): String = "iOS"
// desktopMain에서 구현
actual fun getPlatformName(): String = "Desktop"각 플랫폼별 실행 방법
주의: commonMain은 직접 실행하는 것이 아닙니다. 각 플랫폼을 실행할 때 commonMain의 코드가 자동으로 포함되어 빌드됩니다.
Android 실행
- Run Configuration:
composeApp - 에뮬레이터나 실제 기기 선택
- Run 버튼 클릭
iOS 실행 (Mac 필수)
- Run Configuration:
iosApp - 시뮬레이터 선택
- Run 버튼 클릭
Desktop 실행
- Run Configuration:
composeApp [desktop] - Run 버튼 클릭
- 별도의 윈도우로 앱이 실행됨
Web 실행
- Run Configuration:
composeApp [wasmJs] - Run 버튼 클릭
- 브라우저에서 자동으로 열림 (기본: http://localhost:8080)
iOS 개발 시 주의사항
Development Team 설정 오류 해결
오류: Signing for "iosApp" requires a development team. Select a development team in the Signing & Capabilities editor.이 오류는 iOS 앱을 실행하려면 Apple Developer 계정이 필요하기 때문에 발생합니다. 해결 방법:
방법 1: Xcode에서 설정 (권장)
- Xcode 열기
- Open a project or file 선택
iosApp/iosApp.xcworkspace파일 선택- 왼쪽 네비게이터에서 iosApp 선택
- Signing & Capabilities 탭으로 이동
- Team 드롭다운에서:
- 기존 팀이 있다면 선택
- 없다면 "Add an Account" 선택 후 Apple ID로 로그인
- "Automatically manage signing" 체크박스 선택
Xcode에서 설정하면 project.pbxproj 파일에 자동으로 Team ID가 저장되어, Android Studio에서도 별도 설정 없이 바로 실행할 수 있습니다.
팁: 무료 Apple ID로도 개발 및 테스트가 가능합니다. 개인 개발자 계정 없이도 시뮬레이터와 실제 기기에서 자유롭게 테스트할 수 있습니다.
의존성 관리
공통 의존성 추가
composeApp/build.gradle.kts 파일에서:
kotlin {
sourceSets {
val commonMain by getting {
dependencies {
implementation(compose.runtime)
implementation(compose.foundation)
implementation(compose.material3)
implementation(compose.ui)
// 네비게이션
implementation("cafe.adriel.voyager:voyager-navigator:1.0.0")
// 네트워크
implementation("io.ktor:ktor-client-core:2.3.7")
// 직렬화
implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.0")
}
}
val androidMain by getting {
dependencies {
implementation("io.ktor:ktor-client-android:2.3.7")
}
}
val iosMain by getting {
dependencies {
implementation("io.ktor:ktor-client-darwin:2.3.7")
}
}
}
}첫 번째 공통 UI 작성
composeApp/src/commonMain/kotlin/App.kt:
@Composable
fun App() {
MaterialTheme {
var count by remember { mutableStateOf(0) }
Column(
modifier = Modifier.fillMaxSize(),
horizontalAlignment = Alignment.CenterHorizontally,
verticalArrangement = Arrangement.Center
) {
Text(
text = "You clicked $count times on ${getPlatformName()}",
style = MaterialTheme.typography.headlineMedium
)
Spacer(modifier = Modifier.height(16.dp))
Button(onClick = { count++ }) {
Text("Click me!")
}
}
}
}2025년 주요 업데이트 사항
- Compose Multiplatform 1.8.0: iOS가 Stable로 전환되어 프로덕션 사용 가능
- KMP Plugin 통합: Android Studio와 IntelliJ IDEA에 완전 통합
- Compose Hot Reload: UI 변경사항을 재시작 없이 즉시 확인
- Swift 지원 강화: 코드 하이라이팅, 네비게이션, 디버깅 지원
- 성능 개선: 네이티브 앱 대비 약 9MB만 추가, 시작 시간과 스크롤 성능 동등
자주 발생하는 문제와 해결법
Gradle JDK 설정 문제
Settings → Build, Execution, Deployment → Build Tools → Gradle에서 Gradle JDK를 JDK 11 이상으로 설정
Android SDK 경로 문제
local.properties 파일에 다음 추가:
sdk.dir=/Users/username/Library/Android/sdkiOS 시뮬레이터가 보이지 않는 경우
Xcode를 실행하고 업데이트가 있는지 확인. 필요시 iOS 시뮬레이터 다운로드
마무리
KMP는 2025년 현재 안정적인 크로스 플랫폼 솔루션으로 자리잡았습니다. 특히 Android Studio의 완전한 통합과 Compose Multiplatform의 iOS 안정화로 실제 프로덕션에서 사용하기에 충분히 성숙했습니다.
처음 시작할 때는 복잡해 보일 수 있지만, 한 번 환경을 구성하고 나면 매우 효율적인 개발이 가능합니다. 특히 비즈니스 로직뿐만 아니라 UI까지 공유할 수 있다는 점은 개발 생산성을 크게 향상시킵니다.
추가 리소스:
