VS Code + Flutter 안드로이드 테스트 환경 설정 가이드 (에뮬레이터 + 실기기)

먼저 알아야 할 것 — 각 도구의 역할

설정을 시작하기 전에 각 도구가 실제로 무슨 일을 하는지 파악하면 삽질을 줄일 수 있다.

⚠️ 흔한 오해 — "VS Code 확장만 깔면 되는 거 아닌가요?"

Android iOS Emulator 같은 VS Code 확장팩은 에뮬레이터를 만들어주는 도구가 아니다.
이미 존재하는 에뮬레이터를 VS Code 안에서 편리하게 실행해주는 런처일 뿐이다.

즉, 아래 순서가 반드시 지켜져야 한다:

Android SDK 설치
    ↓
AVD(가상 기기) 생성
    ↓
환경변수 설정
    ↓
flutter doctor 통과
    ↓
VS Code에서 에뮬레이터 실행

확장팩만 깔면 에뮬레이터 목록이 비어있거나 아무것도 실행되지 않는다.

전체 설정 흐름

[1] Android SDK 설치 선택
     ├── 방법 A: Android Studio 설치 (권장 — GUI로 관리)
     └── 방법 B: Command Line Tools만 설치 (경량 — 용량 절약)
[2] 환경변수 설정
[3] flutter doctor로 상태 점검
[4] VS Code 확장 설치
[5] 에뮬레이터 실행  or  실기기 연결
[6] flutter run으로 앱 실행

STEP 1. Android SDK 설치

방법 A — Android Studio 설치 (권장)

Android Studio를 IDE로 쓸 필요는 없다. SDK와 AVD 관리 도구만 빌려쓰는 것이라고 생각하면 된다.

1. https://developer.android.com/studio 에서 다운로드
2. 설치 중 아래 항목 체크 확인:
   • ✅ Android SDK
   • ✅ Android SDK Platform
   • ✅ Android Virtual Device (AVD)
3. 설치 완료 후 SDK Manager 실행 → 아래 항목 설치 확인:
   • Android SDK Build-Tools
   • Android SDK Command-line Tools
   • Android SDK Platform-Tools

💡 SDK 기본 설치 경로 (Windows)
C:\Users\사용자명\AppData\Local\Android\Sdk

방법 B — Command Line Tools만 설치 (경량 설치)

Android Studio 설치 없이 SDK만 따로 받는 방법이다. 용량을 아끼고 싶을 때 선택한다.
단, 명령어로 직접 설정해야 하기 때문에 경로가 꼬이면 flutter doctor가 SDK를 못 찾는 문제가 생길 수 있다.

1. Command Line Tools 다운로드
https://developer.android.com/studio#command-tools 에서 cmdline-tools 다운로드

2. 폴더 구조 구성 (이 구조가 틀리면 sdkmanager가 동작 안 함)

C:\Android\
└── cmdline-tools\
    └── latest\
        ├── bin\
        ├── lib\
        └── source.properties

3. 환경변수 설정 후 SDK 구성 요소 설치

sdkmanager "platform-tools"
sdkmanager "platforms;android-34"
sdkmanager "system-images;android-34;google_apis;x86_64"
sdkmanager "build-tools;34.0.0"

4. Flutter 라이선스 동의

flutter doctor --android-licenses
# 모두 y 입력

방법 A vs B 비교

STEP 2. 환경변수 설정

Windows 기준. 시스템 속성 > 환경변수에서 설정.

새 시스템 변수 추가:

시스템 PATH에 추가:

%ANDROID_HOME%\platform-tools
%ANDROID_HOME%\tools
%ANDROID_HOME%\cmdline-tools\latest\bin

⚠️ 환경변수 설정 후 터미널을 완전히 종료하고 다시 열어야 적용된다.

STEP 3. flutter doctor로 상태 점검

flutter doctor

정상 통과 시 출력 예시:

[✓] Flutter (Channel stable)
[✓] Android toolchain - develop for Android devices
[✓] VS Code
[!] Connected device (기기 연결 전이라 경고 — 정상)

자주 뜨는 오류와 해결법:

⚠️ 자주 겪는 오류 상세 — Android sdkmanager not found

flutter doctor --android-licenses 를 실행했을 때 아래처럼 오류가 뜨는 경우가 있다:

Android sdkmanager not found. Update to the latest Android SDK and ensure that
the cmdline-tools are installed via the Android SDK Manager.

이 오류의 원인은 단순하다. 라이선스 동의를 처리하는 sdkmanager 프로그램 자체가 cmdline-tools 안에 들어있는데, 이 툴이 아직 설치되지 않은 것이다.

즉, flutter doctor --android-licenses를 실행하려면 cmdline-tools가 먼저 설치되어 있어야 한다.

✅ 해결 방법 — Android SDK Command-line Tools 설치

1. Android Studio 실행
2. 메인 화면 우측 상단 톱니바퀴 아이콘 클릭 → SDK Manager 선택
   (프로젝트가 열려 있다면 상단 메뉴 Tools → SDK Manager)
