빌드와 배포

개발 중 flutter run은 핫 리로드가 되는 디버그 모드로 실행됩니다. 배포할 때는 릴리스 모드로 빌드해야 하며, 이때 Dart 코드가 기계어(웹은 JavaScript 또는 WebAssembly)로 미리 컴파일되어 크기가 작아지고 속도가 빨라집니다. 이 장에서는 플랫폼별 빌드 명령, 버전 관리, 서명, 스토어 출시 과정을 정리합니다.

플랫폼별 빌드 명령

flutter build는 기본이 릴리스 모드이며, 결과물은 build 폴더 아래 플랫폼별 위치에 만들어집니다. 각 플랫폼은 해당 운영체제에서 빌드해야 합니다(iOS·macOS는 macOS, Windows는 Windows).

# Android: Play 스토어용 App Bundle
flutter build appbundle

# Android: ABI별로 나눈 APK(파일 크기 감소)
flutter build apk --split-per-abi

# 웹: 하위 경로에 배포할 때
flutter build web --base-href /myapp/

# 릴리스 모드로 기기에서 직접 확인
flutter run --release

버전 번호

앱 버전은 pubspec.yaml의 version 한 곳에서 관리합니다. 1.2.0+5라면 사용자에게 보이는 버전 이름은 1.2.0, 스토어가 구분하는 빌드 번호는 5입니다. 스토어에 새 빌드를 올릴 때마다 빌드 번호를 올려야 하며, 빌드할 때 명령으로 덮어쓸 수도 있습니다.

flutter build appbundle --build-name=1.2.1 --build-number=6

Android 서명

Google Play에 올리려면 업로드 키로 서명해야 합니다. 먼저 키 저장소를 만듭니다(Java의 keytool 사용).

keytool -genkey -v -keystore ~/upload-keystore.jks -keyalg RSA \
  -keysize 2048 -validity 10000 -alias upload

android/key.properties 파일에 비밀번호와 경로를 적고, 이 파일과 키 저장소는 버전 관리에 넣지 않습니다. 그리고 android/app/build.gradle.kts에서 이 값을 읽어 릴리스 빌드에 서명 설정을 연결합니다.

import java.io.FileInputStream
import java.util.Properties

val keystoreProperties = Properties()
val keystorePropertiesFile = rootProject.file("key.properties")
if (keystorePropertiesFile.exists()) {
    keystoreProperties.load(FileInputStream(keystorePropertiesFile))
}

android {
    // ...
    signingConfigs {
        create("release") {
            keyAlias = keystoreProperties["keyAlias"] as String
            keyPassword = keystoreProperties["keyPassword"] as String
            storeFile = keystoreProperties["storeFile"]?.let { file(it) }
            storePassword = keystoreProperties["storePassword"] as String
        }
    }
    buildTypes {
        release {
            signingConfig = signingConfigs.getByName("release")
        }
    }
}

Play Console에서 Play 앱 서명을 쓰면 Google이 실제 배포용 키를 보관하고, 개발자는 업로드 키만 관리합니다. 출시 전에 applicationId(패키지 이름), 앱 이름, 아이콘, 필요한 권한을 확인합니다.

iOS 출시

iOS 앱을 App Store에 올리려면 Apple Developer Program 가입이 필요합니다.

1. App Store Connect에서 앱을 등록하고 번들 식별자를 정합니다.
2. Xcode에서 ios/Runner.xcworkspace를 열고 Signing & Capabilities에서 팀과 번들 식별자를 설정합니다.
3. flutter build ipa로 빌드합니다. 결과는 build/ios/ipa와 build/ios/archive에 생깁니다.
4. Apple의 Transporter 앱이나 Xcode Organizer로 빌드를 업로드하고, TestFlight로 시험한 뒤 심사에 제출합니다.

웹과 데스크톱

웹 빌드 결과 build/web은 정적 파일이므로 Firebase Hosting, GitHub Pages, Nginx 같은 정적 호스팅에 그대로 올리면 됩니다. 앱 내부 경로를 쓴다면 모든 경로가 index.html을 돌려주도록 서버를 설정합니다.

Windows 빌드 결과는 build/windows/x64/runner/Release 폴더에 있으며, 실행 파일과 함께 있는 DLL과 data 폴더를 모두 같이 배포해야 합니다. Microsoft Store용 MSIX 패키지는 msix 패키지로 만들 수 있습니다. macOS 앱은 Xcode로 서명하고 공증(notarization)을 거쳐 배포합니다.

코드 난독화와 출시 점검

Android·iOS·데스크톱 릴리스 빌드에서는 Dart 코드를 난독화할 수 있습니다. 이때 생기는 기호 파일은 오류 보고서를 읽을 때 필요하므로 잘 보관합니다.

flutter build appbundle --obfuscate --split-debug-info=build/symbols

출시 전에는 다음을 확인합니다.

• 릴리스 모드(flutter run --release)로 실제 기기에서 성능과 동작 확인
• 앱 아이콘과 시작 화면(flutter_launcher_icons 같은 패키지가 편리합니다)
• 개인정보 처리방침, 스토어 설명, 스크린샷, 연령 등급 등 스토어 등록 정보
• flutter analyze와 flutter test가 모두 통과하는지

정리

• 배포는 flutter build <대상>으로 릴리스 빌드를 만들어 진행합니다.
• 버전은 pubspec.yaml의 version(이름+빌드 번호)으로 관리합니다.
• Android는 업로드 키로 서명한 App Bundle을, iOS는 Xcode 서명 설정 후 flutter build ipa로 만든 빌드를 올립니다.
• 웹은 정적 호스팅, 데스크톱은 빌드 폴더 전체를 묶어 배포합니다.

공식 문서에서 더 자세히 알아보세요.

• Build and release an Android app
• Build and release an iOS app
• Build and release a web app
• Build and release a Windows desktop app
• Build and release a macOS app
• Build and release a Linux app
• Obfuscate Dart code