SSR 로 블로그 배포하다 마주친 의문의 500 에러 - runtime edge 만날 썰 푼다

돈을 버는 서비스를 운영하는 프론트엔드 엔지니어가 되기위해서 SEO(Search Engine Optimization, 검색 엔진 최적화)에 관심이 많습니다. 이번에 개인 블로그를 배포하여 포스팅을 열심히 하고 있었는데, 이상하게도 구글 검색에서 내 블로그가 검색되지 않는다는 사실을 알게되었습니다. 당황한 마음에 robots.txt 와 sitemap 설정부터 차근차근 점검했습니다.

하지만 robots.txt 와 sitemap 에는 아무런 문제가 없었고, 결국 구글 서치 콘솔을 열어서 확인해보니 예상치 못한 사실을 마주했습니다.

“페이지 색인을 생성할 수 없음: 서버 에러(5xx)”

이런…. 왜 이런 문제가 발생하는지 원인을 찾으려고 로그를 분석하며 많은 시도를 하던 도중, 저는 처음으로 runtime = ”edge” 모드라는 낯선 개념을 마주했습니다. 렌더링 방식 자체가 달라지는 이전까지 생각도 못해본 문제였습니다. 이 경험을 통해 배운 중요한 사실을 놓치지 않고 기록으로 남겨보고자 합니다.

(저처럼 notionpresso를 사용하여 블로그를 배포하는 모든 분들에게 도움이 되길 바랍니다)

"왜 열심히 쓴 내 블로그 글이 구글 검색에서 전혀 안 나올까? SEO를 꼼꼼히 챙겼다고 생각했는데 도대체 어디서부터 잘못된 걸까?"

robots.txt부터 sitemap, JSON-LD, metadata까지 SEO와 관련된 모든 설정을 하나하나 꼼꼼하게 챙겼다고 생각했습니다. 그런데 이상하게도 내 블로그 포스팅은 구글에서 찾아볼 수 없었습니다.

문제의 원인을 검색하다가 구글에서 제공하는 SEO 관리 도구인 Google Search Console을 알게 되었습니다.

새로 발행한 페이지를 구글 검색 봇이 인지할 수 있도록 하기 위해서는 우선 "색인 생성" 과정을 거쳐야 한다. 색인이 완료되면 구글 검색 결과에 내가 발행한 페이지가 노출될 수 있게 됩니다. 또한 Google Search Console을 통해 검색 결과 모니터링과 문제 진단, 검색 순위 향상을 위한 다양한 활동도 가능합니다.

색인 생성을 위해 URL test를 진행했는데, 여기서 앞서 언급한 문제가 발생했습니다.

단순한 SEO 설정 문제를 넘어 뭔가 근본적인 문제가 있다는 걸 직감했고, 본격적으로 원인을 찾기 위해 vercel log를 열어 분석을 시작했습니다.

동일한 URL 요청임에도 불구하고, 문제가 발생할 때도 있고 발생하지 않을 때도 있었습니다.

다양한 시도 끝에 홈에서 링크를 통해 페이지로 이동하면 문제가 없었지만, URL을 직접 입력해서 접근할 경우에는 500 에러가 발생한다는 사실을 발견했습니다.

드디어 문제를 명확하게 재현할 수 있게되었습니다. 하지만 왜 직접 URL로 이동할 때만 문제가 발생하는지는 아직도 미궁입니다.

이 문제를 해결하기 위해 여러 차례의 시도를 거듭하던 중, 뜻밖의 사실을 또 하나 발견했습니다. 바로 /blog와 /guide라는 두 경로 중에서 /guide 경로로 직접 접근했을 때는 500 에러가 전혀 발생하지 않았던 것입니다.

이 두 경로 간의 차이는 무엇일까요? 두 경로의 코드를 꼼꼼하게 비교한 끝에 결정적인 차이를 발견했습니다.

바로 이 한 줄의 설정입니다.

빠르게 관련 문서를 찾아 읽기 시작했습니다.

Edge and Node.js Runtimes - Next.js 공식 문서

이제 무엇이 문제인지 감이 잡히셨나요? 저는 바로 이 부분을 캐치했습니다.

원인을 찾았으니 이제 문제를 해결해볼까요?

앞서 발견한 문제의 핵심은 바로 runtime = "edge" 였습니다.

runtime = "edge" 로 설정된 페이지는 빌드 시점에 미리 정적으로 생성되지 않습니다. 다시 말해, 정적인 HTML 파일이 없으며, 매 요청마다 Edge 환경에서 Backend 로직을 통해 실시간 SSR(Server Side Rendering) 처리 후 HTML 을 반환합니다.

결국 문제의 원인은 “빌드 시점에 생성된 Static Page(정적 페이지)가 존재하지 않는다” 였습니다

이제 해결 방법은 명확해졌습니다. 바로 SSG(Static Site Generation)을 사용하면 되는 거죠!

먼저, 기존과 동일하게 runtime = "edge" 설정을 유지한 상태로 npm run build 를 실행하여 각 페이지의 빌드 유형을 확인해보겠습니다.

빌드 결과, /blog/[slug] 경로는 Dynamic 방식으로 빌드된다는 사실을 확인할 수 있습니다. 이어서 npm run start 명령어로 빌드 결과물을 실행해보니 500 error 가 발생합니다.

다음으로, runtime = "edge" 를 제거하고 다시 빌드를 실행해보겠습니다.

이제 /blog/[slug] 경로가 SSG 방식으로 정상 빌드되었습니다. 그리고 npm run start 를 통해 페이지를 확인해보니, 이번에는 아무런 문제 없이 SSG 로 빌드된 페이지가 정상적으로 렌더링되었습니다.

자 이제 원인도 알았고, 문제도 해결했습니다. 배포 드가자~

Vercel 에서도 각 경로가 어떤 방식으로 빌드되는지 확인할 수 있습니다.

기존에는 functions 에 있는 것을 확인할 수 있습니다.

runtime = "edge" 를 제거하고 배포한 결과를 확인해보면

ISR 영역에 추가되고, 각 페이지 경로가 존재하는 것을 확인할 수 있습니다.

후반 결 및 정리

결국 위 방법으로 문제를 해결하고, 구글 서치 콘솔(google search console)을 통해 색인 요청이 정상적으로 가능해졌습니다.

실제로 구글에서 내 블로그를 확인하기 위해 site:https://mike-blog-murex.vercel.app 를 검색해보니, 다음과 같이 정상적으로 검색 결과에 노출되는 것을 확인할 수 있었습니다.

이변 경험을 통해 처음으로 “edge 런타임 환경” 개념을 접하게 되었는데요. 향후에는 edge 런타임 환경을 구축하여 500 error 없이 동작하는지 추가적으로 확인 해볼 계획입니다.

이번 문제 해결을 통해 얻은 인사이트를 다음과 같이 정리해 보았습니다.

마지막으로 500 error 를 해결하고 색인 생성을 완료한 결과입니다.