3. SDK Tools 탭 클릭
4. 목록에서 Android SDK Command-line Tools (latest) 찾아서 체크박스 ✅
5. 우측 하단 Apply 클릭 → 확인 창에서 OK
6. 설치 완료 후 터미널에서 아래 명령어 재실행:

flutter doctor --android-licenses
# 묻는 항목마다 y 입력

💡 이 과정을 거쳐야 비로소 flutter doctor의 Android toolchain 항목이 ✓ 로 바뀐다.

STEP 4. VS Code 확장 설치

필수:

선택 (생산성 향상):

STEP 5-A. 에뮬레이터 실행

AVD(가상 기기) 생성 — Android Studio GUI 방법

1. Android Studio 실행
2. More Actions → Virtual Device Manager
3. Create Device 클릭
4. 기기 선택: Pixel 7 추천 (Google Play 지원, 안정적)
5. 시스템 이미지: API 34 (Android 14) 선택 후 다운로드
6. AVD 이름 확인 → Finish

AVD 생성 — 명령어 방법 (cmdline-tools 사용자)

avdmanager create avd \
  -n MyEmulator \
  -k "system-images;android-34;google_apis;x86_64"

VS Code에서 에뮬레이터 실행하기

방법 1 — 상태바 클릭 (가장 쉬움)

VS Code 우측 하단 기기 선택 영역 클릭
→ 생성한 AVD 이름 선택
→ 에뮬레이터 자동 실행

방법 2 — 명령 팔레트

Ctrl + Shift + P
→ "Flutter: Launch Emulator" 입력
→ 원하는 AVD 선택

방법 3 — 터미널 직접 실행

flutter emulators                          # 목록 확인
flutter emulators --launch [에뮬레이터_ID]  # 실행

앱 실행

flutter run

또는 F5 (VS Code 디버그 모드)

💡 Hot Reload가 동작하려면 반드시 디버그 모드(F5)로 실행해야 한다.
flutter run 실행 후 터미널에서 r 키를 눌러도 Hot Reload 가능.

STEP 5-B. 실제 안드로이드 기기 연결 (USB)

기기 설정

1. 설정 → 휴대폰 정보 → 소프트웨어 정보 → 빌드번호 7번 연타
2. 개발자 옵션 활성화 확인
3. 개발자 옵션 → USB 디버깅 ON

USB 연결 후 인식 확인

adb devices

정상 출력:

List of devices attached
R3CN1234ABC     device    ← device로 표시되면 성공

상태별 의미:

⚠️ 자주 겪는 오류 상세 — Device is not authorized

flutter devices 실행 시 아래처럼 출력되는 경우가 있다:

Device R3CXC0LN5LH is not authorized.
You might need to check your device for an authorization dialog.

기기는 인식됐지만 이 PC에서의 디버깅을 아직 허용하지 않은 상태다.

✅ 해결 방법

1. 연결된 스마트폰의 화면을 켜고 잠금을 해제한다
2. 화면에 "USB 디버깅을 허용하시겠습니까?" 팝업이 떠 있을 것이다
   (RSA 키 지문 관련 내용이 함께 표시되기도 함)
3. "이 컴퓨터에서 항상 허용" 체크박스에 ☑ 체크
4. 확인(허용) 버튼 클릭
5. 터미널에서 다시 확인:

adb devices
# 상태가 unauthorized → device 로 바뀌면 성공

💡 팝업이 보이지 않는다면 USB를 뽑았다가 다시 꽂으면 팝업이 다시 뜬다.
"항상 허용"에 체크해두면 다음 연결부터는 팝업 없이 바로 연결된다.

드라이버 문제 (Windows 한정)

STEP 5-C. 무선 연결 (Android 11 이상)

USB 없이 Wi-Fi로 연결하는 방법. 같은 Wi-Fi 환경이어야 한다.

# 1. USB로 먼저 연결한 상태에서 실행
adb tcpip 5555

# 2. 기기 IP 확인 (설정 → Wi-Fi → 상세정보)
adb connect 192.168.x.x:5555

# 3. USB를 뽑아도 연결 유지됨 — 확인
adb devices

Android 11 이상 + Android Studio 최신 버전이라면 Wireless Debugging (QR 코드 방식) 도 지원한다.
개발자 옵션 → 무선 디버깅 활성화 후 Android Studio의 Pair Devices Using Wi-Fi 메뉴 사용.

트러블슈팅 모음

마무리 — 설정 완료 체크리스트

□ Android SDK 설치 완료
□ 환경변수 ANDROID_HOME 설정 완료
□ flutter doctor 모두 ✓ (또는 device 경고만 남은 상태)
□ VS Code Flutter 확장 설치 완료
□ AVD 생성 완료 (에뮬레이터 사용 시)
□ USB 디버깅 활성화 (실기기 사용 시)
□ flutter run으로 앱 정상 실행 확인

💬 설정 중 막히는 부분이 있다면 flutter doctor -v 명령어로 상세 로그를 확인하자.
오류 원인의 90%는 이 명령어 출력에서 힌트를 얻을 수 있다.