목차
카페인 중독 신규 앱 출시를 준비하면서 QC를 진행하고 있었다. 수정 사항을 반영하느라 웹을 자주 배포했는데, 그 과정에서 앱을 켜 둔 채 다른 화면으로 이동하면 오류 화면이 나타나는 문제를 발견했다.
이 앱은 React와 TypeScript로 만든 웹을 iOS·Android 앱의 WebView에서 보여주는 구조다. 웹은 Vite로 빌드하고, Stackflow로 화면 이동과 화면 스택을 관리한다. 화면 코드는 React.lazy로 나눠 두어서, 필요한 화면을 열 때 해당 JS 파일을 불러온다.
웹을 새로 배포해도 이미 열려 있는 웹뷰는 이전 코드를 실행하고 있다. 그러다 아직 열지 않았던 화면으로 이동하면, 이전 빌드의 해시가 붙은 JS 파일을 요청한다. 서비스 주소가 새 배포를 바라보는 동안 그 주소에서 이전 청크를 더 이상 제공하지 않으면, 해당 화면의 코드를 가져오지 못할 수 있다. Vite 공식 문서에도 이 배포 상황이 설명돼 있다. Vite 7 — Load Error Handling
SPA rewrite 설정에 따라서는 JS 요청에 404 대신 HTML이 돌아오기도 한다. 응답이 200이라고 해도 화면 코드로 실행할 수는 없다. 다만 청크를 불러오지 못했다는 사실만으로 모든 장애를 재배포 탓으로 볼 수는 없었다. 이번에는 이 버전 불일치에 대비하는 복구 로직을 웹에 추가했다. Vercel 설정과 네이티브 앱은 변경하지 않았다.

