Next.js에서 조건부 렌더링이 늦거나 틀릴 때 체크포인트

Next.js 프로젝트에서 페이지 렌더링이 불안정하면 정말 막힌다. 로컬에서는 괜찮은데 배포 후에 이상하거나, 처음 로드는 빠른데 조건에 따라 화면이 뒤바뀌거나, 메타데이터가 제대로 나오지 않거나.

이런 문제는 단순히 JSX 코드가 잘못됐을 가능성도 있지만, 더 자주는 빌드 설정이나 렌더링 전략 때문이다.

메타데이터와 캐노니컬 태그부터

Next.js에서 생성되는 HTML head를 확인한다. 타이틀, description, og:image, canonical 태그 같은 것들이 실제로 있는지.

curl -s https://example.com | grep -Ei 'title|description|canonical|og:|twitter:'
npm run build

브라우저에서 페이지 소스를 보는 것도 방법이지만, curl로 직접 확인하는 게 더 정확하다. 캐시 영향을 받지 않으니까.

빌드 로그를 무시하지 마

빌드할 때 경고가 떠도 보통은 무시한다. "나중에 봐야겠다" 하다가 까먹는다. 하지만 이 경고들이 런타임 문제로 나타난다. 특히 조건부 렌더링은 빌드 시점의 경고가 나중에 화면 깜빡임이나 틀린 내용으로 나타난다.

로컬과 배포는 다른 환경

처음 로드할 때와 이후 상태 업데이트 후의 렌더링 결과가 다를 수도 있다. 환경 변수, 빌드 모드(dev vs prod), 캐시 정책. 이 모든 게 영향을 미친다.

비슷한 증상이 다시 나오면 현재 화면을 캡처하고, HTML 소스를 저장하고, 빌드 로그를 기록해둔다. 그러면 다음 번엔 금방 같은 문제를 찾아낸다.