콘텐츠로 이동

Flutter Build Fix 자동화 스크립트

마지막 업데이트: 2025-06-18
버전: v2.0 (GitHub Releases 방식으로 전환)
작성자: Heesung Jin (kage2k)

🍎 macOS 전용

이 스크립트는 macOS에서만 동작합니다. iOS 개발을 위해 macOS가 필요한 Flutter 개발자를 위해 설계되었습니다.

🎉 v2.0 주요 변경사항

새로운 배포 방식

  • ✅ GitHub Releases: 체계적인 버전 관리
  • ✅ 원클릭 설치: 복잡한 설정 과정 제거
  • ✅ 자동 업데이트: 항상 최신 버전 유지
  • ✅ 통계 확인: 다운로드 수 및 사용량 추적

flutter_build_fix_script 스크립트는 무엇인가?!

빠른 해결

Flutter 빌드 에러를 한 번에 해결하는 자동화 스크립트예요!
Java, Gradle, iOS 관련 문제를 모두 해결합니다.

🚀 원클릭 설치 (권장)

💫 새로운 방식: 원클릭 설치

터미널에서 한 줄로 설치 완료!
1
curl -fsSL https://raw.githubusercontent.com/flutterkage2k/flutter-build-fix/main/install.sh -o install.sh && zsh install.sh

설치 완료!

설치가 끝나면 바로 사용할 수 있어요:

1
2
3
flutter-fix       # 전체 정리
ffand            # Android만
ffios            # iOS만

📊 현재 버전 정보

GitHub release Downloads

🔄 업데이트

기존 사용자도 동일한 명령어로 업데이트

최신 버전으로 업데이트
1
curl -fsSL https://raw.githubusercontent.com/flutterkage2k/flutter-build-fix/main/install.sh -o install.sh && zsh install.sh

자동 업데이트 알림

스크립트 실행 시 새 버전이 있으면 자동으로 알려드려요!

📥 수동 설치 (고급 사용자)

원클릭 설치를 원하지 않는 경우:

GitHub Releases에서 직접 다운로드

최신 릴리즈 보기

수동 설치 과정
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
# 1. 설치 디렉토리 생성
mkdir -p ~/.flutter-tools

# 2. 최신 버전 다운로드
curl -fsSL https://raw.githubusercontent.com/flutterkage2k/flutter-build-fix/main/flutter_build_fix.sh \
  -o ~/.flutter-tools/flutter_build_fix.sh

# 3. 실행 권한 부여
chmod +x ~/.flutter-tools/flutter_build_fix.sh

# 4. alias 설정 (macOS 기본 zsh)
echo 'alias flutter-fix="$HOME/.flutter-tools/flutter_build_fix.sh --full"' >> ~/.zshrc
echo 'alias ffand="$HOME/.flutter-tools/flutter_build_fix.sh --android"' >> ~/.zshrc
echo 'alias ffios="$HOME/.flutter-tools/flutter_build_fix.sh --ios"' >> ~/.zshrc
source ~/.zshrc

💡 주요 기능

기능 설명
🔧 Java 17 자동 설정 Homebrew 기반 Java 17 자동 감지 및 환경변수 설정
🧹 Flutter 캐시 정리 flutter clean, flutter pub get 자동 실행
🛠️ Gradle 정리 Android 빌드 캐시 및 daemon 정리, gradle.properties 최적화
📱 iOS Pods 재설치 CocoaPods 완전 정리 및 재설치
🍎 Xcode 캐시 정리 DerivedData 폴더 삭제
⚙️ 3가지 모드 플랫폼별 선택적 실행 가능
🔔 자동 업데이트 알림 새 버전 출시 시 자동 알림

📋 사용법

🎯 3가지 실행 모드

명령어 모드 설명 포함 기능
flutter-fix 전체 정리 (기본값) Android + iOS 모든 정리 Java 설정 + Gradle 정리 + iOS Pods + Xcode 정리
ffand Android 전용 Android/Gradle 문제만 해결 Java 설정 + Gradle 정리 + APK 빌드 테스트
ffios iOS 전용 iOS 문제만 해결 iOS Pods + Xcode 정리 + iOS 빌드 테스트

기본 사용법

프로젝트 폴더에서 실행
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
# Flutter 프로젝트 루트로 이동
cd your-flutter-project

