[개발일지 #02 | 인프라] Mac에서 Flutter & VS Code 개발 환경 구축하기 (초보자 완벽 가이드)

카카오톡 같은 크로스플랫폼 메신저 ‘딩동(DingDong)’ 만들기 프로젝트 2탄!
이번 글에서는 macOS(Apple Silicon M1/M2/M3/M4 및 Intel) 환경에서 Flutter SDK를 설치하고, Visual Studio Code(VS Code)를 실무 개발용으로 완벽하게 세팅하는 과정을 다룹니다. 초보자가 따라 하다가 막히는 단골 에러 포인트까지 모두 해결해 드립니다!

1. 사전 요구사항 및 확인

Flutter로 Android, iOS, macOS, Windows 앱을 개발하려면 기본 개발 도구들이 필요합니다. 본격적인 시작 전에 아래 프로그램들을 먼저 설치해 주세요.

1. Mac 운영체제: macOS 11 이상 권장 (현재 Apple Silicon M1~M4 기준 완벽 지원)
2. Xcode: iOS 및 macOS 앱 빌드용 (Mac App Store에서 무료 다운로드)
3. Android Studio: Android SDK 및 에뮬레이터 설정용 (공식 홈페이지에서 다운로드)
4. Visual Studio Code: 주력 코드 편집기 (공식 홈페이지에서 다운로드)

💡 [필수] Apple Silicon(M1~M4) 맥 사용자 사전 작업
일부 Flutter 패키지 및 도구의 원활한 구동을 위해 Rosetta 2가 필요합니다. 맥 기본 터미널(Terminal) 앱을 열고 아래 명령어를 한 줄 실행해 주세요. (비밀번호 입력 시 화면에 글자가 안 보이는 것이 정상이니 입력 후 엔터를 누르세요.)

sudo softwareupdate --install-rosetta --agree-to-license
``

2. 가장 쉬운 설치 방법: VS Code 플러그인부터 설치하기 (추천!)

터미널에서 명령어 입력하고 환경변수(PATH)를 설정하는 게 복잡하게 느껴진다면, VS Code에서 확장 프로그램(플러그인)을 먼저 설치하고 자동으로 SDK를 다운받는 방법이 가장 쉽고 편리합니다.

flowchart LR
    A[VS Code 실행] --> B[Flutter 확장 설치]
    B --> C[Cmd + Shift + P<br/>Flutter: New Project]
    C --> D[Download SDK 클릭]
    D --> E[자동 설치 및 경로 연결 완료!]
    linkStyle default stroke-width:3px,stroke:#333333

[단계 1] VS Code에서 Flutter 확장 프로그램 설치

1. VS Code를 실행합니다.
2. 좌측 사이드바에서 확장(Extensions) 아이콘(Cmd + Shift + X)을 누릅니다.
3. 검색창에 Flutter를 검색한 뒤 [Install] 버튼을 누릅니다.
4. (참고: Dart 언어 플러그인도 자동으로 함께 설치됩니다.)

[단계 2] VS Code 안내창으로 Flutter SDK 자동 다운로드

1. VS Code에서 단축키 Cmd + Shift + P를 눌러 명령 팔레트를 엽니다.
2. 검색창에 Flutter: New Project를 입력하고 엔터를 칩니다.
3. 컴퓨터에 Flutter SDK가 없으면 우측 하단에 "Could not find a Flutter SDK. Please locate or download..."라는 팝업 알림이 뜹니다.
4. 알림창의 [Download SDK] 버튼을 클릭하고 원하는 폴더(예: 본인 홈 폴더 하위에 development 폴더를 새로 만들어 지정)를 선택합니다.
5. VS Code가 알아서 최신 Flutter SDK를 다운로드하고, 압축을 풀고 VS Code 내부 경로 연결까지 자동으로 완료해 줍니다! (우측 하단 진행바가 끝날 때까지 몇 분간 기다려 주세요.)

⚠️ 초보자 주의사항: 터미널에서도 flutter 명령어를 쓰고 싶다면?
위 방식으로 설치하면 VS Code 내부 기능은 바로 작동하지만, 터미널 창에 직접 flutter 명령어를 치면 zsh: command not found: flutter 에러가 뜰 수 있습니다. 터미널에서도 명령어를 쓰려면 아래 명령어를 복사해서 터미널에 한 번 실행해 주세요. (SDK를 ~/development/flutter에 설치했다고 가정)

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

3. (선택) 전통적인 터미널 수동 설치 방식

만약 2번 방식을 건너뛰고, 터미널에서 패키지 매니저인 Homebrew를 사용해 직접 제어하는 것을 선호하신다면 아래 명령어로 한 번에 설치할 수도 있습니다. (2번으로 이미 설치하셨다면 이 단계는 건너뛰세요!)

# Homebrew를 이용한 Flutter SDK 간편 설치 (환경변수 PATH까지 자동 등록됨)
brew install --cask flutter

# 설치 및 버전 확인
flutter --version

4. Flutter Doctor로 개발 환경 상태 점검하기

VS Code 플러그인과 SDK가 준비되었으면, iOS와 Android 앱을 빌드하기 위한 추가 도구들이 잘 연결되어 있는지 점검할 차례입니다.

• 방법 A (VS Code 기능 사용): Cmd + Shift + P를 누르고 **Flutter: Run Flutter Doctor**를 검색해 실행합니다.
• 방법 B (터미널 명령어 사용): VS Code 하단 터미널(Ctrl + ~)을 열고 아래 명령어를 실행합니다.

flutter doctor

실행하면 현재 내 맥의 개발 환경 상태가 아래처럼 체크리스트로 출력됩니다. 처음에는 [!]나 [✗] 표시가 뜨는 것이 정상입니다!

Doctor summary (to see all details, run flutter doctor -v):
[✓] Flutter (Channel stable, 3.x.x, on macOS ...)
[!] Android toolchain - develop for Android devices (Android SDK version 34.0.0)
    ! Some Android licenses not accepted. To resolve this, run: flutter doctor --android-licenses
[✗] Xcode - develop for iOS and macOS
    ✗ Xcode installation is incomplete; a full installation is necessary for iOS development.
    ✗ CocoaPods not installed.
[✓] Chrome - develop for the web
[✓] Android Studio (version 2024.x)
[✓] VS Code (version 1.x.x)

느낌표(!)나 엑스(✗)가 뜰 때 해결 방법

① Android 도구 및 라이선스 동의 오류 해결

먼저 Android Studio를 실행한 뒤, 초기 설정을 마치고 아래 설정을 반드시 체크해야 합니다.

1. Android Studio 시작 화면에서 More Actions (점 세 개 버튼) -> SDK Manager 클릭 (또는 Settings -> Languages & Frameworks -> Android SDK).
2. 상단 탭 중 [SDK Tools] 탭으로 이동합니다.
3. 목록에서 **Android SDK Command-line Tools (latest)**를 체크하고 **[Apply]**를 눌러 설치합니다. (이걸 빼먹으면 라이선스 명령어가 작동하지 않습니다!)
4. 설치가 끝나면 VS Code 터미널로 돌아와 아래 명령어를 실행하고, 나오는 모든 질문에 y를 입력해 동의합니다.

flutter doctor --android-licenses

② Xcode 관련 설정 (iOS/Mac 빌드용)

1. App Store에서 Xcode 설치가 완료되었다면, 먼저 Xcode를 한 번 실행하여 기본 컴포넌트 설치를 진행합니다.
2. 최신 Xcode에서는 iOS 시뮬레이터를 직접 다운로드해야 합니다. 상단 메뉴에서 Xcode -> Settings (Cmd + ,) -> Components (또는 Platforms) 탭으로 이동하여 iOS Simulator 옆의 [Get] 버튼을 눌러 다운로드합니다.
3. 그다음 터미널에서 아래 명령어를 실행해 경로 지정과 라이선스 동의를 완료합니다.

# Xcode 명령줄 도구 경로 지정 및 첫 실행 설정
sudo sh -c 'xcode-select -s /Applications/Xcode.app/Contents/Developer && xcodebuild -runFirstLaunch'

# Xcode 라이선스 동의
sudo xcodebuild -license accept

③ CocoaPods 설치 (iOS 라이브러리 관리자)

iOS 네이티브 패키지를 관리해 주는 도구입니다. 맥 기본 Ruby 환경과 권한 충돌이 나지 않도록 Homebrew로 설치하는 것을 강력히 권장합니다.

# 방법 1: Homebrew가 설치되어 있다면 (가장 깔끔하고 안전함 - 추천!)
brew install cocoapods

# 방법 2: Homebrew가 없다면
sudo gem install cocoapods

위 과정들을 마친 후 다시 flutter doctor를 실행했을 때, 모든 항목에 [✓] 초록색 체크가 뜨면 완벽하게 준비 완료입니다!

5. 추가로 설치하면 좋은 유용한 VS Code 확장 & 설정

5.1 생산성 추천 플러그인 (Extensions)

VS Code 좌측의 확장 아이콘(Cmd + Shift + X)에서 추가로 설치하면 실무 개발이 훨씬 편리해집니다.

5.2 생산성을 200% 올려주는 VS Code 설정 (settings.json)

코드를 저장(Cmd + S)할 때마다 들여쓰기 줄 맞춤을 자동으로 정리해 주고, 복잡한 위젯 트리 구조를 눈으로 보기 쉽게 점선(UI 가이드라인)으로 연결해 주는 필수 설정입니다.

1. VS Code에서 Cmd + Shift + P를 누르고 **Preferences: Open User Settings (JSON)**을 검색해 엔터를 칩니다.
2. 열린 settings.json 파일의 중괄호 { ... } 안에 아래 내용을 추가(병합)하고 저장합니다.

{
  // 1. Dart 파일 저장 시 자동 코드 정렬 및 자동 수정(const 추가, 안 쓰는 import 정리)
  "[dart]": {
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
      "source.fixAll": "explicit",
      "source.organizeImports": "explicit"
    }
  },
  // 2. 위젯 트리 구조를 점선 가이드라인으로 표시 (괄호 지옥 방지 필수 옵션!)
  "dart.previewFlutterUiGuides": true,
  "dart.previewFlutterUiGuidesCustomTracking": true,
  // 3. 자동 줄바꿈 기준을 80자에서 100자로 넉넉하게 확장
  "dart.lineLength": 100,
  // 4. 5.1에서 설치한 Material 아이콘 테마 바로 적용
  "workbench.iconTheme": "material-icon-theme"
}

