🐛 CocoaPods 1.16.2 + Ruby 4.0.3 UTF-8 인코딩 버그 — `pod install` 즉사

일자: 2026-05-18 기기: 🏭 Mac mini (macOS arm64), homebrew Ruby 4.0.3, CocoaPods 1.16.2_2 상황: 메모요 1.0.5+22 release build 1차 사이클 중 pod install 실행 시 즉사 해결됨: ✅

증상

cd ios && pod install 실행 시 stacktrace 와 함께 즉사:

/opt/homebrew/Cellar/ruby/4.0.3/lib/ruby/4.0.0/unicode_normalize/normalize.rb:153:in 'UnicodeNormalize.normalize':
Unicode Normalization not appropriate for ASCII-8BIT (Encoding::CompatibilityError)
    from /opt/homebrew/Cellar/cocoapods/1.16.2_2/libexec/gems/cocoapods-1.16.2/lib/cocoapods/config.rb:167:in 'String#unicode_normalize'
    from /opt/homebrew/Cellar/cocoapods/1.16.2_2/libexec/gems/cocoapods-1.16.2/lib/cocoapods/config.rb:167:in 'Pod::Config#installation_root'
    from /opt/homebrew/Cellar/cocoapods/1.16.2_2/libexec/gems/cocoapods-1.16.2/lib/cocoapods/config.rb:227:in 'Pod::Config#podfile_path'
    ...

원인

Ruby 4.0 의 String#unicode_normalize 는 인코딩이 ASCII-8BIT 인 문자열을 정규화 불가. CocoaPods 1.16.2 의 Pod::Config#installation_root 가 현재 디렉토리 경로 (pwd) 를 String#unicode_normalize(:nfc) 으로 정규화하려 시도하는데, LANG/LC_ALL 환경변수가 비어있거나 ASCII 류로 설정되면 Ruby 가 경로 문자열을 ASCII-8BIT 으로 받음 → 정규화 호출 즉시 Encoding::CompatibilityError.

Claude Code shell 환경은 LANG 을 명시 setup 하지 않아 (또는 C / POSIX 디폴트) ASCII-8BIT 으로 문자열이 들어옴.

해결

LANG + LC_ALL 환경변수를 en_US.UTF-8 로 명시:

LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8 pod install

flutter build ipa 도 내부적으로 pod install 호출하므로 동일 환경변수 prefix 필요:

LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8 flutter build ipa --release --export-method app-store

재발 가능 범위

모든 Flutter iOS 앱 빌드 (포모도로, 로또, 한줄일기, 단어요, 메모요 등) — pod install 또는 flutter build ipa 호출하는 모든 워크플로우
submit-app 스킬의 iOS 빌드 단계 — 환경변수 prefix 누락 시 즉사
night-builder v2 launchd 워커 — 환경변수 inherit 여부 확인 필요 (launchd 는 GUI 세션의 LANG 안 받음, plist 에 EnvironmentVariables 박아야 함)

재발 방지 체크리스트

submit-app 스킬의 iOS build step 에 LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8 prefix 명시
night-builder v2 plist 에 <key>EnvironmentVariables</key><dict><key>LANG</key><string>en_US.UTF-8</string><key>LC_ALL</key><string>en_US.UTF-8</string></dict> 박혀있는지 확인
다른 앱 빌드 directive 작성 시 환경변수 prefix 명시 (또는 pod install 래퍼 스크립트 만들어 envar 강제)
장기적으로 homebrew Ruby 업그레이드 또는 cocoapods 1.16.3+ 출시 시 본 버그 fix 확인 후 환경변수 prefix 제거 검토