플러터 앱 빌드 환경을 초반에 통일해 온보딩 비용 줄이기

플러터 프로젝트 초기 셋업 / 환경 구성 작업을 정리했다.

왜 이 타이밍에 scaffolding + 빌드 설정을 한 번에 묶었나

새 앱 프로젝트를 시작할 때 제일 흔히 생기는 패턴이 있다. "일단 코드부터 짜자"는 분위기에 밀려 빌드 환경 설정이 뒤로 밀리고, 나중에 팀원들이 각자 로컬에서 빌드를 처음 돌릴 때마다 제각각 에러를 만나서 슬랙이 시끄러워지는 것. 이번엔 그 흐름을 미리 끊고 싶었다. flutter scaffolding 구조를 잡으면서 iOS Podfile, Android gradle.properties, Xcode xcconfig까지 한 커밋에 묶어서 "이 레포 클론하면 바로 빌드된다"는 상태를 초반에 확보하는 게 목표였음.

팀장 포지션에서 이 작업을 내가 직접 하는 이유가 있다. 빌드 환경 설정은 "아무나 나중에 해도 되는 일"처럼 보이지만, 한 번 꼬이면 팀 전체의 온보딩 비용이 올라가고 CI 파이프라인까지 영향이 간다. 초반에 기준선을 잡아두는 게 뒤에서 수습하는 것보다 훨씬 싸다.

변경 파일별로 뭘 건드렸나

파일 목록만 봐도 이번 커밋이 얼마나 크로스 플랫폼 전반을 건드렸는지 보인다. iOS 쪽만 5개 파일이고 Android도 gradle.properties까지. 코드 변경량 자체는 크지 않더라도 "영향 범위"는 프로젝트 빌드 전체에 걸쳐 있다.

gradle 메모리 조정 — 왜 초반에 잡아야 하나

gradle.properties에서 JVM 힙 메모리를 건드리는 건 아주 흔한 작업인데, 타이밍이 중요하다.

# android/gradle.properties
org.gradle.jvmargs=-Xmx4096m -XX:MaxMetaspaceSize=512m
org.gradle.parallel=true
android.useAndroidX=true
android.enableJetifier=true

이걸 초반에 안 잡으면 팀원 로컬 환경에 따라 빌드 중 OOM이 뜨거나, 빌드 시간이 들쭉날쭉 해진다. 특히 M1/M2 맥북 쓰는 팀원이랑 인텔 맥 / Windows 팀원이 섞여 있을 때 기본값으로는 누군가 반드시 문제를 만남. 미리 팀 빌드 환경 기준값을 커밋에 박아두는 게 "묵시적 합의" 역할을 한다.

Podfile + Podfile.lock을 같이 커밋하는 이유

이건 팀 내에서 종종 논쟁이 생기는 주제다. Podfile.lock을 .gitignore에 넣어야 하냐 말아야 하냐. 내 입장은 명확하다 — 앱 레포는 Podfile.lock을 커밋해야 한다.

• 라이브러리 버전 고정 → 팀원 전원이 동일한 Pod 버전으로 빌드
• CI/CD 파이프라인에서 pod install 시 재현성 확보
• 버전 drift로 인한 "내 로컬에서는 됐는데" 방지

라이브러리 레포라면 얘기가 다르지만, 앱 프로젝트에서 Podfile.lock을 빠뜨리는 건 package-lock.json 없이 npm 프로젝트 공유하는 것과 같다.

# ios/Podfile 핵심 구조 예시
platform :ios, '13.0'

target 'Runner' do
  use_frameworks!
  use_modular_headers!

  flutter_install_all_ios_pods File.dirname(File.realpath(__FILE__))
end

플랫폼 최소 버전 선언, flutter_install_all_ios_pods 연결 — 이게 제대로 안 잡히면 Flutter 플러그인들이 Xcode 빌드에서 못 잡힘.

회고

scaffolding 커밋은 드라마틱한 코드 변경이 없어서 PR 리뷰에서 가볍게 넘어가는 경향이 있다. 근데 팀장 입장에서 이 커밋이 가장 꼼꼼하게 봐야 할 커밋 중 하나라고 생각한다. 여기서 기준이 잘못 잡히면 이후 수십 개의 커밋이 그 위에 쌓이고, 나중에 고치려면 모든 팀원의 로컬 환경을 건드려야 한다.

빌드 환경 설정 커밋은 "지루하지만 제일 비싼 기술 부채 예방"이다.

다음은 CI 파이프라인 연결.