안드로이드 build.gradle.kts 완벽 설정 가이드: Kotlin DSL로 빌드 스크립트 다루기

안드로이드 스튜디오로 새 프로젝트를 만들면 가장 먼저 마주치는 파일 중 하나가 build.gradle.kts입니다. 화면에 보이는 UI 코드도 아니고, 비즈니스 로직도 아니지만, 이 파일을 제대로 이해하지 못하면 "분명히 라이브러리를 추가했는데 import가 안 된다", "minSdk를 바꿨는데 적용이 안 된다", "동기화(Sync)만 누르면 빨간 줄이 뜬다" 같은 상황에서 시간을 허비하게 됩니다.

이 글에서는 Kotlin DSL(.kts) 기반의 build.gradle.kts 파일을 블록 단위로 분해해 살펴보고, 실무에서 자주 막히는 부분과 해결 방법까지 정리합니다.

왜 build.gradle 이 아니라 build.gradle.kts 인가

과거 안드로이드 빌드 스크립트는 Groovy 언어로 작성된 build.gradle 파일이 표준이었습니다. 지금은 최신 안드로이드 스튜디오가 새 프로젝트를 생성할 때 기본으로 Kotlin DSL(build.gradle.kts)을 사용합니다. 둘은 같은 Gradle 빌드를 기술하지만 작성 언어가 다릅니다.

항목	Groovy DSL (build.gradle)	Kotlin DSL (build.gradle.kts)
작성 언어	Groovy (동적 타입)	Kotlin (정적 타입)
IDE 자동완성	제한적	강력함 (타입 추론 기반)
오타 검출	런타임에 발견	작성 시점에 빨간 줄
문법	괄호·따옴표 생략 가능	함수 호출처럼 명시적

핵심 차이는 타입 안전성입니다. Groovy에서는 minSdkVersion 24처럼 써도 동작했지만, Kotlin DSL에서는 minSdk = 24처럼 프로퍼티 할당 형태로 명시해야 합니다. 덕분에 잘못된 값을 넣으면 빌드를 돌리기 전에 에디터가 먼저 알려줍니다.

build.gradle.kts 의 핵심 블록 정리

안드로이드 프로젝트에는 보통 두 개의 build.gradle.kts가 있습니다. 하나는 프로젝트 루트(전역 설정), 다른 하나는 app 모듈(앱 단위 설정)입니다. 아래는 모듈 수준 파일에서 자주 쓰는 블록들입니다.

1. plugins 블록 — 무엇을 적용할지 선언

// 모듈에 적용할 Gradle 플러그인을 선언하는 영역
plugins {
    alias(libs.plugins.android.application)  // 안드로이드 앱 빌드
    alias(libs.plugins.kotlin.android)       // 코틀린 컴파일 지원
    // 라이브러리 모듈이라면 android.application 대신 android.library 사용
}

최신 프로젝트는 버전을 libs.versions.toml(버전 카탈로그)에서 끌어오는 alias(...) 방식을 씁니다. 직접 문자열로 쓰려면 id("com.android.application") version "8.x.x" 형태가 됩니다.

2. android 블록 — 앱의 정체성과 빌드 규칙

android {
    namespace = "com.example.myapp"   // 생성되는 R 클래스의 패키지 경로
    compileSdk = 34                    // 컴파일에 사용할 SDK 버전

    defaultConfig {
        applicationId = "com.example.myapp" // 스토어에서 앱을 식별하는 고유 ID
        minSdk = 24                         // 지원하는 최소 OS 버전
        targetSdk = 34                      // 테스트·최적화 기준 버전
        versionCode = 1                     // 내부 버전 번호(정수, 업데이트마다 증가)
        versionName = "1.0.0"               // 사용자에게 보이는 버전 문자열
    }

    buildTypes {
        release {
            isMinifyEnabled = true          // 코드 축소(R8) 활성화
            proguardFiles(
                getDefaultProguardFile("proguard-android-optimize.txt"),
                "proguard-rules.pro"
            )
        }
    }

    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }
}

여기서 헷갈리기 쉬운 두 가지는 applicationId와 namespace입니다. namespace는 코드 내부에서 R 클래스 등을 참조할 때 쓰는 패키지이고, applicationId는 구글 플레이에서 앱을 식별하는 값입니다. 초기엔 같게 두는 경우가 많지만 의미가 다릅니다.

3. dependencies 블록 — 외부 라이브러리 연결

dependencies {
    implementation(libs.androidx.core.ktx)          // 일반 의존성
    implementation(libs.androidx.appcompat)
    testImplementation(libs.junit)                  // 단위 테스트에서만 사용
    androidTestImplementation(libs.androidx.espresso.core) // 계측 테스트용

    // 카탈로그를 안 쓸 때의 직접 표기 예시
    // implementation("com.squareup.retrofit2:retrofit:2.11.0")
}

implementation과 api의 차이도 알아두면 좋습니다. implementation은 해당 라이브러리를 이 모듈 안에서만 쓰고 외부에 노출하지 않아 빌드 속도와 캡슐화에 유리합니다. 라이브러리 모듈을 만들고 그 의존성을 사용하는 쪽에도 전파하고 싶을 때만 api를 씁니다.

4. repositories — 라이브러리를 어디서 받을지

// 보통 settings.gradle.kts 의 dependencyResolutionManagement 안에 둔다
dependencyResolutionManagement {
    repositories {
        google()        // 안드로이드 / 구글 라이브러리
        mavenCentral()  // 범용 오픈소스 라이브러리
    }
}

