메뉴
게시글

macOS Flutter 설치 및 개발 환경 설정 매뉴얼

Nullull

• 리딩 타임 5분

macOS에서 Flutter 개발 환경을 구성하고 Android·iOS 빌드 도구를 연결하는 절차입니다. 명령 출력에 포함된 Flutter, Android SDK, Xcode 및 Ruby 버전은 원본 메모 작성 시점의 예시이며, 설치 시점에 따라 달라질 수 있습니다.

1. Flutter SDK 설치 및 경로 설정

  1. Flutter 공식 설치 안내에서 macOS 및 사용하는 CPU(Apple Silicon 또는 Intel)에 맞는 SDK 설치 방법을 확인합니다.
  2. Flutter SDK를 사용자 홈 아래 개발 도구 디렉터리 등에 압축 해제합니다. 예를 들어 설치 위치가 ~/development/flutter인 경우:
mkdir -p ~/development
  1. 현재 셸이 zsh인지 확인한 뒤 ~/.zshrc에 Flutter 실행 경로를 추가합니다.
echo 'export PATH="$HOME/development/flutter/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

SDK를 다른 위치에 설치했다면 경로를 실제 위치에 맞게 변경하십시오. 터미널을 다시 열고 Flutter 명령이 실행되는지 확인합니다.

flutter --version
flutter doctor

2. Android 개발 환경 설정

Android Studio 및 SDK 설치

  1. Android Studio를 설치하고 처음 실행합니다.
  2. Setup Wizard에서 기본(Standard) 설정을 선택하거나 SDK Manager에서 필요한 도구를 설치합니다.
  3. Android Studio의 SDK Manager → SDK Tools에서 **Android SDK Command-line Tools (latest)**를 선택해 설치합니다.
  4. SDK Platforms에서 대상 프로젝트가 요구하는 Android SDK Platform을 설치합니다.
  5. SDK 경로를 확인합니다. 기본 경로 예시는 다음과 같습니다.
~/Library/Android/sdk

SDK 경로가 기본 위치와 다르면 Flutter에 명시합니다.

flutter config --android-sdk "$HOME/Library/Android/sdk"

라이선스 동의

Command-line Tools 설치가 완료된 뒤 Android SDK 라이선스에 동의합니다.

flutter doctor --android-licenses

안내를 읽고 동의한 다음 Android 진단 상태를 확인합니다.

flutter doctor

sdkmanager 또는 Command-line Tools를 찾을 수 없다는 오류가 나오면 Android Studio의 SDK Manager에서 **Android SDK Command-line Tools (latest)**가 설치되어 있는지 확인합니다. SDK 경로가 사용자 지정 위치라면 위의 flutter config --android-sdk 경로와 일치하는지도 확인합니다.

3. iOS 및 macOS 개발 환경 설정

iOS 또는 macOS 앱을 빌드하려면 Xcode가 필요합니다.

  1. App Store에서 Xcode를 설치합니다.
  2. Xcode를 한 번 실행해 초기 구성 및 추가 구성요소 설치를 완료합니다.
  3. 활성 개발자 디렉터리를 지정하고 초기 설정을 완료합니다.
sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -runFirstLaunch
  1. 라이선스 동의가 필요하다는 메시지가 표시되면 다음 명령을 실행하고 안내에 따릅니다.
sudo xcodebuild -license

Xcode의 버전과 실제 설치 경로가 다르면 xcode-select 경로를 설치 환경에 맞게 변경하십시오.

4. CocoaPods 설치 (선택)

iOS 또는 macOS 프로젝트에서 CocoaPods를 사용하는 Flutter 플러그인을 빌드하려면 CocoaPods가 필요할 수 있습니다. Homebrew를 사용하는 경우:

brew install cocoapods
pod --version

Ruby 환경을 직접 관리하는 경우에는 지원되는 Ruby를 선택한 뒤 해당 환경의 gem install cocoapods를 사용합니다. sudo gem install cocoapods는 rbenv 등으로 선택한 Ruby 대신 macOS 시스템 Ruby를 사용할 수 있으므로 피하십시오.

기본 시스템 Ruby가 오래되어 설치 오류가 난 경우 Homebrew 등으로 Ruby 버전 관리 도구를 설치하고, 지원되는 Ruby 버전을 선택한 뒤 새 터미널에서 버전과 실행 경로를 확인합니다.

ruby --version
which ruby
gem install cocoapods
pod --version

CocoaPods는 Android나 Flutter Web만 개발하는 경우에는 일반적으로 필요하지 않습니다.

5. 설치 상태 확인

flutter doctor -v

개발 대상 플랫폼별로 진단 결과를 확인합니다.

대상 플랫폼 필요한 주요 도구
Android Android Studio, Android SDK, Command-line Tools, SDK 라이선스
iOS Xcode, Xcode 초기 설정, 필요 시 CocoaPods
macOS Xcode, 필요 시 CocoaPods
Web Flutter SDK 및 지원 브라우저

사용하지 않는 플랫폼의 경고는 해당 플랫폼을 빌드할 때까지 해결하지 않아도 됩니다. Android 또는 iOS 기기를 연결하거나 시뮬레이터를 실행한 뒤 다음 명령으로 인식 여부를 확인합니다.

flutter devices

6. 자주 발생하는 문제

Unable to locate Android SDK

  • Android Studio SDK Manager에서 SDK가 설치되어 있는지 확인합니다.
  • SDK 경로를 확인하고 Flutter 설정에 지정합니다.
flutter config --android-sdk "$HOME/Library/Android/sdk"

cmdline-tools component is missing 또는 sdkmanager not found

Android Studio의 SDK Manager → SDK Tools에서 **Android SDK Command-line Tools (latest)**를 설치하고 flutter doctor --android-licenses를 다시 실행합니다.

Android SDK 라이선스 오류

flutter doctor --android-licenses

위 명령이 sdkmanager를 찾지 못하면 Command-line Tools 설치 여부와 Flutter의 Android SDK 경로를 먼저 확인합니다.

Xcode가 설치되지 않았거나 불완전하다는 오류

  • App Store에서 Xcode 설치가 완료됐는지 확인합니다.
  • Xcode를 실행해 추가 구성요소 설치를 완료합니다.
  • xcode-select가 올바른 Xcode 경로를 가리키는지 확인하고 다음 명령을 다시 실행합니다.
sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -runFirstLaunch

CocoaPods 설치 시 Ruby 버전 오류

현재 Ruby 버전 및 경로를 확인합니다.

ruby --version
which ruby

Homebrew로 CocoaPods를 설치하거나, Ruby 버전 관리 도구에서 지원되는 Ruby를 선택한 후 권한 상승 없이 gem install cocoapods를 실행합니다. 설치 후 pod --version과 flutter doctor로 확인합니다.

공유하기