이전 목록으로
#Flutter#Shorebird

Flutter Shorebird 1편: Release와 Patch

작은 Dart 코드 하나를 고쳤는데 다시 스토어 심사를 기다려야 했다. Shorebird Release와 Patch의 차이, 패치 가능한 변경 범위, Android·iOS 기본 배포 명령어를 정리한다.

Shorebird 실전 시리즈 1/3 · 2편: Flavor·Track·QA 계정 구분

이 글은 2026년 10월 25일 Shorebird 공식 문서를 기준으로 명령과 정책을 확인했다. CLI 옵션은 변경될 수 있으므로 실제 배포 전 공식 문서를 함께 확인하자.

작은 버그 하나를 고쳤을 뿐인데 다시 빌드하고, 스토어에 올리고, 심사가 끝나고, 사용자가 업데이트하기를 기다려야 한다.

특히 현장 업무용 앱에서는 스캔 결과가 잘못 표시되거나 버튼 하나가 동작하지 않는 문제도 업무를 그대로 막는다. Dart 코드 몇 줄 고친 건데 좀 더 빨리 배포할 방법이 없을까 싶어서 Shorebird를 붙이게 됐다.

Shorebird는 Flutter 앱의 Dart 코드 변경사항을 OTA 방식으로 전달한다. 사용자가 스토어에서 새 버전을 직접 설치하지 않아도 패치를 내려받은 다음 앱 실행부터 수정된 코드를 사용할 수 있다.

여기까지만 보면 웬만한 수정은 전부 바로 보낼 수 있을 것 같았다. 그치만 Kotlin·Swift 같은 네이티브 코드와 Asset, Flutter 엔진 변경은 Patch 대상이 아니다.

Release와 Patch의 차이

처음 제일 헷갈렸던 건 Release와 Patch였다. 둘 다 Shorebird 서버에 무언가 올리는 명령처럼 보이지만 역할은 완전히 다르다.

구분 Release Patch
목적 패치의 기준이 되는 앱 바이너리 생성 기존 Release의 Dart 코드 수정
명령어 shorebird release shorebird patch
스토어 배포 필요 일반적으로 불필요
변경 범위 Dart·Asset·Native 포함 패치 가능한 Dart 코드
앱 버전 새로운 버전·빌드 번호 기존 Release 버전 유지
적용 시점 사용자가 새 앱을 설치한 뒤 다운로드 후 다음 앱 실행

shorebird release는 버전 번호만 등록하는 명령이 아니다. 실제 Flutter 빌드를 수행하고, 나중에 Patch와 비교할 기준 결과를 업로드한다.

여기서 만들어진 AAB나 IPA가 스토어에 자동 제출되는 건 아니다. Play Console과 App Store Connect 제출은 개발자가 따로 해야 한다.

shorebird patch는 현재 코드와 기존 Release를 비교해서 변경된 Dart 코드를 패치로 만든다. Release가 원본이고 Patch는 원본에 얹는 수정본이라고 생각하면 편했다.

flowchart TD
    A[Dart·Flutter 개발] --> B[Shorebird Release]
    B --> C[스토어 또는 사내 배포]
    C --> D[버그 발견]
    D --> E{Native·Asset 변경?}
    E -- 예 --> B
    E -- 아니오 --> F[Shorebird Patch]
    F --> G[패치 다운로드]
    G --> H[다음 실행부터 적용]

패치를 배포했는데 화면이 그대로인 이유

패치를 배포하고 앱을 켰는데 화면이 그대로여서 처음에는 실패한 줄 알았다.

기본 자동 업데이트는 앱 시작 시 백그라운드에서 패치를 확인하고 다운로드한다. 이미 Dart VM이 실행된 상태라 내려받은 패치를 현재 실행에 바로 끼워 넣지는 않는다.

다운로드한 패치는 다음 앱 실행부터 적용된다.

QA 중에는 다음 순서로 확인한다.

  1. 첫 번째 실행에서 패치를 확인하고 다운로드한다.
  2. 앱 프로세스를 완전히 종료한다.
  3. 두 번째 실행에서 패치 적용 결과를 확인한다.

홈 버튼만 눌렀다 돌아오는 건 앱 재실행이 아니다. 프로세스를 종료하고 다시 켜야 한다.

Patch로 보내기 좋은 변경

  • Flutter 화면과 위젯 코드 수정
  • 상태관리 로직 수정
  • API 요청·응답 처리 수정
  • 유효성 검사와 조건문 수정
  • Dart 비즈니스 로직 수정
  • 네이티브 변경이 없는 Dart 패키지 업데이트
  • Dart에서 생성되는 일부 Generated Code 수정

새로운 Release가 필요한 변경

  • Android Kotlin·Java 코드 변경
  • iOS Swift·Objective-C 코드 변경
  • AndroidManifest.xml, 권한, Gradle 설정 변경
  • iOS Entitlement, Capability, Pod 설정 변경
  • 이미지·폰트 등 Asset 추가와 제거
  • Flutter SDK 또는 엔진 버전 변경
  • 네이티브 구현이 포함된 플러그인 추가·업데이트
