Next.js 머니 충전 서비스 개발: CORS와 Version Skew 장애 극복기

핵심 기술

본 글은 Next.js v13 (Pages Router) 기반의 SSR 서비스에서 프론트엔드 개발 시 겪을 수 있는 CORS 에러와 Version Skew 문제의 근본 원인을 분석하고, 실제 장애 상황에서의 해결 과정을 상세히 공유합니다. 특히, 브라우저 캐싱과 HTTP 요청 헤더의 상호작용, 그리고 배포 전략의 중요성을 강조합니다.

기술적 세부사항

• 서비스 개요: 카카오페이에 연결된 계좌 잔액을 카카오페이 머니로 충전하는 웹뷰 서비스
• 개발 환경: Next.js v13 (Pages Router), SSR (Server-Side Rendering)
• 주요 장애 1 (CORS):
  • 증상: 배포 직후 Sentry 에러 알람 폭발, Failed to load static props 메시지
  • 원인: Next.js client-side navigation 시 fetch API를 통한 CSS 리소스 요청 시 CORS 에러 발생.
    • SSR 초기 렌더링 시 <link rel='stylesheet'> 태그 요청은 CORS가 아니지만, client-side navigation 시 fetch API 사용으로 Origin 헤더가 포함되며 CORS 요청이 됨.
    • 브라우저의 잘못된 캐싱: Origin 헤더가 없는 응답과 Origin 헤더가 있는 요청 간의 캐시 불일치.
  • 해결 방안 검토 및 적용:
    1. Vary: Origin 헤더 사용 (CDN 서버 수정 필요하여 보류)
    2. next.config.js의 crossOrigin: 'anonymous' 옵션 사용 (다른 서비스 사이드 이펙트 우려로 처음엔 보류, 이후 다른 서비스 스타일 깨짐 현상 발생으로 제거 → 새로운 CORS 에러 유발)
    3. dynamic import를 이용한 지연 로딩 (CSR로 전환하여 CORS 요청 자체 회피)
• 주요 장애 2 (Version Skew):
  • 증상: 클라이언트 앱 릴리즈 후 404 에러 발생, 특히 카나리(Canary) 배포 단계에서 빈번하게 발생.
  • 원인: 롤링(Rolling) 배포 시 구버전 서버와 신버전 서버가 공존하며 사용자 요청이 분기될 때 발생.
    • SSR 서비스에서 특정 페이지(진입점 등)가 배포되지 않은 상태에서 요청이 발생하거나, 페이지 이동 시 버전 불일치로 인해 에러 발생.
  • 재현 경로: 안드로이드 웹뷰 환경에서 브라우저 프로세스 종료 후 새로 시작하여 진입하는 경우.
  • 해결 방안: 카나리 배포 비율 최소화 (1%로 설정), 블루 그린 배포 도입으로 롤백 안정성 확보.
• 심리적 측면: 처음 겪는 운영 장애에 대한 당황, 촉박한 일정 속에서의 문제 해결 압박, 심리적 무력감과 자책감.
• 일정 및 배포 전략: 코드 프리징 기간 준수, 카나리 및 블루 그린 배포 도입.

개발 임팩트

이 글은 Next.js SSR 환경에서 발생할 수 있는 복잡한 네트워크 에러(CORS)와 배포 과정에서의 버전 관리 문제(Version Skew)에 대한 실질적인 해결책을 제공합니다. 실제 장애 사례를 통해 문제 해결 능력 향상과 안정적인 서비스 운영을 위한 배포 전략의 중요성을 배울 수 있습니다. 또한, 예상치 못한 문제 발생 시 심리적 압박을 관리하고 효율적으로 해결하는 방법론을 간접적으로 경험할 수 있습니다.