Next.js

Next.js에서 sitemap.xml이 제대로 생성 안 될 때

sitemap이 비어있거나 URL이 누락됐을 때 어디서부터 확인할지 정한 흐름.

2026년 6월 24일·2분 읽기

Next.js 12.2부터 sitemap.ts를 통해 동적으로 사이트맵을 생성할 수 있다. 그런데 배포했는데 sitemap.xml이 비어있거나, 일부 URL만 나타났던 경험이 있다.

SEO 관점에서 이건 치명적이다. 검색 엔진 봇이 중요한 페이지를 못 찾으니까. 그래서 빠르게 확인해야 하는데, 할 일이 많아 보인다.

먼저 체크: 실제 생성됐는가

curl -s https://yoursite.com/sitemap.xml | head -20

파일이 있는지, 있다면 내용이 뭔지 본다. XML 구조가 맞는지, <url> 태그가 몇 개나 있는지 확인한다.

빈 파일이거나 에러 페이지가 나오면 sitemap.ts 함수 자체가 실행되지 않거나 에러를 던지는 걸 의미한다.

npm run build
npm run start

# 다른 터미널에서
curl -s http://localhost:3000/sitemap.xml | head -20

로컬에서 정상이면 빌드 결과는 괜찮다는 뜻이다. 그러면 배포 환경의 환경 변수나 실행 환경이 다를 가능성이 높다.

# 배포 환경 로그에서 (Vercel, Docker 등)
START /sitemap.xml
ERROR in sitemap generation

# 또는 404, 500 에러

함수에서 throw하면 결과적으로 500 에러가 나간다. 데이터 페칭 실패, 환경 변수 누락, DB 연결 실패 등이 원인이다.

빌드 환경에서 마이그레이션, Seed 같은 작업이 필요하다면 그게 스킵됐을 가능성도 있다.

블로그라면 RSS 피드도 같은 방식으로 생성된다. /rss.xml도 확인해서 두 생성 로직의 차이가 뭔지 본다.

어느 한쪽만 안 되는 경우:

둘 다 안 되는 경우:

curl -s https://yoursite.com | grep -E 'og:|twitter:|canonical'

Sitemap 외에도 메타데이터와 canonical이 맞는지 본다. 이들이 모두 일관성 있으려면, 동일한 데이터 소스를 쓰는지 확인해야 한다.

예를 들어 블로그 게시글 목록을 /posts에서 가져오는데, sitemap 생성할 때는 다른 곳에서 가져오면 누락된다.

# 배포 환경에서
echo $DATABASE_URL
echo $NEXT_PUBLIC_SITE_URL

Sitemap 함수에서 절대 URL을 만들 때 필요한 SITE_URL이 빈 값이면, relative URL만 나가거나 에러가 난다.

다음에 같은 문제가 생기면 이 네 가지로 원인을 반으로 줄일 수 있다.