Flutter 캐시 제거 및 실행

Flutter 프로젝트에서 빌드 오류가 계속 발생하거나, 패키지 변경 후에도 이전 설정이 남아 있는 것처럼 보일 때 캐시를 정리해야 할 수 있다.

특히 Windows Desktop, Android, Firebase, CMake 관련 오류가 계속 남아 있을 때 빌드 캐시를 삭제하면 해결되는 경우가 있다.

캐시 정리가 필요한 상황
- 패키지를 업데이트했는데 이전 오류가 계속 발생할 때
- Windows Desktop 빌드 오류가 반복될 때
- Firebase 관련 native 빌드 오류가 남아 있을 때
- CMake 설정을 수정했는데 반영되지 않을 때
- Android / Windows 빌드 결과물이 꼬였을 때

---

1. Flutter 기본 캐시 정리

가장 먼저 실행하는 명령어는 flutter clean이다.

flutter clean

flutter clean은 Flutter가 생성한 기본 빌드 결과물을 정리한다.

flutter clean
- Flutter 기본 빌드 캐시 삭제
- build 폴더 일부 정리
- 이전 빌드 결과물 제거

보통 패키지를 변경하거나 빌드 설정을 수정한 뒤 문제가 생기면 먼저 실행한다.

---

2. build 폴더 완전 삭제

build 폴더는 Android, Windows 등 빌드 결과물이 저장되는 폴더다.

PowerShell에서는 다음 명령어로 삭제할 수 있다.

Remove-Item -Recurse -Force .\build

역할은 다음과 같다.

.\build
- Android 빌드 결과물
- Windows 빌드 결과물
- 임시 컴파일 결과물
- 이전 빌드 캐시

flutter clean 후에도 문제가 남아 있다면 build 폴더를 직접 삭제해볼 수 있다.

---

3. .dart_tool 폴더 삭제

.dart_tool 폴더에는 Dart와 Flutter 패키지 설정 정보가 저장된다.

PowerShell에서는 다음 명령어로 삭제한다.

Remove-Item -Recurse -Force .\.dart_tool

.dart_tool을 삭제하면 패키지 설정과 빌드 관련 메타데이터가 다시 생성된다.

.dart_tool
- Dart 패키지 설정 캐시
- Flutter 빌드 메타데이터
- package_config.json
- 빌드 도구가 사용하는 임시 설정

삭제 후에는 반드시 flutter pub get을 다시 실행해야 한다.

---

4. Windows Desktop ephemeral 폴더 삭제

Windows Desktop 빌드에서는 windows/flutter/ephemeral 폴더가 생성된다.

이 폴더에는 Windows Desktop 빌드에 필요한 임시 파일들이 들어 있다.

Remove-Item -Recurse -Force .\windows\flutter\ephemeral

역할은 다음과 같다.

windows/flutter/ephemeral
- Windows Desktop 빌드 임시 파일
- Flutter Windows engine 관련 파일
- CMake 빌드 보조 파일
- 자동 생성되는 파일

Windows Desktop 빌드에서 CMake, Visual Studio, Firebase native 관련 오류가 계속 남아 있다면 이 폴더를 삭제하는 것이 도움이 될 수 있다.

이 폴더는 다시 빌드하면 자동으로 생성된다.

---

5. 패키지 다시 받기

캐시와 빌드 파일을 삭제한 뒤에는 패키지를 다시 받아야 한다.

flutter pub get

flutter pub get은 pubspec.yaml을 기준으로 필요한 패키지를 다시 설치하고 설정 파일을 생성한다.

flutter pub get
- pubspec.yaml 기준으로 패키지 다시 받기
- .dart_tool 재생성
- package_config.json 재생성
- 의존성 설정 갱신

---

6. 캐시 제거 전체 순서

PowerShell 기준으로 전체 정리 순서는 다음과 같다.

flutter clean

Remove-Item -Recurse -Force .\build
Remove-Item -Recurse -Force .\.dart_tool
Remove-Item -Recurse -Force .\windows\flutter\ephemeral

flutter pub get

흐름은 다음과 같다.

flutter clean
   |
   v
build 폴더 삭제
   |
   v
.dart_tool 폴더 삭제
   |
   v
windows/flutter/ephemeral 삭제
   |
   v
flutter pub get
   |
   v
패키지와 설정 다시 생성

만약 특정 폴더가 없다는 메시지가 나와도 문제는 아니다.

아직 생성되지 않았거나 이미 삭제된 상태일 수 있다.

---

7. Windows Desktop 실행하기

Windows Desktop 앱을 실행하려면 다음 명령어를 사용한다.

flutter run -d windows

이 명령어는 Flutter 앱을 Windows 데스크톱 대상으로 실행한다.

flutter run -d windows
- Windows Desktop 앱 실행
- CMake 빌드 수행
- Visual Studio / MSVC로 native 코드 컴파일

Windows Desktop 빌드 오류를 확인할 때 자주 사용하는 명령어다.

---

8. 모바일 기기 확인하기

연결된 모바일 기기나 에뮬레이터를 확인하려면 다음 명령어를 사용한다.

flutter devices

출력 예시는 다음과 같다.

Found 2 connected devices:
SM-G991N (mobile) • R5CT123456A • android-arm64 • Android 14
Windows (desktop) • windows     • windows-x64   • Microsoft Windows

여기서 모바일 기기 ID를 확인한다.

예시 모바일 기기 ID
R5CT123456A

---

9. 모바일 기기로 실행하기

모바일 기기 ID를 확인한 뒤 다음처럼 실행할 수 있다.

flutter run -d R5CT123456A

형식은 다음과 같다.

flutter run -d 모바일기기ID

예를 들어 Android 에뮬레이터라면 다음처럼 보일 수 있다.

flutter run -d emulator-5554

실행 흐름은 다음과 같다.

flutter devices
   |
   v
모바일 기기 ID 확인
   |
   v
flutter run -d 모바일기기ID
   |
   v
해당 기기로 앱 실행

---

10. 자주 쓰는 명령어 모음

캐시 제거와 실행 명령어를 한 번에 정리하면 다음과 같다.

캐시 제거

flutter clean

Remove-Item -Recurse -Force .\build
Remove-Item -Recurse -Force .\.dart_tool
Remove-Item -Recurse -Force .\windows\flutter\ephemeral

flutter pub get

Windows Desktop 실행

flutter run -d windows

연결된 기기 확인

flutter devices

모바일 기기로 실행

flutter run -d 모바일기기ID

---

11. 정리

Flutter에서 빌드 오류가 계속 남아 있을 때는 캐시와 임시 빌드 파일을 정리한 뒤 다시 패키지를 받아보는 것이 좋다.

핵심 명령어는 다음과 같다.

flutter clean
- Flutter 기본 빌드 정리

Remove-Item .\build
- Android / Windows 빌드 결과물 완전 삭제

Remove-Item .\.dart_tool
- Dart / Flutter 패키지 설정 캐시 삭제

Remove-Item .\windows\flutter\ephemeral
- Windows Desktop 빌드 임시 파일 삭제

flutter pub get
- 패키지와 설정 다시 생성

실행 명령어는 다음과 같다.

Windows Desktop 실행
-> flutter run -d windows

모바일 기기 확인
-> flutter devices

모바일 실행
-> flutter run -d 모바일기기ID

즉, Windows Desktop 빌드가 꼬였을 때는 다음 순서로 정리하면 된다.

flutter clean

Remove-Item -Recurse -Force .\build
Remove-Item -Recurse -Force .\.dart_tool
Remove-Item -Recurse -Force .\windows\flutter\ephemeral

flutter pub get
flutter run -d windows