[Flutter] Android v1 vs v2 Embedding 차이와 프로젝트마다 다른 이유

Flutter 프로젝트를 만들다 보면 같은 Flutter 버전을 사용하고 있음에도 불구하고,
어떤 프로젝트는 Android v1 embedding, 어떤 프로젝트는 v2 embedding을 사용하는 경우가 있습니다.

왜 이런 일이 생기는 걸까요?
이번 글에서는 Android embedding 방식의 차이와 이러한 차이가 발생하는 원인, 그리고 해결 방법까지 정리해보았습니다.

---

✅ Android embedding v1과 v2의 차이

구분	v1 embedding	v2 embedding
진입점	MainActivity에서 플러그인 수동 등록	FlutterActivity만 상속하면 자동 등록
Flutter 엔진 연결	수동	자동
플러그인 등록 방식	GeneratedPluginRegistrant.registerWith() 호출 필요	자동 연결
지원 상태	Deprecated (더 이상 권장되지 않음)	✅ 현재 표준

---

🤔 같은 Flutter 버전인데 v1과 v2가 나뉘는 이유

1. 프로젝트 생성 시점의 차이

Flutter 버전이 같아도, 프로젝트가 생성된 시점이 다르면 v1 방식이 적용될 수 있습니다.

• 예전에는 기본이 v1이었고
• Flutter 1.12 이후부터 v2 embedding이 기본이 되었기 때문입니다.

2. 기존 프로젝트 유지

Flutter는 기존 프로젝트를 자동으로 v2로 마이그레이션하지 않습니다.
즉, 예전에 만든 프로젝트는 Flutter 버전을 올려도 여전히 v1 구조를 유지합니다.

3. MainActivity 코드 구조에 따른 차이

// 🔻 v1 embedding 예시
public class MainActivity extends FlutterActivity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        GeneratedPluginRegistrant.registerWith(this.getFlutterEngine());
    }
}
// ✅ v2 embedding 예시
public class MainActivity extends FlutterActivity {
    // 비어 있거나, minimal한 구조
}

4. AndroidManifest.xml 내용에 따른 차이

• io.flutter.app.FlutterApplication → v1

• io.flutter.embedding.android.FlutterActivity → v2

이런 차이로도 프로젝트가 어떤 embedding을 쓰고 있는지 판단할 수 있어요.

🛠️ v1 → v2 embedding 마이그레이션 방법

프로젝트를 v2 embedding 구조로 바꾸고 싶다면, 아래 명령어로 마이그레이션이 가능합니다:

flutter create .

현재 프로젝트 디렉토리(.)를 기준으로 새롭게 v2 embedding 구조로 재설정됩니다.

💡 기존 파일은 백업해두는 것을 추천합니다!

🔍 현재 프로젝트가 v1인지 v2인지 확인하는 방법

• android/app/src/main/java/.../MainActivity.java 또는 .kt 파일 확인
• GeneratedPluginRegistrant.registerWith(...) 코드가 있으면 → v1
• 아무런 플러그인 등록 코드 없이 FlutterActivity만 상속하고 있다면 → v2

✅ 결론

• Flutter 버전이 같아도 프로젝트 구조와 생성 시점에 따라 embedding 방식이 다를 수 있다.
• v2 embedding이 표준이며, 새로운 프로젝트는 기본적으로 v2를 사용한다.
• 기존 v1 프로젝트는 flutter create . 명령어로 쉽게 v2로 마이그레이션 가능하다.

참고

공식 문서: Upgrading Android projects to use the V2 embedding