새로고침부터 하면 곤란한 화면이 있었다
오류를 잡아서 location.reload()를 호출하면 간단해 보인다. 그런데 이 웹뷰 안에서는 결제와 PASS 본인인증, 회원가입도 진행한다. 사용자가 입력하거나 인증을 마치고 돌아오는 중에 문서 전체를 다시 읽어도 되는지는 별개의 문제였다.
지금 보고 있는 화면이 정상인 경우도 있다. 다음 화면을 미리 불러오는 프리패치만 실패했는데, 전역 오류 이벤트에서 새로고침하면 정상 화면까지 영향을 받는다.
그래서 복구를 두 단계로 나눴다. 전역 이벤트에서는 오류를 분류하고, 실제로 실패한 화면에서 새로고침할 수 있는지 판단한다. 일반 탐색 화면은 조건을 확인해 한 번만 자동 복구하고, 결제·인증·가입 흐름은 건드리지 않기로 했다.
이벤트에서는 오류 객체만 기록했다
Vite는 동적 import 로딩에 실패하면 vite:preloadError 이벤트를 발생시킨다. event.payload에는 원래 오류가 들어 있다. 이 객체를 WeakSet에 기록해 두고, 나중에 화면에서 받은 오류와 비교했다. Vite 7 공식 문서
리스너의 핵심 구현은 다음과 같다.
앱 부트스트랩에서 등록하고 HMR dispose 시 해제한다. 이 안에서는 새로고침도, event.preventDefault()도 호출하지 않는다.
preventDefault()를 생략한 데에는 이유가 있다. Vite 7의 preload helper는 원본 오류를 이벤트로 전달한 뒤, 이벤트가 취소되지 않았으면 그 오류를 다시 던진다. 실제 동적 import 실패를 처리하는 baseModule().catch(handlePreloadError) 경로에서는, 예외를 막으면 handler의 반환값인 undefined로 Promise가 이행될 수 있다. Vite v7.0.0 구현
이 프로젝트는 그 Promise를 React.lazy로 연결한다. lazy는 유효한 컴포넌트를 담은 default export를 기대하므로, undefined를 전달하면 원래 import 실패 대신 다른 오류가 생길 수 있다. 원래 rejection이 ErrorBoundary까지 가도록 두는 편이 이 구조에 맞았다. Vite가 제공하는 preventDefault() 자체가 잘못된 것은 아니다. 여기서는 오류 전파를 유지해야 해서 사용하지 않았다. React — lazy
오류 판별은 먼저 WeakSet에 기록된 객체인지 확인한다. 기록이 없을 때만 Chrome·Safari의 알려진 동적 import 오류 메시지를 보조적으로 확인한다. 일반 API 요청의 Failed to fetch나 임의의 렌더링 오류까지 같은 오류로 묶지는 않았다. 이 기록은 import 경로에서 온 오류라는 단서로 쓰고, 새 배포인지는 별도로 확인한다.
실제로 실패한 화면에서 복구를 시작했다
복구 판단은 현재 렌더링 중인 화면의 ErrorBoundary에서 시작한다. Stackflow에 보관된 비활성 화면은 복구를 시작하지 않는다. 프리패치 실패만으로도 시작하지 않는다. 일반 런타임 오류는 기존 오류 처리에 맡긴다.
공용 ErrorBoundary 안에 라우터나 인증 규칙을 넣지는 않았다. renderError 콜백으로 복구 UI를 외부에서 주입했다. ErrorBoundary는 렌더링 오류를 받고, 화면 쪽에서 활성 여부와 보호 흐름을 판단하도록 책임을 나눴다.
수동 재시도도 함께 정리했다. React.lazy는 Promise와 그 결과를 기억한다. 같은 lazy 인스턴스를 다시 렌더링하는 것만으로 로더가 다시 실행되지는 않는다. 화면 로더에서 import 실패 시 새 lazy 인스턴스를 준비해, 다음 진입이나 사용자가 누른 ‘다시 시도’에 사용했다. React 공식 문서
여기서 재시도하는 것은 화면 코드를 불러오는 경로다. 결제나 인증 API를 재전송하는 기능은 아니다. 새 lazy 인스턴스를 만들었다고 브라우저의 모듈 캐시가 지워지거나 로딩 성공이 보장되는 것도 아니다.
새 배포인지 확인하고, 화면 상태도 다시 확인했다
새로고침 전에 실행 중인 웹과 서버의 배포 버전을 비교했다. 빌드할 때 작은 Vite 플러그인에서 UUID 하나를 만들고, 같은 값을 웹 코드의 import.meta.env.APP_BUILD_VERSION과 배포 파일 /app-version.json에 넣었다.
APP_BUILD_VERSION은 Vite가 기본으로 제공하는 값이 아니라 직접 주입한 빌드 식별자다. 인증 토큰처럼 숨겨야 하는 값도 아니다. 두 곳에 적힌 값이 같은 빌드인지 비교하는 데만 쓴다.
버전 파일은 cache: 'no-store', credentials: 'omit'으로 조회하고, AbortController로 최대 5초까지만 기다리도록 했다. 응답은 unknown으로 받아 Zod로 검사한다. HTML이나 잘못된 JSON이 오거나, 요청이 실패하거나, 실행 중인 버전과 같으면 자동 새로고침하지 않는다.
새 버전이 확인돼도 바로 새로고침하지는 않는다. 조회를 기다리는 동안 사용자가 다른 화면으로 이동할 수 있기 때문이다. 요청 전과 같은 URL·활성 화면인지, 보호 흐름으로 들어가지 않았는지 다시 확인한다. 화면이 여전히 활성 상태이고 온라인이며 문서가 보이는지도 확인한다. 화면이 바뀌거나 컴포넌트가 해제되면 진행하던 복구를 취소한다.
약관 화면이라고 항상 안전한 것은 아니었다
자동 복구는 일반 탐색 화면의 허용 목록으로 관리했다. 새 화면을 추가해도 목록에 등록하기 전에는 자동 복구 대상이 되지 않는다. 결제·PG·PASS·로그인·회원가입·닉네임 입력·인증 복귀 화면과 작성 중인 폼은 보수적으로 보호했다.
현재 URL만 보면 놓치는 경우가 있었다. 회원가입 화면에서 약관을 열면 URL은 약관 화면이어도, 그 아래에는 진행 중인 가입 화면이 남아 있다. 약관을 일반 화면으로 보고 새로고침하면 가입 흐름에도 영향을 준다.
그래서 Stackflow의 화면 스택 전체를 확인했다. 아래에 결제나 가입 화면이 남아 있다면, 위에 열린 약관이나 혜택 화면에서도 새로고침하지 않는다. 완전히 종료된 exit-done 화면은 이 검사에서 제외했다.
자동 복구는 세션당 한 번으로 제한했다
새로고침했는데 같은 오류가 다시 나면 또 새로고침할 수 있다. 이를 막으려고 sessionStorage에 자동 복구 시도 기록을 남겼다. 이 저장소는 페이지 세션 동안 유지되고 새로고침을 거쳐도 남는다. 여기서 말하는 세션은 로그인 세션이 아니라 같은 탭·WebView의 페이지 세션이다. MDN — sessionStorage
먼저 기존 시도 기록을 확인한다. 기록이 없으면 새 배포인지 조회하고, 조회가 끝난 뒤 화면·URL·네트워크 상태와 시도 기록을 다시 확인한다. 그다음 새로고침하기 전에 기록을 저장하고, 저장된 값까지 읽어 확인한다.
아래는 마지막 단계만 설명하려고 재구성한 코드다. 키 이름과 저장값은 예시이며, 버전 조회·요청 취소·복구 UI는 생략했다. isStillSafe는 조회를 시작한 URL과 활성 화면, 화면 스택, 온라인·표시 상태와 취소 여부를 다시 확인하는 함수를 뜻한다.
최종 확인과 기록 사이에 await를 두지 않아 같은 문서의 여러 오류가 동시에 복구를 시도해도 먼저 남긴 기록을 확인하게 했다. 새로고침했거나 빌드가 바뀌었다는 이유로 기록을 지우지도 않는다. 같은 페이지 세션에서 자동 복구를 반복하지 않기 위해서다.
저장소를 사용할 수 없거나 기록을 남기지 못하면 자동 복구를 하지 않는다. 이 경우에는 새로고침이 반복되는 것보다 오류 안내를 보여주는 편을 택했다.
일반 화면에서는 조건을 만족하면 로딩 표시 후 현재 주소에서 한 번 새로고침한다. 조건이 맞지 않으면 오류 안내와 화면 코드 재시도를 제공한다. 보호 화면은 자동 새로고침 없이 입력·결제·인증을 보호하고 있다는 안내와 이전 화면으로 돌아가는 선택을 보여준다. 자동으로 홈으로 보내거나 인증 정보·장바구니를 삭제하지는 않는다.
복구되는 경우만큼, 멈추는 경우도 확인했다
단위 테스트와 React 통합 테스트에서는 새 버전일 때 복구하는지뿐 아니라, 복구하지 않아야 할 조건을 함께 확인했다.
| 확인한 상황 | 기대한 처리 |
|---|---|
| 같은 버전, 잘못된 응답, 조회 시간 초과 | 자동 새로고침하지 않음 |
| 새 버전, 안전한 활성 화면 | 한 번 복구하고 새 문서에서도 시도 기록 유지 |
| 동시 오류, StrictMode의 effect 정리·재실행 | 중복 복구 차단 |
| 오프라인, 백그라운드, 저장소 사용 불가 | 자동 복구 중단 |
| 조회 중 화면 이동, 결제·가입 화면 위의 약관 | 복구 취소 또는 보호 흐름으로 처리 |
| 비활성 화면, 프리패치 실패, 일반 렌더링 오류 | 자동 복구를 시작하지 않음 |
| 실제 lazy 화면의 로딩 실패와 명시적 재시도 | 화면 코드 재시도 경로 확인 |
타입 검사와 린트, 프로덕션 빌드도 확인했다. 실제 기기에서 결제나 PASS 인증을 수행하는 E2E까지 진행한 것은 아니다.
마무리
이번 작업으로 서버가 이전 배포 파일을 유지하는 전략까지 대신할 수는 없다. 최초 엔트리 JS부터 로드되지 않으면 이 복구 코드도 실행되지 않는다. 일반 화면을 새로고침하더라도 메모리에만 있던 상태나 스크롤 위치는 초기화될 수 있다.
적용 시점도 한계다. 이미 실행 중인 예전 웹에 새 오류 처리 코드를 끼워 넣을 수는 없다. 이 수정이 들어간 웹을 한 번 로드한 사용자부터 이후 재배포에서 복구 로직을 사용할 수 있다.
결국 손이 많이 간 부분은 reload()를 호출하는 코드보다, 호출하면 안 되는 조건을 정하는 쪽이었다. 프리패치가 실패했다고 정상 화면을 새로고침하지 않기, 약관 아래에 남은 가입 화면을 확인하기, 시도 기록을 저장하지 못하면 멈추기. 자동으로 복구하는 범위는 좁아졌지만, 사용자가 진행하던 일을 유지하는 쪽으로 선택했다.
이번 QC를 하면서 웹 배포도 좀 더 주의해야겠다는 생각이 들었다. 수정한 코드를 바로 배포할 수 있는 건 편하지만, 이미 앱을 켜 둔 사람에게는 이전 화면과 코드가 남아 있다. 새 버전이 잘 뜨는지 확인하는 것뿐 아니라, 배포 전부터 열려 있던 앱에서도 화면을 계속 오갈 수 있는지 함께 봐야겠다고 느꼈다.
