운영 보험 서비스 SSR 빌드 불일치 원인 수정

운영 환경에서 insurance.service entry 파일과 로컬 빌드 결과물이 맞지 않는다는 게 감지됐다. 원인을 따라가 보니 Astro 설정에서 렌더링 모드가 잘못 잡혀 있었음.

배경 — entry.mjs 불일치가 왜 문제냐

Astro는 output 모드에 따라 빌드 결과물 구조가 달라진다. static 모드면 순수 HTML/CSS/JS로 뽑히고, server(SSR) 모드면 Node 서버에서 실행되는 entry.mjs 가 생성된다. 운영 인프라가 entry.mjs를 직접 구동하는 구조라면 반드시 SSR 빌드 결과물이 나와야 한다.

그런데 어느 순간부터 로컬에서 빌드한 결과물에 entry.mjs가 없거나 위치가 달랐던 것. 운영 서버가 기대하는 파일 경로와 실제 빌드 아티팩트가 어긋나면, 배포는 성공했는데 서비스가 뜨지 않는 최악의 케이스로 이어진다. "빌드는 됐는데 왜 안 뜨지?" 류의 이슈는 항상 팀 전체를 소모하는 디버깅 시간을 만든다.

이번 수정은 결국 astro.config.mjs에서 output 모드를 명시적으로 server로 고정하고, 의존성 변경 사항이 package.json / package-lock.json에 반영된 구조다.

변경 내용

핵심은 astro.config.mjs 한 줄이다. 나머지 두 파일은 그 변경에 따라 자연스럽게 따라온 것.

// astro.config.mjs (변경 후)
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';

export default defineConfig({
  output: 'server',          // 명시적으로 SSR 고정
  adapter: node({
    mode: 'standalone',
  }),
});

output 값을 명시하지 않으면 Astro 버전이나 플러그인 조합에 따라 기본값이 달라질 수 있다. 특히 Astro가 버전업되면서 기본 동작이 조용히 바뀐 사례가 있어서, 인프라와 맞닿아 있는 설정일수록 명시 > 암묵 원칙을 지키는 게 맞다.

회고 — 운영 entry와 빌드 결과물 동기화

이런 이슈가 생기는 패턴을 보면 대부분 세 가지 중 하나다.

• 프레임워크 버전업 과정에서 기본값이 바뀌었는데 config를 건드리지 않은 경우
• 누군가 로컬에서 빠르게 테스트하려고 static 모드로 돌려봤다가 커밋에 섞여 들어간 경우
• 신규 팀원이 세팅 가이드 없이 config를 복붙하다가 잘못된 옵션을 가져온 경우

세 번째가 팀 리딩 관점에서 제일 아프다. 이 부분은 README나 온보딩 문서에 "이 서비스는 반드시 SSR 모드로 빌드되어야 하며, entry.mjs가 운영 인프라 구동 파일임" 같은 문장 한 줄이 있었다면 사전에 막을 수 있었던 이슈다. 코드리뷰 단계에서 astro.config.mjs 변경이 올라왔을 때 output 모드를 확인하는 체크포인트를 팀 룰에 넣기로 했다.

그리고 package-lock.json이 함께 바뀌었다는 건 어댑터 패키지 변경도 같이 일어났다는 신호다. lock 파일 변경은 리뷰에서 흘려보내기 쉬운데, 의존성 트리가 바뀌는 PR에서는 "왜 이 패키지 버전이 올라갔냐"를 한 번쯤 확인하는 습관이 있어야 한다. 특히 운영 서버가 특정 Node 버전이나 어댑터 버전에 맞춰 세팅돼 있다면, lock 파일 변경이 배포 실패로 직결될 수 있다.

작은 config 수정처럼 보이지만 운영 빌드 파이프라인 전체를 다시 신뢰할 수 있게 만든 작업이었다. 이런 핀포인트 수정일수록 커밋 메시지에 "왜" 를 남겨두는 게 나중에 팀원들한테 도움이 된다. (운영 insurance.service entry.mjs 일치) 라는 괄호 안 메모가 실제로 그 역할을 한다.

끝.

🛒 이 글과 어울리는 추천 상품

• 외장SSD 쿠팡에서 보기 →
• 모니터 쿠팡에서 보기 →
• 기계식키보드 쿠팡에서 보기 →

*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.