Flutter Desktop Error 정리

Flutter Desktop을 Windows 환경에서 개발하면서 발생한 에러와 해결 방법을 정리한다.

Android 앱 개발에서는 Gradle, Android SDK, Kotlin/Java 관련 에러를 주로 만나지만,
Flutter Windows Desktop에서는 CMake, Visual Studio, MSVC, Windows native plugin 관련 에러도 자주 발생할 수 있다.

이 글은 Flutter Desktop 개발 중 만난 에러를 하나씩 추가하면서,
나중에 같은 문제가 발생했을 때 빠르게 확인하기 위한 기록용 글이다.

정리 방식은 다음과 같다.

에러 메시지
   |
   v
발생 상황
   |
   v
원인
   |
   v
해결 방법
   |
   v
정리

Flutter Windows Desktop 빌드에는 다음 도구들이 함께 사용된다.

Flutter
- 앱 빌드 실행

CMake
- Windows Desktop 빌드 설정 처리

Visual Studio / MSVC
- C++ 코드 컴파일

Flutter Plugin
- Windows native 코드 포함

Firebase Plugin
- Firebase 관련 native 코드 포함

그래서 에러가 발생했을 때 Flutter 코드만 볼 것이 아니라,
CMake 설정, Visual Studio 빌드 환경, 패키지 버전, 인코딩 문제도 함께 확인해야 한다.

---

1. CMake VERSION / Policy 관련 에러

에러 메시지

Update the VERSION argument <min> value.

Or, use the <min>...<max> syntax to tell CMake that the project requires at least <min>
but has been updated to work with policies introduced by <max> or earlier.

Or, add -DCMAKE_POLICY_VERSION_MINIMUM=3.5 to try configuring anyway.

발생 상황

Flutter Windows Desktop 앱을 실행하거나 빌드할 때 발생할 수 있다.

flutter run -d windows

또는 다음 명령어 실행 중 발생할 수 있다.

flutter build windows

원인

이 에러는 CMake 버전이 낮아서 발생하는 문제가 아닐 수 있다.

오히려 PC에 설치된 CMake는 최신인데, 프로젝트나 플러그인에 포함된 CMakeLists.txt가 오래된 CMake 정책을 기준으로 작성되어 있을 때 발생할 수 있다.

현재 PC의 CMake
- 최신 버전

프로젝트 또는 플러그인 CMake 설정
- 오래된 최소 버전 기준

결과
- CMake 정책 버전 충돌 발생

Flutter Desktop에서는 Windows native 코드, Flutter Plugin, Firebase Plugin 등이 CMake 빌드에 포함될 수 있다.

그래서 Dart 코드가 아니라 CMake 정책 문제로 빌드가 실패할 수 있다.

해결 방법

windows/CMakeLists.txt 파일에 CMake Policy 최소 버전을 지정한다.

수정할 파일
windows/CMakeLists.txt

파일 상단 근처에 다음 코드를 추가한다.

set(CMAKE_POLICY_VERSION_MINIMUM 3.5 CACHE STRING "Minimum CMake policy version" FORCE)

이 코드는 CMake에게 최소 정책 버전을 지정해서 오래된 CMake 설정과 최신 CMake 사이의 충돌을 완화하는 역할을 한다.

정리

에러 원인
- 최신 CMake와 오래된 CMake 설정 간 정책 충돌

수정 파일
- windows/CMakeLists.txt

해결 방법
- CMAKE_POLICY_VERSION_MINIMUM 설정 추가

---

2. std::variant 오버로드 관련 에러

에러 메시지

::variant': 모든 인수 형식을 변환할 수 있는 오버로드된 함수가 없습니다.

또는 Visual Studio 빌드 과정에서 std::variant 관련 C++ 컴파일 에러가 발생할 수 있다.

발생 상황

Flutter Windows Desktop 빌드 중 MSVC가 C++ native 코드를 컴파일할 때 발생할 수 있다.

flutter run -d windows

또는 다음 명령어 실행 중 발생할 수 있다.

flutter build windows

특히 Firebase 관련 패키지를 사용할 때 발생할 수 있다.

발생 가능 상황
- firebase_core 사용
- firebase_auth 사용
- cloud_firestore 사용
- Flutter Windows Desktop 빌드
- Visual Studio / MSVC 컴파일 과정

원인

이 에러는 Dart 코드 문제라기보다는 Flutter Desktop 빌드 환경과 플러그인 버전이 맞지 않아서 발생할 수 있다.

특히 Firebase 플러그인과 Flutter SDK, Windows native 빌드 환경 사이에서 버전 충돌이 생기면 C++ 컴파일 에러가 발생할 수 있다.

가능한 원인

Firebase 패키지 버전이 오래됨
   |
   v
Flutter SDK 버전과 맞지 않음
   |
   v
Windows native 코드 생성 또는 컴파일 과정에서 충돌
   |
   v
std::variant 관련 에러 발생

또는 pubspec.lock에 오래된 의존성 버전이 고정되어 있어서 문제가 계속될 수 있다.

해결 방법

먼저 패키지를 현재 Flutter 환경에 맞는 버전으로 업데이트한다.

flutter pub upgrade

그다음 기존 빌드 결과를 정리하고 다시 실행한다.

flutter clean
flutter pub get
flutter run -d windows

