[Android] Hilt의 kapt → ksp 마이그레이션 및 버전 호환성 이슈 해결

알린·2025년 2월 4일

android hilt ksp

TroubleShooting

목록 보기

28/29

에러 상황

KAPT에서 KSP로 마이그레이션

KAPT 대신 KSP를 사용하여 컴파일 성능을 향상하고 Hilt와의 호환성을 높일 수 있다.
따라서 기존의 KAPT를 사용하던 Hilt를 KSP로 마이그레이션 했다.

기존 코드
앱 수준 build.gradle.kts

plugins {
    id("com.android.application")
    id("org.jetbrains.kotlin.android")
    // Hilt
    id("kotlin-kapt")
    id("com.google.dagger.hilt.android")
}

변경 코드
앱 수준 build.gradle.kts

plugins {
    id("com.android.application")
    id("org.jetbrains.kotlin.android")
    // Hilt
    id("com.google.devtools.ksp")  // KSP로 변경
    id("dagger.hilt.android.plugin")  // Hilt 플러그인 추가
    id("com.google.dagger.hilt.android")
}

이러한 빌드환경 변경으로 다양한 빌드 에러를 마주했다. 그 중 버전 호환성 문제가 가장 문제가 되었다.

빌드 시 다음 에러가 발생했다.

This version (1.5.1) of the Compose Compiler requires Kotlin version 1.9.0 but you appear to be using Kotlin version 1.9.23 which is not known to be compatible. Please consult the Compose-Kotlin compatibility map located at https://developer.android.com/jetpack/androidx/releases/compose-kotlin to choose a compatible version pair (or suppressKotlinVersionCompatibilityCheck but don't say I didn't warn you!).

에러 원인 및 해결

에러 원인

에러 메시지를 보면 현재 사용 중인 Compose Compiler 버전(1.5.1)이 Kotlin 1.9.0과 호환되지만, 현재 프로젝트에서는 Kotlin 1.9.23을 사용하고 있어서 호환성 문제가 발생했다는 것을 알 수 있다.

이 오류의 근본 원인은 프로젝트의 build.gradle.kts 파일에서 Hilt와 KSP 버전이 호환되지 않았기 때문이다.

1. Kotlin과 Compose Compiler 버전 호환성 이슈

Jetpack Compose를 사용할 시 특히 Compose Compiler는 특정 Kotlin 버전과만 호환되고 있다는 것을 매우 유의해야 한다.
따라서 Compose-Kotlin 호환성 표에서 현재 내 프로젝트에 설정되어 있는 Kotlin 버전과 호환되는 Compose Compiler 버전을 선택해야 한다.

나의 경우는 프로젝트 수준 build.gradle.kts에서 설정한 Kotlin 버전이 앱 수준 build.gradle.kts에서 설정한 Compose Compiler 버전이 호환이 안되어 빌드 오류가 생겼다.

👿 에러 원인 코드
프로젝트 수준 build.gradle.kts
plugins {
    id("org.jetbrains.kotlin.android") version "1.9.22" apply false
}
앱 수준 build.gradle.kts
composeOptions {
    kotlinCompilerExtensionVersion = "1.5.1"
}

2. KSP 플러그인 누락

KAPT에서 KSP로 마이그레이션 과정 중 프로젝트 수준 build.gradle.kts에서 com.google.devtools.ksp 플러그인이 누락되어 오류가 발생했다.

👿 에러 원인 코드
프로젝트 수준 build.gradle.kts

plugins {
    id("com.android.application") version "8.2.2" apply false
    id("org.jetbrains.kotlin.android") version "1.9.0" apply false
    id("com.google.dagger.hilt.android") version "2.51.1" apply false
    // com.google.devtools.ksp 플러그인 설정 누락
}

에러 해결

1. Kotlin과 Compose Compiler 버전 호환성 보완

Compose-Kotlin 호환성 표를 참고해 현재 내 프로젝트의 Compose Compiler 버전인 1.5.1에 맞추어 1.9.22였던 Kotlin 버전을 1.9.0로 수정했다.

프로젝트 수준 build.gradle.kts

plugins {
    id("org.jetbrains.kotlin.android") version "1.9.0" apply false
}

앱 수준 build.gradle.kts

composeOptions {
    kotlinCompilerExtensionVersion = "1.5.1"
}

🚨 주의
Kotlin 버전이 2.0.0 이상일 경우 수동으로 Compose Compiler 버전을 설정해주는 것이 아닌 Compose 컴파일러 Gradle 플러그인 공식문서를 참고하여 Compose 사용을 설정해야한다.

2. KSP 플러그인 추가

KSP 릴리즈 로그 공식문서를 참고해서 Kotlin 버전과 동일한 KSP 버전을 선택해야 한다.

나의 경우 Kotlin 버전이 1.9.0 였기 때문에 KSP 플러그인 버전도 동일한 1.9.0으로 설정했다.

plugins {
    id("com.android.application") version "8.2.2" apply false
    id("org.jetbrains.kotlin.android") version "1.9.0" apply false
    id("com.google.dagger.hilt.android") version "2.51.1" apply false
    id("com.google.devtools.ksp") version "1.9.0-1.0.13"  // KSP 플러그인 추가
}