Computer >> 컴퓨터 >  >> 시스템 >> Android

Flutter 튜토리얼: 최신 V2 Android 임베딩으로 앱 마이그레이션하는 방법

Flutter 초창기부터 개발을 시작하셨다면, Flutter 1.12 버전 이전에 생성된 프로젝트가 한두 개 있을 가능성이 높습니다. 그렇다면 프로젝트에서 pub get을 실행할 때마다 아래와 같은 메시지를 마주한 경험이 있으실 겁니다.

"이 앱은 지원이 중단된(deprecated) 버전의 Android 임베딩을 사용하고 있습니다. 예기치 않은 런타임 오류나 향후 빌드 실패를 방지하려면 V2 임베딩으로 마이그레이션하세요."

공식 문서에도 마이그레이션 절차가 정리되어 있지만, 무엇을 어디서 어떻게 수정해야 하는지 구체적으로 설명하지 않는 경우가 많습니다.

이 글에서는 Flutter 애플리케이션을 V2 임베딩으로 마이그레이션하는 과정을 단계별로 자세히 안내해 드립니다. 이 가이드를 따라 하면 해당 경고를 완전히 없앨 수 있습니다.

자동 마이그레이션 – 가장 쉬운 방법

먼저 짚고 넘어갈 부분이 있습니다. 애플리케이션을 비교적 쉽게 새로 만들 수 있다면 굳이 마이그레이션 작업을 진행할 필요가 없습니다.

앱의 코드가 복잡하지 않다면 lib 폴더의 파일들을 백업한 뒤, flutter create 명령어로 새 프로젝트를 생성하는 방법을 추천합니다. 이렇게 하면 처음부터 V2 임베딩이 적용된 프로젝트가 만들어지므로, 기존 lib 폴더의 코드만 옮겨 붙여 넣으면 됩니다.

반면 프로젝트가 복잡한 경우, 예를 들어 플랫폼별 네이티브 코드를 포함하는 패키지라면 수동 마이그레이션이 더 안전한 선택입니다.

수동 마이그레이션 – 단계별 가이드

  1. 애플리케이션의 MainActivity.kt(또는 .java) 파일을 엽니다.
  2. 특별한 로직이 담겨 있지 않다면 파일 내용을 모두 제거하고 클래스 선언만 남겨둡니다.
  3. 모든 import 문을 삭제하고 아래 import 하나만 남깁니다.
import io.flutter.embedding.android.FlutterActivity;

최종 결과는 다음과 같아야 합니다.

