첫 앱 만들기도 전에 망부석이 될 뻔한 당신에게
special thx to. 지선생님, 블선생님들

👋  인트로

플러터 앱을 개발하려고 VSCode를 깔고 가볍게 시작했는데,
생각보다 초기 세팅에서 시간이 꽤나 걸렸다.

 

플러터 초기세팅 사건을 아는 사람: 너무 무서워

 

특히 Android SDK, iOS CocoaPods, 시뮬레이터 문제 등등…

이 글은 내가 직접 겪은 Flutter 세팅 삽질기(?)를 정리한 글이다.

 

어이 블선생 지선생. 일감이다.


하지만 생각해보면? 어?
오히려 더 배울 수 있는 기회잖아~ 완전 합격이잖아~

하지만 여러분은 저처럼 고생하지 마세요. 그래서 적어봤습니다.


나처럼 VSCode 기반으로 Android + iOS 둘 다 개발하려는 사람에게 도움이 되길 바라면서~ 스타뜨!

 

💻 참고차 적어본 사전 정보

  • 사용 에디터: VSCode
  • OS: macOS
  • 이미 설치된 툴:
    • Android Studio ✅
    • Xcode ✅
    • VSCode ✅
  • Flutter SDK 설치 방식: Homebrew로 설치
brew install flutter
 

 

🧩 Step 1. Flutter SDK 경로 설정

 

설치 후, 기본 점검부터 시작!

flutter doctor
 

그런데 바로 이런 에러가 떴다:

Unable to locate Android SDK
 

✅ 해결 방법

  1. Android Studio에서 SDK 경로 확인
    예: ~/Library/Android/sdk
    (위에는 그냥 예시고, 실제로는 내 경로를 복사해주었다!)

  2. Flutter에 경로 수동 등록
flutter config --android-sdk ~/Library/Android/sdk
 
 

터미널 껐다 켜고 flutter doctor 다시 실행하면 Android 인식 완료!

 

🧩 Step 2. Android Emulator 설정 – avdmanager missing?

VSCode에서 Flutter: Create Android Emulator 명령 실행 시:

avdmanager is missing from the Android SDK
 

이게 무슨 일이람…? 

✅ 해결 방법

Flutter가 cmdline-tools 내부의 avdmanager를 못 찾는 이슈였다.
실제 경로엔 있는데, Flutter가 못 찾는 경우 아래처럼 symlink를 만들어줬다:

mkdir -p ~/Library/Android/sdk/tools/bin

ln -s ~/Library/Android/sdk/cmdline-tools/latest/bin/avdmanager ~/Library/Android/sdk/tools/bin/avdmanager
ln -s ~/Library/Android/sdk/cmdline-tools/latest/bin/sdkmanager ~/Library/Android/sdk/tools/bin/sdkmanager
 

VSCode 재시작 후 다시 실행 → 에뮬레이터 생성 성공 ~

 

🧩 Step 3. CocoaPods 설치 – ruby 버전 오류

 

자 이제 CocoaPods 설치 시도해봄

sudo gem install cocoapods

 

그런데 한참 있다가 이런 에러 발생:

securerandom requires Ruby >= 3.1.0
현재 Ruby는 2.6.10...
 

✅ 해결 방법

macOS 기본 Ruby가 너무 낮아서 발생한 문제.
rbenv로 최신 Ruby 설치:

brew install rbenv ruby-build

echo 'eval "$(rbenv init -)"' >> ~/.zshrc
source ~/.zshrc

rbenv install 3.2.2
rbenv global 3.2.2
 

그러고 다시

 
sudo gem install cocoapods

 

 

하면 설치 성공 🎉

 

안드로이드 에뮬레이터를 실행하면 이런 식으로 보인다.

 

🧩 Step 4. iOS 시뮬레이터.. 너 왜 visionOS로 켜지냐?

 

Flutter: Launch iOS Simulator → Vision Pro 시뮬레이터가 켜지며 멈춤...,,,

그리고 이런 에러가 뜬다

너무 오랫동안 에뮬레이터가 실행 안되고 대기중이라 그런듯

Failed to launch iOS Simulator: Error: Emulator didn't connect within 60 seconds
 
일단 왜 비전프로 시뮬이 뜨는지부터 확인해보고 그거부터 잡기로 했다
 

✅ 해결 방법

결론부터 말하자면 Xcode 시뮬레이터 설정상으로 항상 최근에 실행한 디바이스가 켜지도록 되어있어서 그랬다.

최근에 visionOS 프로젝트를 하느라 마지막에 켰던 게 저거였나보다.

 

그래서 설정을 바꿔주고, 아무 프로젝트나 켜서 iPhone 16 Pro로 런해줬더니 해결됨.ㅋ

 

좀 구체적으로 말하자면

일단 시뮬레이터에서 설정을 확인해준다.

상단의 설정 > 시뮬 켜면 최근에 켰던 시뮬레이터 열기 > 체크되어 있는지 확인 (체크됐다면 원인이 맞을 확률 UP)

여기까지 확인 됐다면 Xcode에서 아무 프로젝트나 열고 아이폰으로 런해줍니다.

그러고 VSC로 돌아와서 flutter run 을 해주면 ~~~?

 

 

아무리 기다려도...

아무 것도 뜨지 않는다...

아무.. 것도....

실행이 되는건가..? 안되는건가? 안되는거겠지?

 

 

🧩 Step 5. flutter run 실패 – 서명 인증서 오류

 

응? 이건??

 

한참을 기다린 끝에 에러 메세지를 받을 수 있었다

시뮬레이터는 켜졌지만 앱 실행은 안 된 상태

Signing certificate is invalid Apple Development: ... is not valid for code signing

 

뭐야 인증서 문제였어? 

이거 참 자주 뵙던 분이군요 껄껄 즉시 조져드립니다

바로 해결 고.

 

✅ 해결 방법

  1. Xcode로 ios/Runner.xcworkspace 열기
  2. Runner → Signing & Capabilities
  3. Automatically manage signing 체크
  4. Apple 계정 선택 <- 나의 경우에는 다시 로그인을 해야 했다.
  5. (필요 시) 인증서 재발급 
  6. Xcode에서 ⌘ + B로 빌드 성공 확인 후, 다시 flutter run

그러면 실행할 시뮬레이터를 선택하라고 뜬다.

 

 

내 경우에는 2번인 iPhone 16 Pro를 선택했다.

그리고 드디어 iOS 시뮬레이터에서 앱 실행 완료!

(참고) Emulator 실행 단축키:
1) Cmd + Shift + P → Flutter: Launch Emulator
2) 우하단의 Device 버튼을 그냥 눌러도 된다 ㅋ

 

 

🎉 마무리

이제 Android/iOS 모두 VSCode 하나로 개발, 실행, 디버깅이 가능해졌다!

샘플 앱이 양쪽에서 잘 돌아가는 걸 확인했으니 이제 만들기만 하면 된다.

 

참고로 나는 이미 android studio를 예전에 설치해놨고, Xcode도 전부터 쓰고 있었어서 둘 다 세팅이 되어 있었지만

그렇지 않은 분들은 세팅에 조금 더 시간을 써야할 수도 있다..!

 

처음이 조오금 번거로울 수는 있지만 그래도 이 정도면 할만한 것 같다.

모두 화이팅! 


(P.S. 잠깐 다른 걸 찍먹해봤지만 역시 난 모바일 앱이 좋다.... 마음의 고향...... 최고..!!!!)

 

 

 

 

📚 참고자료

티스토리툴바