6. 첫 번째 Flutter 프로젝트 실행 테스트

모든 설정이 끝났으니, 제대로 동작하는지 기본 샘플 프로젝트를 만들어 실행해 봅니다.

6.1 프로젝트 생성

1. VS Code에서 Cmd + Shift + P를 누르고 Flutter: New Project를 선택합니다.
2. 템플릿 목록에서 Application을 선택합니다.
3. 프로젝트가 저장될 폴더를 지정합니다.
4. 프로젝트 이름 입력창에 dingdong_app *(소문자와 언더스코어 _만 사용 가능)*을 입력하고 엔터를 누르면 기본 프로젝트 코드가 생성됩니다!

6.2 실행 및 핫 리로드(Hot Reload) 체험

1. 디바이스 선택: VS Code 우측 하단 파란색(또는 보라색) 상태바에서 현재 선택된 기기 이름을 클릭해 타겟 기기를 선택합니다.
   • (예: macOS (darwin), iPhone 16 Pro Simulator, 또는 Chrome)
2. 실행: 키보드 F5 키를 누르거나, 상단 메뉴에서 **Run -> Start Debugging**을 클릭합니다. (최초 실행 시 빌드하는 데 1~2분 정도 소요됩니다.)
3. 핫 리로드(Hot Reload) 테스트:
   • 좌측 탐색기에서 lib/main.dart 파일을 엽니다.
   • 코드 중간의 'Flutter Demo Home Page' 문구를 **'딩동 메신저 개발 시작!'**으로 변경하고 저장(Cmd + S)합니다.
   • 앱이 재시작되지 않고 1초도 안 되어 화면 글자가 즉시 바뀌는 마법을 확인할 수 있습니다!

7. 다음 편 예고

이제 모바일/데스크톱 앱을 개발할 수 있는 완벽한 클라이언트 환경이 마련되었습니다.

다음 **[개발일지 #03 인프라]**에서는 유그린 NAS(UGOS)의 Docker를 이용해 PostgreSQL 데이터베이스와 Caddy 웹서버를 세팅하고 외부에서 안전하게 접속하는 방법을 다루겠습니다!