React Native APK 빌드 방법

React Native APK 빌드 방법에 대해 정리한 페이지입니다.

Posted Jun 19, 2025

By HyunJinNo

9 min read

React Native APK 빌드 방법

Tags
APK, Mobile, React Native, TypeScript

Environment
OS: Windows 11
react v19.0.0
react-native v0.79.2

개요

React Native 프로젝트에서 APK 빌드 방법에 대해 정리한 페이지입니다. Debug APK (테스트용 APK) 빌드 방법과 Release APK (배포용 APK) 빌드 방법을 각각 정리하였습니다.

Debug APK vs Release APK

Debug API와 Release APK를 표로 비교하면 다음과 같습니다.

항목	Debug APK	Release APK
목적	개발/테스트용	배포용
최적화	X	O
Metro 서버	필요함 (기본 설정상 JS 코드가 서버에서 로드됨)	불필요함 (JS 코드가 앱에 내장되어 번들링됨)
디버그 도구	로그, DevTools 등 사용 가능	사용 불가능
서명	디버그 키로 자동 서명됨	배포용 키로 수동 서명 필요
명령어	`assembleDebug`	`assembleRelease`

정리하자면, Debug APK는 개발 및 QA, 내부 테스트를 위해 디버깅 정보와 비최적화 코드, 디버그 키로 서명되어 빠른 문제 파악이 용이하지만 보안상 취약하며 성능 최적화가 되어 있지 않습니다. 반면에 Release APK는 배포를 위해 코드 최적화, 난독화, 불필요한 디버깅 정보 제거 등 보안과 성능 측면에서 개선된 APK로, 개발자가 생성한 keystore로 서명되어 업데이트 관리가 용이합니다.

Debug APK 빌드하기

먼저 프로젝트 루트에서 android 폴더로 이동합니다.

cd android

이후 다음 명령어를 입력하여 Debug APK를 빌드할 수 있습니다.

./gradlew assembleDebug

Info.
./gradlew assembleDebug 명령어는 React Native 앱의 Debug APK 파일을 생성할 때 사용하는 명령어입니다.

./gradlew
- 프로젝트 내에 있는 Gradle Wrapper 실행 파일
- Gradle이 시스템에 설치되어 있지 않아도 빌드할 수 있게 해줌.
- ./gradlew는 Linux/Mac, gradlew.bat은 Windows용

assembleDebug
- Debug 빌드 변형(variant)을 만들어주는 Gradle task
- 단어 그대로 디버깅용 APK를 만드는 명령어
- 실제 생성 파일: android/app/build/outputs/apk/debug/app-debug.apk

빌드 완료 후 다음 경로에서 빌드된 APK를 확인할 수 있습니다.

android/app/build/outputs/apk/debug/app-debug.apk

Release APK 빌드하기

Step 1 - 배포용 키 생성하기

먼저 프로젝트 루트에서 android/app 폴더로 이동합니다.

cd android/app

이후 다음 명령어를 입력하여 배포용 키를 생성합니다.

  
keytool -genkeypair -v -keystore release.keystore -alias my-key-alias -keyalg RSA -keysize 2048 -validity 10000

Info.
keytool
- Java JDK에 포함된 도구로, 안드로이드 앱 출시용 서명에 사용할 keystore와 키를 생성할 때 사용합니다.
- keytool -help로 전체 옵션을 확인할 수 있습니다.

-genkey 또는 -genkeypair
- 공개키와 개인키를 생성합니다.

-v
- verbose라는 의미로, 생성 과정을 상세히 출력합니다.

-keystore release.keystore
- 생성할 keystore 파일의 이름과 경로를 지정합니다.
- 보통 android/app 폴더에 복사해 두고, Gradle 설정에서 참조합니다.

-alias my-key-alias
- keystore 안에 저장될 키에 붙일 별칭을 지정합니다.
- 하나의 keystore에 여러 키를 보관할 수 있으므로, 별칭을 사용하여 구분합니다.
- Ex. app-release, upload-key 등으로 직관적으로 짓는 것이 좋습니다.

-keyalg RSA
- 키 생성 알고리즘을 지정합니다.

-keysize 2048
- 키의 비트 길이를 지정합니다.
- 2048 비트는 현재 널리 권장되는 보안 수준이며, 배포 환경에서는 최소 2048 비트 이상을 사용하는 것이 권장됩니다.

-validity 10000
- 키의 유효 기간을 일(day) 단위로 지정합니다.
- 10000일이면 약 27년 동안 유효합니다.

