Flutter Build Fix 자동화 스크립트¶

마지막 업데이트: 2026-07-18
버전: v4.0.0 — Universal DSL Support
작성자: Heesung Jin (kage2k)

🖥️ 지원 플랫폼

macOS: 전체 지원 (Android + iOS)
Linux: Android 전용
Windows: 미지원 (WSL2 사용)

🎉 v4.0.0 주요 변경사항¶

무엇이 바뀌었나요?

✅ Universal DSL 지원: Kotlin DSL(Flutter 3.29+) / Groovy DSL(3.28 이하) 자동 감지
✅ Flutter 3.44.6 대응: DependencyVersionChecker 경고 기준 충족
✅ NDK & minSdk 위임: 값을 하드코딩하지 않고 Flutter에 위임
✅ Dry-run 미리보기: 변경 전 안전하게 결과 확인
✅ 자동 백업 & 롤백: 수정 전 모든 파일 백업
✅ 16KB 페이지 크기 지원: 최신 Android 기기 대응

flutter_build_fix 스크립트는 무엇인가?!¶

빠른 해결

Flutter 빌드 에러를 한 번에 해결하는 자동화 스크립트예요!
Gradle 버전, AGP 설정, Kotlin/Groovy DSL 감지, Java 설정, NDK 위임까지 모두 처리합니다.

🚀 원클릭 설치 (권장)¶

💫 원라인 설치¶

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

📊 현재 버전 정보¶

⚡ 사용법 (명령어 별칭)¶

설치가 끝나면 어느 Flutter 프로젝트 폴더에서든 아래 별칭을 바로 사용할 수 있어요.

자주 쓰는 명령어
flutter-fix    # 전체 정리 (Android + iOS)
ffand          # Android 전용
ffios          # iOS 전용 (macOS)
ff-full        # 전체 정리 (자동 모드)
ff-dry         # 변경사항 미리보기 (dry-run)
ff-auto        # 기본값으로 자동 실행

처음이라면 ff-dry 부터

실제로 파일을 바꾸기 전에 ff-dry 로 어떤 변경이 일어날지 먼저 확인하는 걸 추천해요.

🧩 프로젝트 호환성¶

스크립트가 프로젝트 유형을 자동으로 감지합니다.

Kotlin DSL (Flutter 3.29+)

settings.gradle.kts
build.gradle.kts
app/build.gradle.kts

Groovy DSL (Flutter 3.28 이하)

settings.gradle
build.gradle
app/build.gradle

지원 Flutter 버전¶

✅ Flutter 3.44.6 (최신 stable)
✅ Flutter 3.29+ (Kotlin DSL 프로젝트)
✅ Flutter 3.28 이하 (Groovy DSL 프로젝트)

🛠️ 설정 상세¶

적용되는 버전 (검증된 안정 버전)

Gradle: 8.14 (권장) — 8.14 / 8.13 / 8.12 / 8.11.1 지원
AGP: 8.11.1 — AGP 9의 파괴적 변경을 피하기 위해 8.x 유지
Kotlin: 2.2.20
Java: 17

이 값들은 Flutter 3.44.6의 DependencyVersionChecker 경고 기준(Gradle ≥ 8.14, AGP ≥ 8.11.1, Kotlin ≥ 2.2.20, Java ≥ 17)을 만족시켜 flutter analyze --suggestions 를 깨끗하게 유지합니다. 동시에 kotlin-android 플러그인을 제거하는 AGP 9는 의도적으로 피합니다.

16KB 페이지 크기 지원¶

Google Play는 최신 Android 기기를 위해 16KB 페이지 크기 지원을 요구합니다. Flutter 3.44.6부터는 번들 NDK(28.2.13676358+)가 16KB 호환 네이티브 코드를 자동으로 빌드해요.

NDK 버전: flutter.ndkVersion 에 위임 (하드코딩 없음)
이유: Flutter가 검증한 기본값을 따르면서 버전 충돌을 방지
마이그레이션: 오래된 NDK가 고정되어 있으면 flutter.ndkVersion 으로 되돌릴지 제안

💾 안전 장치 & 수정 대상¶

안전하게 동작합니다

✅ 자동 백업: 수정 전 모든 파일 백업
✅ Dry-run 모드: 적용 없이 미리보기
✅ 롤백 지원: 백업에서 손쉽게 복원
✅ 비파괴적: 설정 파일만 수정

수정되는 파일

android/
├── settings.gradle[.kts]          # 플러그인 버전
├── build.gradle[.kts]             # 루트 빌드 설정
├── app/build.gradle[.kts]         # 앱 레벨 설정
├── gradle.properties              # 빌드 최적화
├── local.properties               # Java 경로 설정
└── gradle/wrapper/
    └── gradle-wrapper.properties  # Gradle 버전

수정하지 않는 것: 소스 코드(.dart/.java/.kt), 에셋, pubspec.yaml 의존성, Git 설정, IDE 설정

🔄 업데이트 / 마이그레이션¶

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

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

v3.x → v4.0.0 마이그레이션¶

프로젝트 백업: git commit -am "Before flutter-fix v4.0.0"
설치 실행: 위 원라인 명령어 실행
미리보기: ff-dry 로 변경사항 확인
적용: flutter-fix
빌드 검증: flutter build apk --debug

자동 업데이트 알림

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

🚑 문제 해결¶

업데이트 후 빌드 실패

flutter clean
flutter pub get
flutter build apk --debug

Java 버전 문제

java -version   # Java 17 이상이어야 함
# 아니라면: brew install openjdk@17

Gradle 데몬 문제

./gradlew --stop
gradle --stop
# 이후 flutter-fix 다시 실행

NDK 못 찾음

Android Studio 열기
Tools → SDK Manager
SDK Tools 탭 → NDK (Side-by-side) 설치
Flutter가 요구하는 버전 설치 (flutter.ndkVersion, 현재 28.2.13676358)

🔗 GitHub Repository¶

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

GitHub Repository

참여하기¶

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

🎉 마무리¶

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

한 줄 명령어로 모든 문제를 해결하고, Kotlin/Groovy DSL을 자동으로 감지하며, 항상 최신 상태를 유지하는 개발 환경을 만들어보세요! 🚀

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

Flutter 3.44.6 Ready · AGP 8.x Safe · Universal DSL Support

macOS와 Linux에서 최적화된 Flutter 빌드 환경을 경험해보세요!