flowchart TD
    A[변경사항 확인] --> B{Native·빌드 설정 변경?}
    B -- 예 --> R[새 Release]
    B -- 아니오 --> C{Asset 추가·제거?}
    C -- 예 --> R
    C -- 아니오 --> D{Flutter 엔진 변경?}
    D -- 예 --> R
    D -- 아니오 --> P[Patch 가능]

검사에 막히면 --allow-native-diffs나 --allow-asset-diffs가 눈에 들어온다. 일단 붙이면 넘어갈 것 같아서 솔깃하다.

그치만 이 옵션은 해결이 아니라 “차이가 있다는 걸 알지만 진행하겠다”는 선언에 가깝다. 왜 차이가 생겼는지 설명할 수 없다면 새 Release를 만드는 편이 안전하다.

Shorebird 초기 설정

CLI 상태 확인

shorebird --version
shorebird doctor

뭔가 안 될 때는 shorebird doctor부터 실행한다. Shorebird가 사용하는 Flutter 버전과 개발 환경을 확인할 수 있다.

프로젝트 초기화

shorebird init

프로젝트 루트에 shorebird.yaml이 만들어지고 앱을 식별하는 app_id가 기록된다.

app_id: your-app-id

Stage와 Prod를 별도 앱으로 운영한다면 각 환경에 맞는 app_id를 사용해야 한다. 화면에 Stage라고 적혀 있어도 Shorebird는 app_id로 앱을 구분한다.

Android Release와 Patch

Play Store용 AAB

shorebird release android

사내 배포용 APK

shorebird release android --artifact apk

Flutter 버전 지정

shorebird release android --flutter-version 3.47.7

Shorebird CLI 1.6.123 이상에서는 FVM이나 시스템 Flutter 버전을 따라가도록 별칭도 사용할 수 있다.

shorebird release android --flutter-version=fvm
shorebird release android --flutter-version=system

별칭은 버전 번호를 해석하는 용도다. 실제 빌드는 해당 버전의 Shorebird Flutter로 수행된다.

Patch 생성

shorebird patch android --release-version 1.0.0+1
shorebird patch android --release-version latest

latest는 편하지만 운영에서는 대상 버전을 직접 적는 편이 낫다. 여러 Release가 살아 있으면 CLI가 고른 최신 버전과 내가 생각한 대상이 다를 수 있다.

iOS Release와 Patch

shorebird release ios
shorebird patch ios --release-version 1.0.0+1

수동 서명이나 Ad Hoc 배포를 사용하는 프로젝트는 ExportOptions.plist가 필요할 수 있다.

shorebird release ios \
  --export-options-plist ios/ExportOptions.plist

Runner.app requires a provisioning profile 오류가 발생하면 다음 항목을 확인한다.

  • 테스트 기기 UDID가 Apple Developer에 등록되어 있는가?
  • Provisioning Profile에 해당 기기가 포함되어 있는가?
  • Bundle ID와 Profile의 App ID가 일치하는가?
  • 현재 Mac에 인증서와 Private Key가 존재하는가?
  • ExportOptions.plist의 Team ID와 Profile 이름이 맞는가?

Release 전 체크리스트

  • 앱 버전과 빌드 번호를 올렸다.
  • shorebird doctor 결과를 확인했다.
  • Android·iOS 서명 설정을 확인했다.
  • Release Artifact를 실제 기기에서 실행했다.
  • pubspec.lock을 커밋했다.
  • 생성된 AAB·APK·IPA를 배포할 위치를 확인했다.

마무리

Shorebird를 처음 적용할 때는 Patch 명령부터 보고 싶었다. 실제로는 기준이 되는 Release를 어떻게 만들었는지가 더 중요했다.

Release와 Patch의 Flavor, Target, Flutter 버전과 의존성이 같아야 한다. 이 기준이 흔들리면 패치가 안 내려오거나 Native Changes 경고로 다시 만나게 된다.

다음 편에서는 Stage·Prod Flavor와 Track이 어떻게 다른지, QA 계정만 먼저 패치를 받게 하려면 어떻게 해야 하는지 정리한다.

관련 문서

목록으로 돌아가기

다른 게시글

#Android#Flutter

현장 Flutter 앱 디버깅에 자주 쓴 ADB 명령어

기기 지정, Logcat, APK 설치, 파일 복사, 포트 reverse를 실기기 점검 흐름으로 정리한다.

#Android#Kotlin

Android 입력 장치 목록 조회하기: 키보드·마우스·HID 스캐너 구분

Android `InputManager`와 `InputDevice` API로 연결된 입력 장치를 조회하고, 키보드·포인터·외부 장치 여부를 판별하는 방법을 정리한다. USB·Bluetooth HID 바코드 스캐너를 일반 키보드와 구분할 때의 한계와 연결 변경 감지 방법도 함께 살펴본다.

#Android#Kotlin

Android 위치 권한과 FusedLocationProvider 실전 정리: 현재 위치·지속 추적·GPS 설정

Jetpack Compose 앱에서 Android 위치 권한을 요청하고, Fused Location Provider로 캐시 위치·일회성 현재 위치·지속 위치 업데이트를 처리하는 흐름을 정리한다. Android 12의 대략적·정확한 위치 선택, 백그라운드 위치 정책, GPS 설정 확인과 생명주기 연동까지 예제 코드로 살펴본다.