> ## Content Index
> Fetch the complete content index at: https://appsworld.kr/llms.txt
> Use this file to discover other available public pages before exploring further.

# macOS Flutter 설치 및 개발 환경 설정 매뉴얼
- URL: https://appsworld.kr/macos-flutter-seolci-mic-gaebal-hwangyeong-seoljeong-maenyueol/
- Published: 2026-10-14T07:16:55.000Z
- Updated: 2026-10-14T07:16:55.000Z
- Author: Nullull

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

## 1\. Flutter SDK 설치 및 경로 설정

1. [Flutter 공식 설치 안내](https://docs.flutter.dev/install/manual)에서 macOS 및 사용하는 CPU(Apple Silicon 또는 Intel)에 맞는 SDK 설치 방법을 확인합니다.
2. Flutter SDK를 사용자 홈 아래 개발 도구 디렉터리 등에 압축 해제합니다. 예를 들어 설치 위치가 `~/development/flutter`인 경우:

```bash
mkdir -p ~/development

```

1. 현재 셸이 zsh인지 확인한 뒤 `~/.zshrc`에 Flutter 실행 경로를 추가합니다.

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

```

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

```bash
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 경로를 확인합니다. 기본 경로 예시는 다음과 같습니다.

```text
~/Library/Android/sdk

```

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

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

```

### 라이선스 동의

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

```bash
flutter doctor --android-licenses

```

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

```bash
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. 활성 개발자 디렉터리를 지정하고 초기 설정을 완료합니다.

```bash
sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -runFirstLaunch

```

1. 라이선스 동의가 필요하다는 메시지가 표시되면 다음 명령을 실행하고 안내에 따릅니다.

```bash
sudo xcodebuild -license

```

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

## 4\. CocoaPods 설치 (선택)

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

```bash
brew install cocoapods
pod --version

```

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

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

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

```

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

## 5\. 설치 상태 확인

```bash
flutter doctor -v

```

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

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

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

```bash
flutter devices

```

## 6\. 자주 발생하는 문제

### `Unable to locate Android SDK`

- Android Studio SDK Manager에서 SDK가 설치되어 있는지 확인합니다.
- SDK 경로를 확인하고 Flutter 설정에 지정합니다.

```bash
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 라이선스 오류

```bash
flutter doctor --android-licenses

```

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

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

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

```bash
sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -runFirstLaunch

```

### CocoaPods 설치 시 Ruby 버전 오류

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

```bash
ruby --version
which ruby

```

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