[Flutter] deprecated 경고 발생 시 해결법

Flutter 프로젝트를 클론해서 실행하려고 할 때, 'RaisedButton' is deprecated, 'FlatButton' is deprecated, 또는 pub get failed: Your current Flutter SDK version is incompatible...와 같은 메시지를 본 적이 있다면, 이 글을 주의 깊게 읽어볼 필요가 있습니다.

이 글에서는 이러한 deprecated 경고가 왜 발생하는지, 그리고 이를 어떻게 해결할 수 있는지 Flutter SDK 버전 관리를 중심으로 실용적이고 구체적으로 설명합니다.

왜 deprecated 경고가 발생할까?

Flutter는 굉장히 빠른 주기로 발전하고 있습니다. 새로운 위젯이 추가되거나 기존 API가 변경되는 경우가 많으며, 이 과정에서 기존 위젯들은 @deprecated 처리됩니다.

대표적인 변경 예시

변경 전	변경 후	설명
RaisedButton	ElevatedButton	Flutter 2.0 이후 UI 표준 변경
FlatButton	TextButton	더 명확한 역할 분리
ButtonTheme	ButtonStyle	테마 시스템 개편에 따라 대체됨

이 외에도 Flutter나 Dart SDK 자체의 버전 범위가 달라서 발생하는 경우도 많습니다.

예를 들어, 다음과 같은 경고는 SDK 간 버전 호환 문제가 원인입니다

pub get failed: Your current Flutter SDK version is incompatible with ...

프로젝트에서 요구하는 SDK 버전 확인하기

프로젝트를 클론한 뒤, 아래의 파일들을 확인해보세요.

pubspec.yaml

environment:
  sdk: ">=2.12.0 <3.0.0"

이 설정은 Dart SDK가 2.12.0 이상 3.0.0 미만이기를 요구합니다. Dart SDK 3.x를 사용 중이라면 pub get 자체가 실패할 수 있습니다.

.metadata

version: 2.5.3
channel: stable

Flutter 프로젝트는 대개 .metadata 파일에 작성 당시의 SDK 버전을 명시합니다. 위 예시는 해당 프로젝트가 Flutter 2.5.3에서 개발되었음을 나타냅니다. 현재 사용하는 SDK 버전이 너무 높다면 호환되지 않는 API 때문에 deprecated 경고가 발생합니다.

Flutter SDK 버전 맞추는 방법

FVM(Flutter Version Management) 사용 – 권장

FVM은 프로젝트마다 Flutter SDK 버전을 개별 관리할 수 있게 도와주는 도구입니다. 협업 시에도 일관된 환경을 유지할 수 있습니다.

1) 설치

dart pub global activate fvm

Homebrew를 사용 중이라면

brew tap leoafarias/fvm
brew install fvm

2) 사용 예시

fvm install 2.5.3
fvm use 2.5.3
fvm flutter pub get

이후에는 모든 Flutter 명령어를 fvm flutter로 실행하면 됩니다:

fvm flutter run
fvm flutter build apk

3) 버전 고정

.fvmrc 파일을 프로젝트 루트에 생성하면 버전이 고정됩니다.

2.5.3

FVM을 사용하는 환경에서는 해당 버전으로 자동 전환되므로 매우 편리합니다.

직접 Flutter SDK 다운그레이드 – 보조 방법

FVM을 사용하지 않고 Flutter SDK를 직접 다운그레이드할 수도 있습니다. 다만 전역 환경에 영향을 주므로 신중히 접근해야 합니다.

1) 기존 Flutter 제거

rm -rf ~/flutter

2) 특정 버전 설치

git clone https://github.com/flutter/flutter.git -b stable ~/flutter
cd ~/flutter
git checkout 2.5.3

3) 환경 변수 설정

export PATH="$HOME/flutter/bin:$PATH"
flutter --version

이제 프로젝트에 맞는 Flutter 버전으로 작업할 수 있습니다.

안정적인 Flutter 버전 관리를 위한 팁

항목	설명
.fvmrc	프로젝트별 Flutter 버전을 고정
pubspec.yaml	Dart SDK 범위를 명확히 지정
README.md	사용된 Flutter/Dart 버전을 문서화
CI 환경	FVM 또는 버전 체크 스크립트 사용 권장

협업 또는 팀 프로젝트에서는 위 항목들을 통해 버전 호환 문제를 사전에 방지할 수 있습니다.

결론

Flutter는 빠르게 진화하는 프레임워크이며, 이는 종종 기존 프로젝트를 다시 실행할 때 버전 호환성 문제로 이어집니다. 'RaisedButton' is deprecated 같은 경고는 단순한 오류 메시지가 아니라 버전 불일치의 신호입니다.

이러한 문제를 가장 안전하고 효율적으로 해결하는 방법은 FVM을 도입하여 프로젝트마다 SDK 버전을 고정하는 것입니다. 불필요한 경고 없이, 팀원 모두가 동일한 개발 환경에서 안정적으로 개발할 수 있게 됩니다.

지금 사용하는 Flutter 버전을 점검하고, 클론한 프로젝트에 맞게 맞춰보세요. 작은 습관이 프로젝트의 품질을 지키는 핵심이 됩니다.