하루 2번 자동 발행 블로그에서 열어둔 탭이 ChunkLoadError를 내는 이유

라이프케어로그 블로그는 하루 2번, 12시간 간격으로 글이 자동 발행돼요. 글이 올라갈 때마다 빌드와 배포가 같이 돌죠. 이 파이프라인을 만들어 보니 편한 만큼 부작용도 하나 따라왔어요. 아침에 열어둔 탭을 저녁에 다시 보면 링크를 누르는 순간 화면이 하얘지고, 콘솔엔 ChunkLoadError가 찍혀요.

원인은 파일 이름이에요

Next.js로 빌드하면 자바스크립트가 여러 조각(chunk)으로 나뉘고, 각 파일 이름에 내용 해시가 붙어요. 열어둔 탭은 아침 빌드의 해시가 적힌 HTML을 들고 있어요. 그런데 저녁 빌드가 올라가면 서버에는 새 해시 파일만 남죠. 탭 안에서 링크를 누르면 라우터가 아침 해시로 된 조각을 요청하고, 서버는 404를 돌려주고, 그게 ChunkLoadError로 터지는 거예요.

하루 1번 배포하는 사이트라면 운 나쁜 사람만 겪어요. 2번이면 오래 열어둔 탭은 거의 다 걸려요. 플랜씨처럼 로그인 없이 계산기를 켜두고 종일 쓰는 화면이라면 더 민감한 문제고요.

로컬에서 재현하기

직접 재현해 보니 4단계면 충분했어요. 빌드 후 서버를 띄우고, 브라우저 탭을 하나 열어둔 다음, 컴포넌트 한 줄을 바꿔 다시 빌드하고 서버를 재시작해요. 그 탭에서 내부 링크를 누르면 바로 에러가 나요. 10분 정도 걸렸고, 네트워크 탭엔 옛 해시 파일이 404로 빨갛게 남아 있어요.

처리: error.tsx에서 1회만 새로고침

가장 작은 수정은 에러 바운더리에서 잡아 전체 새로고침을 한 번 하는 거예요. 새로고침하면 새 HTML을 받으니 해시가 맞춰져요. 다만 무한 새로고침을 막으려고 sessionStorage에 표시를 남겨요.

'use client';
 
import { useEffect } from 'react';
 
const RELOAD_FLAG = 'chunk-reloaded';
 
export default function ErrorPage({ error }: { error: Error }) {
  useEffect(function reloadOnceOnStaleChunk() {
    const isStaleChunk =
      error.name === 'ChunkLoadError' || /Loading chunk/i.test(error.message);
    const alreadyTried = sessionStorage.getItem(RELOAD_FLAG) === '1';
 
    if (isStaleChunk && !alreadyTried) {
      sessionStorage.setItem(RELOAD_FLAG, '1');
      window.location.reload();
      return;
    }
    sessionStorage.removeItem(RELOAD_FLAG);
  }, [error]);
 
  return <p>새 글이 올라와서 화면을 다시 불러오고 있어요.</p>;
}

적용해 봤더니 수정한 파일은 1개고, 사용자 쪽에선 링크를 눌렀을 때 잠깐 깜빡이고 새 페이지가 뜨는 정도로 끝나요. 번들러마다 에러 이름이 다를 수 있어서 message도 같이 보도록 했어요. 재현 환경에서 다시 돌려 보니 두 번째 빌드 뒤 클릭에서 콘솔 에러 없이 새 화면으로 넘어갔어요.

더 다듬을 자리

새로고침은 사후 처리예요. 테스트해 보면 폼에 입력하던 내용은 날아가요. 글만 읽는 블로그엔 충분하지만, 입력이 많은 화면이라면 빌드 ID를 주기적으로 비교해서 새 배포가 감지되면 다음 이동을 전체 내비게이션으로 바꾸는 쪽이 나아요. 호스팅에 이전 빌드 파일을 일정 기간 남겨주는 설정이 있다면 그것도 같이 보세요. 어느 쪽이든 "열어둔 탭은 항상 과거 빌드"라는 전제를 화면 설계에 넣어두는 게 핵심이에요.