이 글에서 다루는 내용

macOS 환경에서 FVM(Flutter Version Manager)을 이용해 Flutter를 설치하고, Android toolchain 및 Xcode까지 포함한 완전한 Flutter 개발 환경을 구성하는 과정을 다룬다. flutter doctor로 모든 항목이 통과되는 시점까지의 실제 세팅 흐름을 기록한다.

FVM이란?

FVM(Flutter Version Manager)은 Flutter SDK의 버전을 프로젝트별로 독립적으로 관리할 수 있게 해주는 CLI 도구다. 하나의 머신에서 여러 Flutter 버전을 동시에 설치하고, 프로젝트마다 다른 버전을 지정할 수 있다. 글로벌 버전과 프로젝트 로컬 버전을 분리해 관리하기 때문에, 버전 충돌 없이 안정적인 개발 환경을 유지할 수 있다.

FVM 설치 확인

터미널에서 아래 명령어로 FVM이 이미 설치되어 있는지 확인한다.

fvm --version

설치가 안 되어 있다면 Homebrew로 설치한다.

brew tap leoafarias/fvm
brew install fvm

Flutter 버전 설치 및 글로벌 설정

FVM을 통해 stable 채널의 Flutter를 설치하고 글로벌 버전으로 지정한다.

fvm install stable
fvm global stable

설치된 버전 목록은 아래 명령어로 확인할 수 있다.

fvm list

PATH 설정

FVM으로 설치한 Flutter를 flutter 명령어로 바로 사용하려면 ~/.zshrc에 PATH를 추가해야 한다.

echo 'export PATH="$HOME/fvm/default/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

적용 후 확인:

flutter --version

flutter doctor로 개발 환경 점검

flutter doctor

각 항목이 ✅ 인지 확인한다. 문제가 있는 항목만 골라서 해결하면 된다.

Android toolchain 설정

flutter doctor 실행 시 Android toolchain 항목에 아래와 같은 오류가 발생할 수 있다.

✗ cmdline-tools component is missing.
✗ Android license status unknown.

cmdline-tools 설치

Android Studio를 실행하고 아래 경로에서 설치한다.

Tools > SDK Manager > SDK Tools 탭
→ "Android SDK Command-line Tools (latest)" 체크
→ Apply → OK

Android 라이선스 동의

flutter doctor --android-licenses

모든 항목에 y를 입력해 라이선스에 동의한다.

최종 확인

모든 설정이 완료된 후 flutter doctor를 다시 실행해 전체 항목이 통과되는지 확인한다.

flutter doctor

아래와 같이 출력되면 성공이다.

[✓] Flutter
[✓] Android toolchain
[✓] Xcode
[✓] Chrome
[✓] Connected device
[✓] Network resources

• No issues found!

Flutter 최신 버전으로 업그레이드

이미 stable이 설치된 상태에서 최신 버전으로 업그레이드할 때는 아래 명령어를 사용한다.

fvm flutter upgrade

처음부터 새로 설치할 때는 아래 순서로 진행한다.

fvm install stable
fvm global stable

자주 사용하는 FVM 명령어

명령어 설명
fvm --version FVM 버전 확인
fvm list 설치된 Flutter 버전 목록 확인
fvm releases 설치 가능한 Flutter 버전 전체 목록
fvm install stable stable 채널 최신 Flutter 설치
fvm install 3.24.0 특정 버전 설치
fvm global stable 글로벌 기본 버전 지정
fvm use 3.24.0 현재 프로젝트에 특정 버전 지정
fvm flutter upgrade 현재 버전을 최신으로 업그레이드
fvm flutter --version FVM을 통한 flutter 버전 확인

자주 사용하는 Flutter 명령어

명령어 설명
flutter --version Flutter 버전 확인
flutter doctor 개발 환경 전체 점검
flutter doctor -v 점검 결과 상세 출력
flutter doctor --android-licenses Android 라이선스 동의
flutter create 프로젝트명 새 Flutter 프로젝트 생성
flutter run 앱 실행
flutter build apk Android APK 빌드
flutter build ios iOS 빌드
flutter pub get 패키지 의존성 설치
flutter pub upgrade 패키지 업그레이드
flutter clean 빌드 캐시 초기화
flutter devices 연결된 디바이스 목록 확인
flutter upgrade Flutter SDK 업그레이드