문제가 계속되면 다음 순서로 실행해볼 수 있다.

flutter clean
flutter pub get
flutter pub upgrade
flutter run -d windows

Firebase 관련 패키지를 사용 중이라면 pubspec.yaml의 Firebase 패키지 버전도 확인한다.

dependencies:
  firebase_core: 최신 호환 버전
  firebase_auth: 최신 호환 버전
  cloud_firestore: 최신 호환 버전

단, 무조건 최신 버전이 항상 정답은 아니다.

현재 Flutter SDK 버전과 호환되는 Firebase 패키지 버전을 사용하는 것이 중요하다.

정리

에러 원인
- Firebase Plugin과 Flutter Desktop 빌드 환경 간 버전 충돌 가능성
- pubspec.lock에 오래된 의존성 버전이 남아 있을 수 있음

해결 방법
- flutter pub upgrade 실행
- flutter clean 후 다시 빌드
- Firebase 관련 패키지 버전 확인

---

3. C4819 인코딩 관련 에러

에러 메시지

C4819: 현재 코드 페이지(949)에서 표시할 수 없는 문자가 파일에 들어 있습니다.
데이터가 손실되지 않게 하려면 해당 파일을 유니코드 형식으로 저장하십시오.

발생 상황

Flutter Windows Desktop 빌드 중 Visual Studio C++ 컴파일러인 MSVC가 소스 파일을 읽는 과정에서 발생할 수 있다.

flutter run -d windows

또는 다음 명령어 실행 중 발생할 수 있다.

flutter build windows

원인

한국어 Windows 환경에서는 기본 코드 페이지가 949인 경우가 많다.

그런데 빌드 대상 파일이 UTF-8 문자나 한글, 특수 문자를 포함하고 있으면 MSVC가 파일을 제대로 해석하지 못할 수 있다.

Windows 기본 코드 페이지
   |
   v
MSVC가 949 기준으로 파일 읽기
   |
   v
파일 안에 UTF-8 문자 또는 해석 불가능한 문자 존재
   |
   v
C4819 에러 발생

즉, 코드 로직 문제가 아니라 파일 인코딩 해석 문제다.

해결 방법

MSVC가 소스 파일을 UTF-8로 읽도록 CMake 옵션을 추가한다.

수정할 파일은 보통 다음 위치에 있다.

windows/CMakeLists.txt

CMakeLists.txt에 다음 코드를 추가한다.

add_compile_options("$<$<CXX_COMPILER_ID:MSVC>:/utf-8>")
add_compile_options("$<$<C_COMPILER_ID:MSVC>:/utf-8>")

각 옵션의 의미는 다음과 같다.

CXX_COMPILER_ID:MSVC
- C++ 컴파일러가 MSVC일 때 적용

C_COMPILER_ID:MSVC
- C 컴파일러가 MSVC일 때 적용

/utf-8
- 소스 파일을 UTF-8로 해석

정리

에러 원인
- MSVC가 파일을 현재 코드 페이지 949 기준으로 읽으면서 발생
- UTF-8 문자 또는 한글 문자를 제대로 해석하지 못함

수정 파일
- windows/CMakeLists.txt

해결 방법
- MSVC /utf-8 컴파일 옵션 추가

---

4. CMakeLists.txt 적용 예시

CMake 정책 에러와 C4819 인코딩 에러를 함께 해결하려면 windows/CMakeLists.txt에 다음 코드를 추가할 수 있다.

set(CMAKE_POLICY_VERSION_MINIMUM 3.5 CACHE STRING "Minimum CMake policy version" FORCE)

add_compile_options("$<$<CXX_COMPILER_ID:MSVC>:/utf-8>")
add_compile_options("$<$<C_COMPILER_ID:MSVC>:/utf-8>")

각 설정의 역할은 다음과 같다.

CMAKE_POLICY_VERSION_MINIMUM
- CMake 정책 버전 문제 완화

CXX_COMPILER_ID:MSVC /utf-8
- C++ 파일을 UTF-8로 컴파일

C_COMPILER_ID:MSVC /utf-8
- C 파일을 UTF-8로 컴파일

적용 흐름은 다음과 같다.

windows/CMakeLists.txt 열기
   |
   v
CMAKE_POLICY_VERSION_MINIMUM 추가
   |
   v
MSVC /utf-8 옵션 추가
   |
   v
flutter clean
   |
   v
flutter pub get
   |
   v
flutter run -d windows

---

5. 패키지 업데이트 및 재빌드

Firebase와 Flutter Desktop 빌드 환경 간 버전 충돌이 의심된다면 패키지를 업데이트하고 다시 빌드한다.

flutter pub upgrade

문제가 계속된다면 다음 순서로 실행한다.

flutter clean
flutter pub get
flutter pub upgrade
flutter run -d windows

각 명령어의 의미는 다음과 같다.

flutter clean
- 기존 빌드 결과와 캐시 정리

flutter pub get
- pubspec.yaml 기준으로 패키지 다시 받기

flutter pub upgrade
- 가능한 범위 안에서 패키지 버전 업데이트

flutter run -d windows
- Windows Desktop 앱 실행

Windows 앱을 실행하지 않고 빌드만 하고 싶다면 다음 명령어를 사용할 수 있다.

flutter build windows