최신 프로젝트에서는 저장소 선언이 모듈의 build.gradle.kts가 아니라 settings.gradle.kts로 옮겨갔습니다. 옛 블로그를 따라 모듈 파일에 repositories {}를 넣으면 충돌 경고가 날 수 있으니 위치를 먼저 확인하세요.

5. 그 외 자주 쓰는 블록

• buildscript: 빌드 도구 자체(플러그인 클래스패스)에 필요한 의존성을 선언. 버전 카탈로그가 보급되면서 직접 만질 일은 줄었습니다.
• subprojects / allprojects: 멀티 모듈 프로젝트에서 공통 설정을 한 번에 적용. 다만 모듈이 많아지면 컨벤션 플러그인으로 빼는 편이 깔끔합니다.
• tasks.register: 커스텀 빌드 작업 정의. 예) 빌드 전에 버전 파일을 자동 생성.
• extra: 여러 곳에서 공유할 상수 정의. 카탈로그가 이 역할을 상당 부분 대체했습니다.

단계별 설정 흐름

1. 루트 build.gradle.kts에서 사용할 플러그인을 apply false로 선언한다.
2. settings.gradle.kts에서 저장소와 모듈(include(":app"))을 등록한다.
3. 모듈 build.gradle.kts의 plugins에 실제 적용할 플러그인을 넣는다.
4. android 블록에서 compileSdk, minSdk, versionName 등을 채운다.
5. dependencies에 필요한 라이브러리를 추가한다.
6. 상단의 Sync Now를 눌러 Gradle 동기화를 수행한다.

흔한 실수와 엣지 케이스

1) 따옴표·할당 문법 혼동
Groovy 습관으로 compileSdk 34처럼 등호 없이 쓰면 Kotlin DSL에서는 에러입니다. 반드시 compileSdk = 34로 할당하세요.

2) Gradle / AGP / JDK 버전 불일치
Android Gradle Plugin(AGP) 버전과 Gradle 버전, 그리고 사용하는 JDK 버전은 호환 표가 정해져 있습니다. Unsupported class file major version 같은 에러는 대부분 JDK 버전이 너무 높거나 낮을 때 발생합니다. AGP 8.x는 보통 JDK 17을 요구합니다.

3) minSdk 변경 후 미반영
값을 바꾸고 Sync를 안 하면 적용되지 않습니다. 변경 후에는 항상 동기화하고, 그래도 안 되면 Build > Clean Project 후 다시 빌드하세요.

4) 캐시로 인한 의존성 해석 실패
라이브러리를 추가했는데 import가 안 될 때는 네트워크 문제이거나 캐시 문제일 수 있습니다. 터미널에서 다음을 시도하세요.

# Gradle 캐시를 무시하고 의존성을 새로 받아 빌드
./gradlew clean build --refresh-dependencies

5) namespace 누락
AGP 8 이상에서는 android 블록에 namespace가 없으면 빌드가 실패합니다. 과거 AndroidManifest.xml의 package 속성으로 대체하던 방식은 더 이상 권장되지 않습니다.

요약

• build.gradle.kts는 Kotlin DSL로 작성하는 안드로이드 빌드 설정 파일로, Groovy 대비 타입 안전성과 자동완성이 강점이다.
• 핵심 블록은 plugins, android, dependencies 세 가지이며, 저장소 선언은 settings.gradle.kts로 이동했다.
• 값은 항상 프로퍼티 = 값 형태로 할당하고, 변경 후에는 반드시 Sync를 수행한다.
• 빌드 에러의 다수는 AGP·Gradle·JDK 버전 불일치 또는 캐시 문제이므로, 호환 버전 확인과 --refresh-dependencies로 대부분 해결된다.

AI에게 물어볼 때 (프롬프트 팁)

빌드 설정 문제는 에러 메시지 한 줄에 원인이 숨어 있는 경우가 많습니다. ChatGPT나 Claude 같은 AI에게 물어볼 때는 맥락(버전)과 전체 에러를 함께 주면 정확도가 크게 올라갑니다. 아래는 Prompt Architect가 추천하는 프롬프트 예시입니다.

1. 버전 충돌 진단용 프롬프트
   "Android 프로젝트에서 AGP 8.5, Gradle 8.9, JDK 21을 쓰고 있어. 빌드 시 Unsupported class file major version 65 에러가 난다. 호환되는 JDK 버전과 build.gradle.kts에서 바꿔야 할 설정을 단계별로 알려줘."

2. Groovy → Kotlin DSL 변환용 프롬프트
   "아래 build.gradle (Groovy) 코드를 동작이 동일한 build.gradle.kts (Kotlin DSL)로 변환해줘. 각 변경 라인에 왜 바뀌었는지 주석을 한국어로 달아줘: [여기에 코드 붙여넣기]"

3. 의존성 정리용 프롬프트
   "내 dependencies 블록이야. 중복되거나 불필요한 의존성, implementation을 써야 하는데 api로 잘못 선언된 항목을 찾아서 표로 정리해줘: [코드 붙여넣기]"

프롬프트에 "버전 정보 + 전체 에러 로그 + 원하는 출력 형태(표/단계/주석)"를 명시하는 것이 핵심입니다. 더 정교한 프롬프트 작성법이 궁금하다면 Prompt Architect의 프롬프트 분석기로 자신의 질문을 점검해 보세요.