Next.js Route Handler가 검색에 노출되지 않을 때

검색 유입을 기대했던 페이지가 노출되지 않으면 보통 두 가지 혼동이 섞여 있다. Route Handler 자체 문제와 메타데이터 전파 문제를 구분하는 게 핵심이다.

먼저 공개 URL 상태 확인

브라우저에서 직접 페이지에 들어가 보면 가장 빠르다. HTML head에 검색 엔진이 읽을 메타 태그가 제대로 박혀 있는지 확인한다.

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

이 명령으로 title, description, canonical, og 태그 등을 한눈에 볼 수 있다. 만약 이곳이 비어 있으면 빌드나 렌더링 단계 문제다.

로컬과 운영 환경 비교

로컬에서는 잘 보이는데 운영에만 문제가 나타나면 보통 빌드 환경이나 환경변수 때문이다. 정상 상태를 먼저 정의하고, 빌드 로그를 남겨둔다.

npm run build
npm run start

로컬 빌드 결과와 배포 환경 빌드 결과를 비교해야 한다. 특히 빌드 시간, 에러 메시지, 생성된 파일 크기 같은 작은 신호들이 원인이 될 수 있다.

응답 코드와 sitemap 확인

사이트맵이나 RSS에는 노출되는데 검색에만 안 나오면 캐시 문제일 가능성이 높다. 실제 요청의 응답 코드를 확인하고, 3xx 리다이렉트가 없는지 봐야 한다.

curl -I https://example.com

수정 후 확인 루틴

하나를 고칠 때마다 다음 순서로 확인한다. 이 루틴을 지키면 비슷한 증상이 다시 나올 때 훨씬 빠르게 대응할 수 있다.

1. 로컬에서 원래 증상이 재현되는지 한번 더 확인한다.
2. 수정한 부분만 언급하고, 빌드 결과나 로그의 어떤 부분이 바뀌었는지 기록한다.
3. 배포 후 실제 공개 URL에서 최종 확인을 한다.

다음에 비슷한 문제가 나오면 공개 URL의 메타 태그 확인에서부터 시작하면 된다.