명령어 입력 이후 다음과 같이 비밀번호와 이름, 조직 등 문항을 입력하면 keystore 파일이 생성됩니다.

Step 2 - Gradle에 서명 정보 추가하기

android/gradle.properties 파일에 다음 내용을 추가합니다.

  
MYAPP_UPLOAD_STORE_FILE=[keystore 파일의 이름]
MYAPP_UPLOAD_KEY_ALIAS=[keystore를 생성할 때 설정한 별칭]
MYAPP_UPLOAD_STORE_PASSWORD=[keystore 파일의 비밀번호]
MYAPP_UPLOAD_KEY_PASSWORD=[keystore 안에 생성된 개별 키(alias)의 비밀번호]

예를 들어 step 1 - 배포용 키 생성하기에서 생성한 keystore를 기준으로 설정한다면 다음과 같이 입력하면 됩니다.

  
MYAPP_UPLOAD_STORE_FILE=release.keystore
MYAPP_UPLOAD_KEY_ALIAS=my-key-alias
MYAPP_UPLOAD_STORE_PASSWORD=my-password
MYAPP_UPLOAD_KEY_PASSWORD=my-password

Info.
위의 예시에서 개별 키에 대한 비밀번호를 설정하지 않았으므로 MYAPP_UPLOAD_KEY_PASSWORD에는 keystore 비밀번호와 동일하게 설정되었습니다. 즉, MYAPP_UPLOAD_STORE_PASSWORD와 동일한 값을 설정하면 됩니다.

이후 android/app/build.gradle 파일을 열어서, android { } 블록 안에 signingConfigs와 buildTypes를 설정합니다.

  
/* ... */

android {
    /* ... */

    signingConfigs {
        /* ... */

        release {
            if (project.hasProperty('MYAPP_UPLOAD_STORE_FILE')) {
                storeFile file(MYAPP_UPLOAD_STORE_FILE)
                storePassword MYAPP_UPLOAD_STORE_PASSWORD
                keyAlias MYAPP_UPLOAD_KEY_ALIAS
                keyPassword MYAPP_UPLOAD_KEY_PASSWORD
            }
        }
    }

    buildTypes {
        release {
            // Caution! In production, you need to generate your own keystore file.
            // see https://reactnative.dev/docs/signed-apk-android.
            signingConfig signingConfigs.release
            minifyEnabled enableProguardInReleaseBuilds
            proguardFiles getDefaultProguardFile("proguard-android.txt"), "proguard-rules.pro"
        }
    }
}

/* ... */

Step 3 - Release APK 생성하기

먼저 프로젝트 루트에서 android 폴더로 이동합니다.

cd android

이후 다음 명령어를 입력하여 Release APK를 빌드할 수 있습니다.

./gradlew assembleRelease

PS C:\Users\user\vscode\braille-translator> cd android
PS C:\Users\user\vscode\braille-translator\android> ./gradlew assembleRelease
Starting a Gradle Daemon, 1 incompatible and 1 stopped Daemons could not be reused, use --status for details

/* ... */

> Task :react-native-vision-camera:configureCMakeRelWithDebInfo[x86_64]
C/C++: VisionCamera: Frame Processors: OFF!

[Incubating] Problems report is available at: file:///C:/Users/user/vscode/braille-translator/android/build/reports/problems/problems-report.html

Deprecated Gradle features were used in this build, making it incompatible with Gradle 9.0.

You can use '--warning-mode all' to show the individual deprecation warnings and determine if they come from your own scripts or plugins.

For more on this, please refer to https://docs.gradle.org/8.13/userguide/command_line_interface.html#sec:command_line_warnings in the Gradle documentation.

BUILD SUCCESSFUL in 18m 6s
471 actionable tasks: 435 executed, 36 up-to-date
PS C:\Users\user\vscode\braille-translator\android>

빌드 완료 후 다음 경로에서 빌드된 APK를 확인할 수 있습니다.

android/app/build/outputs/apk/release/app-release.apk

참고: Release AAB 빌드하기

Release AAB를 빌드하기 위해선 Release APK 빌드하기 문단에서 Step 2 - Gradle에 서명 정보 추가하기까지 진행한 후 프로젝트 루트에서 다음 명령어를 입력하면 됩니다.

npx react-native build-android --mode=release

빌드 완료 후 다음 경로에서 빌드된 AAB를 확인할 수 있습니다.

android/app/build/outputs/bundle/release/app-release.aab

참고 자료

Front-end

This post is licensed under CC BY 4.0 by the author.