vercel로 배포한 웹에서 404 not found 페이지가 잠시 노출되는 문제 해결기
최근 Github Pages 를 사용하다가 Vercel로 배포환경을 바꾸면서 발생한 문제입니다.
새로고침 혹은 링크로 처음 페이지에 진입시 잠깐동안 404 not found 페이지로 시작되는 문제가 있었는데 장시간 삽질 끝에 간단히 해결했습니다.
원인과 해결 방법 🪄
과정은 재미 없으니 해결 방법부터 작성합니다.
프로젝트의 루트에 vercel.json 파일을 위치시키면 Vercel의 기본 설정을 오버라이드하여 기본 동작을 바꿀 수 있습니다.
저와 같은 원인이었다면 이 파일에 아래와 같이 작성하여 새로 배포하면 해결됩니다.
{
"cleanUrls": true
}
원인 파악 과정 👾
지금 블로그는 docusaurus 를 사용합니다. 한동안 방치하다가 github pages에서 Vercel로 배포 환경을 바꿨는데 이참에 docusaurus 버전도 올려버렸습니다. 버전도 올리는김에 리액트 버전도 올리고 각종 라이브러리 버전도 올리고.. eslint, prettier 설정 등 아무 설정도 되어있지 않던 블로그 프로젝트에 여러가지 겉으로는 티나지 않는 새단장을 해줬습니다.
빌드도 해보니 잘 됩니다. 이제 배포준비가 끝났으니 Vercel에 깃허브 저장소를 연결하고 배포를 해보니 아주 쉽고 간단하게 배포가 됩니다. 그렇게 아무 문제가 없는줄 알고 지내다보니 며칠이 지나서 구글에서 메일이 옵니다.
페이지 색인이 생성되지 않는다며 구글이 메일을 보내줬다
google search console에 들어가보니 페이지 색인이 생성되지 않고 있 었습니다.
google search console에 찾을 수 없음(404)의 사유로 유효성 검사에 실패하고 있다
Vercel문제일 줄은 꿈에도 모르고 버전을 올리면서 발생한 문제인줄 알고 docusaurus.config 등 여러 구성요소를 바꿔보며 삽질하기 시작합니다..
버전을 올리면서 뭔가 잘못된 것 같아서 프로젝트를 새롭게 세팅해봅니다. 로컬에서 빌드해보니 아무 문제 없는 것 같아서 배포까지 해봅니다. 근데 이런 현상이 발생하지 않는군요..?? 오오
그래서 블로그 글들을 옮겨서 다시 배포해봅니다. 그랬더니 다시 같은 현상이 발생합니다.
이래도 저래도 제가 뭔가 잘못한 것 같습니다. 근데 가만히 생각해보니 로컬에서 빌드하고 빌드 결과물을 돌려보면 이런 현상이 전혀 없습니다. 그래서 Vercel에 문제가 있을지 모르겠다는 의심을 하며 공식문서를 보다 보니 이런 내용이 있습니다. Configuring Projects with vercel.json
이 페이지를 보니 vercel.json 파일을 프로젝트에 넣어서 vercel의 기본 동작을 제어할 수 있는 것 같습니다.
cleanurls 라는 옵션을 보니 뭔가 제 상황과 비슷합니다.
공식문서의 설명은 이러합니다.
Type:
Boolean.Default Value:
false.When set to
true, all HTML files and Serverless Functions will have their extension removed. When visiting a path that ends with the extension, a 308 response will redirect the client to the extensionless path.For example, a static file named
about.htmlwill be served when visiting the/aboutpath. Visiting/about.htmlwill redirect to/about.Similarly, a Serverless Function named
api/user.gowill be served when visiting/api/user. Visiting /api/us er.gowill redirect to/api/user.
요약해보면 기본값은 false 인데 true 로 설정하면 /about 경로로 접근할때 이름이 about.html인 정적파일이 서브된다고 합니다. 반대로 about.html 로 접근하면 /about 으로 리다이렉트 된다고 하고요.
docusaurus는 markdown 파일을 생성할때 slug옵션으로 원하는 경로를 설정하면 정적 파일 이름과 경로가 다를 수 있습니다. 빌드하면 이 설정된 slug를 이용하여 동일한 이름의 html파일을 생성합니다. 그러므로 이 옵션을 true로 설정하면 바로 해당 경로에 매칭되는 html파일에 접근할 수 있습니다.
false 이면 어떤 html이 바로 서브되는지는 설명이 되어있지 않지만 원하는 옵션을 찾았으니 프로젝트 루트에 vercel.json파일을 만들고 cleanurls 옵션을 활성화 시켜줍니다.
{
"cleanUrls": true
}
결과 데모
network throttle Fast 3G로 설정한 상태입니다.
- 왼쪽: 404 페이지가 잠깐 렌더됨
- 오른쪽: 404 페이지가 렌더되지 않고 바로 본문이 렌더됨✨