Next.js 정적 생성 운영 환경 점검 순서

Next.js 정적 생성(Static Generation)을 사용하면 빌드할 때 모든 페이지가 미리 생성되어 배포된다. 운영 중에 문제가 생기면 빌드를 다시 해야 새 콘텐츠가 반영된다. 그래서 정기적인 점검이 필요하다.

핵심 질문부터 시작

먼저 실제로 무엇이 문제인지 확인한다. 사용자가 보는 화면이 예전 버전인가? 일부 페이지만 문제인가? 모든 페이지가 문제인가?

제외할 원인 빠르게 찾기

모든 파일이 의심스러울 때는 우선순위를 정한다. 대부분의 경우 문제는 다음 중 하나다:

1. 캐시 (브라우저나 CDN)
2. 빌드 환경 변수
3. 데이터 소스 업데이트
4. 배포 설정

어느 것이 아닌지 빠르게 제외해본다.

재현 조건 확인

문제가 항상 발생하는지 특정 조건에서만 발생하는지 확인한다. 특정 경로, 특정 브라우저, 특정 네트워크 환경에서만 문제가 나는지 본다.

• 먼저 볼 값: 재현이 되는 정확한 조건
• 비교할 값: 정상일 때의 상태 (이전 버전, 다른 환경)
• 기록할 값: 명령 출력, 응답 코드, 설정

설정 확인 및 비교

현재 배포된 환경의 설정을 확인하고, 이전에 잘 작동했던 설정과 비교한다. next.config.js, .env.production, 빌드 스크립트 등이 변경되지 않았는지 본다.

빌드 결과물 확인

마지막 빌드가 성공했는지 확인한다. 일부 페이지만 생성되지 않았을 수 있다.

npm run build

사용자가 보는 모습과 개발자가 보는 신호

사용자 입장에서 보는 화면과 개발자가 로그에서 보는 신호가 같은 문제인지 다른 문제인지 구분한다.

• 사용자: 페이지가 이전 버전처럼 보여요
• 개발자: 빌드 로그에는 에러가 없고 최신 데이터가 생성되었네

이 경우 문제는 캐시나 배포 방식일 가능성이 높다.

예상되는 정상 상태

정상일 때 어떤 상태여야 하는지 정한다. 캐시 헤더는? 응답 시간은? 콘텐츠는?

다음 실제 확인 순서를 정한다:

1. 로컬에서 빌드해서 결과 확인
2. 배포 서버의 파일 시스템 확인
3. 네트워크 응답 확인
4. 브라우저 캐시 확인

비정상일 때 볼 곳

문제가 재현되면:

• 배포된 .next 디렉토리의 수정 시간
• CDN이나 리버스 프록시의 캐시 설정
• 환경 변수 값 (데이터 소스 URL 등)

한 번에 한 가지씩만 수정하고 결과를 확인한다. 여러 개를 동시에 바꾸면 뭐가 문제를 해결했는지 모른다.

운영 중 점검 기록을 남겨두면 같은 문제가 반복될 때 훨씬 빠르게 대응할 수 있다.