오래된 Flutter 프로젝트를 유지보수하다 보면 로컬에서는 정상적으로 실행되던 앱이 CI 빌드나 스토어 배포 단계에서 멈추는 일이 있습니다.
코드가 갑자기 틀린 것이 아닐 수 있습니다. 배포 환경에 필요한 값이 빠졌거나, 로컬과 CI가 서로 다른 환경변수를 사용하고 있을 가능성이 있습니다.
가장 먼저 확인할 것: 값이 어디에 있는가
환경변수와 비밀값을 저장소에 직접 넣어 관리하면 편해 보일 수 있습니다. 하지만 API 키나 서버 접속 정보처럼 외부에 노출되면 안 되는 값은 저장소와 분리해 배포 파이프라인에서 관리하는 편이 적절합니다.
핵심은 다음과 같습니다.
- 로컬 개발 환경에 필요한 값
- CI에서 빌드할 때 필요한 값
- 플레이버별로 달라지는 값
dart-define으로 전달되는 값- 서버 환경에 설정된 값
이 항목들이 서로 같은 기준으로 관리되고 있는지 확인해야 합니다.
Flutter 환경변수 점검표
1. 로컬 실행값을 먼저 정리합니다
개발자의 로컬 환경에서 어떤 값이 있어야 앱이 실행되는지 목록으로 만듭니다.
예를 들어 다음과 같은 항목을 확인할 수 있습니다.
- API 엔드포인트
- 개발·스테이징·운영 구분값
- 외부 서비스 연동에 필요한 설정값
dart-define으로 전달하는 값
이 단계에서는 값 자체를 저장소에 올리는 것이 아니라, 어떤 이름의 값이 필요한지 정리하는 것이 중요합니다.
2. CI 시크릿을 확인합니다
로컬에 있는 값이 CI에도 자동으로 전달된다고 가정하면 안 됩니다. CI에서 사용하는 시크릿과 환경변수 설정을 별도로 확인해야 합니다.
특히 다음을 대조해 보세요.
- 로컬 변수명과 CI 시크릿 이름이 같은가
- CI 빌드 명령에 필요한
dart-define값이 전달되는가 - 브랜치나 빌드 유형에 따라 다른 값이 필요한가
- 값이 비어 있을 때 빌드가 즉시 실패하도록 되어 있는가
CI에서 값이 빠지면 컴파일 단계, 앱 실행 단계, 또는 스토어 제출 전 단계에서 문제가 드러날 수 있습니다.
3. 플레이버별 설정을 대조합니다
개발, 스테이징, 운영처럼 플레이버를 나누어 사용하고 있다면 각 환경의 설정을 따로 확인해야 합니다.
한 플레이버에서는 존재하는 값이 다른 플레이버에서는 누락될 수 있습니다. 빌드 명령, 환경변수 이름, API 엔드포인트가 플레이버별로 일관되게 연결되어 있는지 살펴보세요.
4. dart-define 전달 방식을 확인합니다
Flutter 프로젝트에서 환경별 값을 dart-define으로 전달하는 경우, 로컬 실행 명령과 CI 빌드 명령이 같은 방식으로 구성되어 있는지 확인해야 합니다.
로컬에서는 개발자가 직접 옵션을 넣고 있었지만 CI에서는 해당 옵션이 빠져 있을 수 있습니다. 이 차이를 줄이려면 빌드 명령과 필요한 변수 목록을 문서화하고, 파이프라인에서 동일한 기준으로 검사하는 편이 좋습니다.
5. 서버 환경과 앱 설정을 함께 봅니다
앱에 전달되는 설정만 확인해서는 충분하지 않을 수 있습니다. 앱이 호출하는 서버의 환경변수와 엔드포인트도 함께 대조해야 합니다.
다음 질문을 순서대로 확인해 보세요.
- 앱이 호출하는 주소가 현재 서버 주소와 맞는가
- 서버에 필요한 환경변수가 설정되어 있는가
- 개발·스테이징·운영 서버가 혼동되지 않았는가
- 앱 빌드 설정과 서버 배포 설정의 환경 구분이 일치하는가
배포 실패를 반복하지 않으려면
환경변수 문제는 한 번의 수정으로 끝나지 않을 수 있습니다. 로컬, CI, 플레이버, dart-define, 서버 환경을 각각 따로 관리하면 같은 문제가 다시 발생하기 쉽습니다.
운영 관점에서는 다음과 같은 기준을 정해 두는 것이 도움이 됩니다.
- 필요한 변수 이름을 목록으로 관리합니다.
- 로컬과 CI의 전달 방식을 문서화합니다.
- 플레이버별 필수값을 구분합니다.
- 배포 전에 필수값 누락 여부를 확인합니다.
- 비밀값은 저장소와 분리합니다.
오래된 Flutter 프로젝트일수록 현재의 배포 방식과 과거의 설정 방식이 섞여 있을 수 있습니다. 이때는 특정 파일 하나만 수정하기보다 앱 빌드부터 CI, 서버 환경까지 연결해서 보는 것이 안전합니다.
환경변수 누락으로 배포가 멈췄다면 코드 수정 전에 환경 차이부터 확인해 보세요. Flutter 앱과 관리자 웹, API, 데이터베이스, 스토어 출시 과정이 어떻게 연결되어 있는지 함께 점검해야 원인을 좁힐 수 있습니다.
배포가 환경 차이에서 멈춘다면 진단부터 받아 보세요.
앱 상태 진단이 필요하면 www.universoft.kr/contact 로 문의하세요.