# 전체 정리 (가장 많이 사용)
flutter-fix

# 특정 플랫폼만
ffand    # Android 문제만
ffios    # iOS 문제만

# 도움말
flutter-fix --help

🔧 각 모드별 상세 동작

🤖 Android 모드 (ffand)

실행 순서:

  1. ☕ Java 17 설정 - Homebrew 경로에서 자동 감지 및 환경변수 설정
  2. 🧹 Flutter 정리 - flutter clean + flutter pub get

  3. 🛠️ Gradle 완전 정리:

  4. 모든 Gradle Daemon 종료

  5. 전역/로컬 Gradle 캐시 삭제
  6. gradle.properties 최적화

  7. Gradle Wrapper 8.6으로 업데이트

  8. ✅ 빌드 테스트 - APK 빌드로 정상 작동 확인

🍎 iOS 모드 (ffios)

실행 순서:

  1. 🧹 Flutter 정리 - flutter clean + flutter pub get

  2. 📱 iOS Pods 완전 정리:

  3. Pods 폴더 삭제

  4. CocoaPods 캐시 정리

  5. 스마트 Pod 재설치 (빠른 방법 먼저 시도)

  6. 🍎 Xcode 정리 - DerivedData 및 캐시 폴더 삭제

  7. ✅ 빌드 테스트 - iOS 빌드로 정상 작동 확인

🌟 전체 모드 (flutter-fix)

Android 모드 + iOS 모드를 순차적으로 실행

🆘 문제 해결

자주 발생하는 문제들

curl 명령어 실행 안됨

네트워크 연결이나 방화벽 문제일 수 있습니다. 

1
2
3
4
5
# Homebrew로 wget 설치 후 사용
brew install wget
wget -qO- https://raw.githubusercontent.com/flutterkage2k/flutter-build-fix/main/install.sh | zsh

# 또는 GitHub Releases에서 직접 다운로드

Permission denied 에러

실행 권한이 없을 때 발생하는 문제입니다. 

1
chmod +x ~/.flutter-tools/flutter_build_fix.sh

Java 17을 찾을 수 없음

Java 17이 설치되지 않았거나 경로 설정이 안 된 경우입니다. 

1
2
3
4
5
6
7
8
9
# Homebrew로 Java 17 설치
brew install openjdk@17

# 시스템에 등록
sudo ln -sfn /opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk /Library/Java/JavaVirtualMachines/openjdk-17.jdk

# 환경변수 설정 (zsh)
echo 'export JAVA_HOME=/opt/homebrew/opt/openjdk@17' >> ~/.zshrc
source ~/.zshrc

flutter-fix 명령어를 찾을 수 없음

설치 후 새 터미널을 열거나 다음 명령어로 해결: 

1
2
3
4
5
6
7
# zsh 설정 다시 로드 (macOS 기본)
source ~/.zshrc

# bash 사용 시
source ~/.bashrc

# 또는 새 터미널 창 열기

Xcode가 설치되지 않음

iOS 개발을 위해서는 Xcode가 필요합니다. 

1
2
3
# App Store에서 Xcode 설치 또는
# Command Line Tools만 설치
xcode-select --install

CocoaPods 문제

CocoaPods 설치나 업데이트 관련 문제입니다. 

1
2
3
4
5
6
# CocoaPods 재설치 (gem)
sudo gem uninstall cocoapods
sudo gem install cocoapods

# 또는 Homebrew로 설치 (권장)
brew install cocoapods

🔍 새로운 기능들

🔔 자동 업데이트 알림

스크립트 실행 시 새 버전이 있으면 자동으로 알려드려요:

1
2
3
4
5
6
$ flutter-fix
🔔 새 버전이 있습니다: v2.1 (현재: v2.0)
🔄 업데이트: curl -fsSL https://raw.githubusercontent.com/flutterkage2k/flutter-build-fix/main/install.sh -o install.sh && zsh install.sh

🚀 Flutter 3.32.4 최적화 빌드 수정 스크립트 시작
...

📊 사용량 통계

GitHub에서 실시간으로 확인 가능:

  • 다운로드 수
  • 스타 수
  • 이슈 및 피드백