import io.flutter.embedding.android.FlutterActivity;public class MainActivity extends FlutterActivity { // 여기에는 아무 내용도 없어야 합니다}
  1. AndroidManifest.xml 파일을 열고 application 태그 아래의 name 속성을 ${applicationName}으로 변경합니다.
<application android:name="${applicationName}"> ....</application>
  1. application 태그 내부에 다음 meta-data를 추가합니다.
<meta-data android:name="flutterEmbedding" android:value="2" />
  1. 특정 스플래시 화면 동작을 원한다면 기존 스플래시 관련 meta 태그를 제거합니다.
<meta-data android:name="io.flutter.app.android.SplashScreenUntilFirstFrame" android:value="true" />
  1. 이후 styles.xml 파일로 이동하여 LaunchTheme에 원하는 drawable을 설정합니다.
<?xml version="1.0" encoding="utf-8"?><resources> <style name="LaunchTheme" parent="@android:style/Theme.Black.NoTitleBar"> <item name="android:windowBackground">@drawable/launch_background</item> </style></resources>

위 변경 사항을 모두 적용하면 AndroidManifest.xml은 대략 다음과 같은 형태가 됩니다.

<manifest xmlns:android="https://schemas.android.com/apk/res/android" package="PACKAGE_NAME"><application android:name="${applicationName}" android:label="APPLICATION_LABEL" android:icon="@mipmap/ic_launcher"> <activity android:name=".MainActivity" android:exported="true" android:launchMode="singleTop" android:theme="@style/LaunchTheme" android:configChanges="orientation|keyboardHidden|keyboard|screenSize|locale|layoutDirection|fontScale|screenLayout|density|uiMode" android:hardwareAccelerated="true" android:windowSoftInputMode="adjustResize"> <intent-filter> <action android:name="android.intent.action.MAIN"/> <category android:name="android.intent.category.LAUNCHER"/> </intent-filter> </activity> <meta-data android:name="flutterEmbedding" android:value="2" /> </application></manifest>

AndroidX 지원

프로젝트에 따라서는 기존 서포트 라이브러리(support library) 대신 AndroidX 라이브러리를 사용하도록 전환해야 할 수도 있습니다. 이 경우 앱을 빌드하고 실행할 때 다음과 같은 알림이 표시됩니다.

"Your app isn't using AndroidX. To avoid potential build failures, you can quickly migrate your app by following the steps on https://goo.gl/CP92wY."

다행히 해결 방법은 간단합니다. Android Studio에는 AndroidX 마이그레이션 기능이 기본으로 내장되어 있습니다.

먼저 Flutter 애플리케이션의 Android 폴더를 독립형 프로젝트로 엽니다.

그런 다음 Refactor → Migrate to AndroidX 메뉴를 클릭합니다.

Flutter 튜토리얼: 최신 V2 Android 임베딩으로 앱 마이그레이션하는 방법AndroidX로 마이그레이션하는 드롭다운 메뉴

프로젝트 백업본 저장 여부를 묻는 프롬프트가 표시되며, 이후 마이그레이션 프로세스가 자동으로 진행됩니다.

마이그레이션 중 발생할 수 있는 오류

마이그레이션 과정에서 앱을 빌드할 때 몇 가지 오류가 발생할 수 있습니다. 대표적인 오류는 다음과 같습니다.

  • Unable to get mutable Windows environment variable map
  • cvc-complex-type.2.4.a: Invalid content was found starting with element 'base-extension'. One of '{layoutlib}' is expected
  • Warning: This version only understands SDK XML versions up to 2 but an SDK XML file of version 3 was encountered. This can happen if you use versions of Android Studio and the command-line tools that were released at different times

첫 번째와 두 번째 오류는 서로 연관되어 있으며, 근본 원인도 동일합니다. 프로젝트가 오래된 Gradle 버전으로 설정되어 있기 때문이며, 이를 업그레이드해야 합니다.

Gradle을 업그레이드하려면 다음 단계를 따르세요.

  1. Flutter 애플리케이션의 Android 폴더를 독립형 프로젝트로 엽니다.
  2. File → Project Structure 메뉴를 클릭합니다.

Flutter 튜토리얼: 최신 V2 Android 임베딩으로 앱 마이그레이션하는 방법Project Structure 선택 드롭다운 메뉴

  1. Gradle 버전을 현재 사용 중인 Android Studio 버전과 호환되는 최신 버전으로 변경합니다.

Flutter 튜토리얼: 최신 V2 Android 임베딩으로 앱 마이그레이션하는 방법AGP 및 Gradle 설정 화면

또는 Tools → AGP Upgrade Assistant 메뉴를 통해 AGP Upgrade Assistant를 사용할 수도 있습니다.

Flutter 튜토리얼: 최신 V2 Android 임베딩으로 앱 마이그레이션하는 방법AGP Upgrade Assistant로 업그레이드하는 드롭다운 메뉴

세 번째 항목은 경고(warning)인데, 주로 구버전의 Android SDK Tools를 사용할 때 발생합니다. 해결 방법은 공식 문서를 참고해 SDK Tools를 최신 버전으로 업데이트하면 됩니다.

여기까지 완료했다면 프로젝트가 성공적으로 마이그레이션되어 문제없이 컴파일되고 실행될 것입니다.

freeCodeCamp의 오픈소스 커리큘럼은 이미 40,000명 이상의 사람들이 개발자로 취업하는 데 도움을 주었습니다. 지금 바로 무료로 코딩 학습을 시작해 보세요.