플러터

flutter run -d emulator-5554

📱 플러터(Flutter) 디바이스 및 실행 관련 필수 CLI 명령어

플러터 개발 시 터미널에서 가장 자주 사용하게 되는 핵심 CLI 명령어들을 정리해 드립니다. 특히 모바일 플랫폼의 네이티브 SDK 설정이나 빌드 환경을 다루실 때 유용한 명령어들도 함께 포함했습니다.

1. 기기(Device) 및 에뮬레이터 확인

• flutter devices
  현재 PC에 연결되어 앱을 실행할 수 있는 모든 물리 기기, 시뮬레이터, 웹 브라우저 등의 목록과 각 기기의 고유 ID를 출력합니다.
• flutter emulators
  실행 가능한 에뮬레이터(Android) 및 시뮬레이터(iOS) 목록을 확인합니다.
• flutter emulators --launch <에뮬레이터_ID>
  IDE를 켜지 않고 터미널에서 특정 에뮬레이터를 즉시 실행합니다. (예: flutter emulators --launch apple_ios_simulator)

2. 앱 실행 (Run)

• flutter run
  기본적으로 연결된 기기에서 앱을 디버그 모드로 실행합니다. 연결된 기기가 여러 대일 경우 어떤 기기에서 실행할지 선택하는 프롬프트가 나타납니다.
• flutter run -d <기기_ID>
flutter devices로 확인한 특정 기기의 ID를 지정하여 앱을 실행합니다. (예: flutter run -d chrome 또는 flutter run -d R3CW10XXXXX)
• flutter run --release
  앱을 릴리즈 모드로 실행합니다. 앱의 실제 성능을 측정하거나, 디버그 모드에서는 잡히지 않는 네이티브 통합 관련 이슈를 실제 배포 환경과 동일하게 테스트할 때 사용합니다.
• flutter run -t <파일_경로>
  기본 진입점인 lib/main.dart 대신 다른 파일을 진입점으로 지정하여 실행합니다. (예: flutter run -t lib/main_dev.dart)

3. 캐시 삭제 및 패키지 관리 (Clean & Pub)

네이티브 SDK를 추가하거나, Android/iOS 폴더 내의 네이티브 설정(예: SHA-1 키 등록, 소셜 로그인 연동 설정 등)을 변경한 후 원인 모를 빌드 에러가 발생할 때 가장 먼저 실행해야 하는 명령어들입니다.

• flutter clean
  프로젝트의 build/ 디렉토리와 빌드 캐시를 완전히 삭제합니다. 네이티브 단의 설정 변경사항이 꼬였을 때 환경을 초기화하는 역할을 합니다.
• flutter pub get
pubspec.yaml 파일에 정의된 의존성 패키지들을 다운로드합니다. 보통 flutter clean 이후에 세트로 실행합니다.
• flutter pub upgrade
pubspec.yaml의 버전 제약 조건 내에서 패키지들을 최신 버전으로 업데이트합니다.

4. 개발 환경 진단 (Doctor)

• flutter doctor
  현재 플러터 SDK, Android Studio, Xcode 버전 및 연결된 기기 상태 등 전반적인 개발 환경에 문제가 없는지 체크합니다.
• flutter doctor -v (또는 --verbose)
  환경 정보를 훨씬 더 상세하게 출력합니다. 네이티브 빌드 툴체인의 경로 문제나 특정 버전을 짚어내야 하는 복잡한 트러블슈팅 상황에서 유용합니다.

---

💡 실행 중 유용한 터미널 단축키

flutter run 명령어로 앱을 실행한 후, 해당 터미널 창에서 바로 입력하여 사용할 수 있는 단축키입니다.

• r (Hot Reload): 앱의 현재 상태(State)를 유지하면서 변경된 UI 코드만 빠르게 반영합니다.
• R (Hot Restart): 앱의 상태를 완전히 초기화하고 코드를 처음부터 다시 로드합니다. (주로 상태 관리 로직이나 초기화 코드를 수정했을 때 사용합니다.)
• p: 디버그 페인트 켜기/끄기 (UI 위젯의 경계선을 시각적으로 확인)
• q: 앱 실행을 종료하고 터미널 명령어로 빠져나옵니다.