🛠️ 향상된 안정성

  • 스마트 Pod 설치: 빠른 방법 먼저 시도, 실패 시 --repo-update
  • 호환성 검사: flutter analyze --suggestions 자동 실행
  • 더 나은 에러 메시지: 실패 원인과 해결책 명확히 제시

🎯 실제 사용 예시

새 프로젝트 시작 시

새 Flutter 프로젝트 설정
1
2
3
4
5
6
7
8
9
# 1. 프로젝트 생성
flutter create my_awesome_app
cd my_awesome_app

# 2. 환경 최적화 (한 번만 실행)
flutter-fix

# 3. 개발 시작
flutter run

빌드 에러 발생 시

빌드 에러 해결 과정
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
# 빌드 에러 발생
flutter run # ❌ 에러 발생

# 플랫폼별 해결
ffand    # Android 문제 해결
ffios    # iOS 문제 해결

# 또는 한 번에
flutter-fix

# 다시 빌드
flutter run # ✅ 정상 작동

오래된 프로젝트 재시작

장기간 방치된 프로젝트
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
cd old-flutter-project

# 환경 완전 정리 및 최신화
flutter-fix

# 의존성 업데이트
flutter pub upgrade

# 정상 작동 확인
flutter run

📚 관련 가이드

이 문서들과 함께 보시면 더 효과적입니다:

💡 추가 팁

언제 사용하면 좋을까요?

정기적 사용 권장

  • 새 Flutter 프로젝트 시작 전
  • 오랫동안 작업하지 않은 프로젝트 재개 시
  • 이상한 빌드 에러 발생 시
  • Gradle이나 Pods 관련 문제가 생겼을 때
  • "Starting a Gradle Daemon" 에러 발생 시
  • Flutter나 Xcode 업데이트 후
  • 새로운 패키지 추가 후 빌드 문제 발생 시

개발 워크플로우에 통합

일일 개발 루틴
1
2
3
4
5
6
7
8
# 아침 개발 시작 시
cd my-project
flutter-fix    # 환경 점검 및 정리
flutter run    # 개발 시작

# 이상한 에러 발생 시
flutter-fix    # 빠른 해결
flutter run    # 재시작

macOS 환경 최적화 팁

macOS Flutter 개발 환경

  • Homebrew 사용: 모든 개발 도구를 Homebrew로 관리하면 편리해요
  • Xcode 최신 유지: iOS 빌드 호환성을 위해 항상 최신 버전 사용
  • Java 17 고정: Flutter Android 빌드의 안정성을 위해 Java 17 권장
  • 정기적 정리: 주 1회 정도 flutter-fix 실행으로 환경 최적화

🔗 GitHub Repository

프로젝트의 모든 정보는 GitHub에서 확인하세요:

GitHub Repository

참여하기

  • 🐛 버그 리포트: Issues
  • 💡 기능 제안: Discussions
  • ⭐ Star: 프로젝트가 도움이 되셨다면 Star를 눌러주세요!
  • 🔄 Pull Request: 개선사항이 있으시면 PR을 보내주세요

📞 도움이 필요하신가요?

지원 채널

제거 방법

더 이상 필요 없다면:

완전 제거
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
# 1. 스크립트 파일 삭제
rm -rf ~/.flutter-tools

# 2. alias 제거 (macOS)
sed -i '' '/flutter-fix\|ffand\|ffios/d' ~/.zshrc
source ~/.zshrc

# bash 사용 시
sed -i '' '/flutter-fix\|ffand\|ffios/d' ~/.bashrc
source ~/.bashrc

echo "✅ Flutter Build Fix 스크립트가 완전히 제거되었습니다."

🎉 마무리

이제 macOS에서 Flutter 빌드 에러로 고생할 일이 없어요!

한 줄 명령어로 모든 문제를 해결하고, 항상 최신 상태를 유지하며, 전문적인 개발 환경을 만들어보세요! 🚀

1
2
# 지금 바로 설치하세요!
curl -fsSL https://raw.githubusercontent.com/flutterkage2k/flutter-build-fix/main/install.sh -o install.sh && zsh install.sh

macOS Flutter 개발자를 위한 최고의 도구

Android와 iOS 앱을 모두 개발할 수 있는 macOS에서 최적화된 Flutter 개발 환경을 경험해보세요!