백엔드 개발자에게 "배포"는 보통 서버를 세팅하는 일입니다. EC2 인스턴스 띄우고, Docker 컨테이너 올리고, nginx 설정하고. 그게 제가 아는 배포였습니다. 그런데 Q-Fit을 만들면서 처음으로 정적 배포라는 걸 해봤습니다. 그리고 배포 후에야 보이는 것들이 생각보다 꽤 많았습니다.
어디에 배포할까: Gemini에게 상황을 설명했다
처음엔 그냥 서버 빌려서 올리면 되지 않나 싶었습니다. AWS에 올리면 되겠다고 생각했는데, Gemini에게 이야기하니 정적 사이트는 서버 없이도 배포할 수 있다고 했습니다. 빌드하면 HTML, CSS, JS 파일만 나오는 구조라서, 그 파일들을 그냥 CDN에 올려버리면 된다는 거였습니다. 서버를 24시간 돌릴 필요가 없으니 비용이 거의 안 든다는 것도 처음 알았습니다.
그러면서 후보를 몇 가지 알려줬습니다. Vercel, Netlify, Cloudflare Pages. 처음엔 Vercel이 편리하다고 추천했습니다. 그런데 Q-Fit이 상업적 목적이고 트래픽이 어느 정도 붙을 수 있다는 걸 설명하니, 무료 플랜의 상업 이용 제한과 트래픽 한도 문제가 있다고 했습니다. 그러면서 Cloudflare Pages를 대안으로 제시했습니다. 상업적 이용 제한이 없고, 무료 플랜에서 트래픽 제한도 없다는 이유였습니다. 그래서 Cloudflare Pages로 결정했습니다.
첫 배포: Pages 메뉴를 못 찾았다
Cloudflare 대시보드에 들어가니 메뉴가 꽤 많았습니다. Workers, R2, D1, KV 같은 이름들이 즐비했습니다. 그런데 Pages가 어디 있는지 한참을 못 찾았습니다. Workers 항목 안에 있는 건지, 아니면 따로 있는 건지. 결국 스크린샷을 찍어서 Gemini에게 보내면서 "이 화면에서 Pages는 어디 눌러요?"를 물었습니다.
Gemini가 화면을 보고 어디를 클릭하면 되는지 알려줬습니다. 어떤 값을 입력해야 하는지도 전부 안내를 받았습니다. 빌드 명령어, 출력 디렉토리까지. 뭘 왜 입력하는지 완전히 이해한 건 아니었지만, 일단 시키는 대로 넣었습니다. 그랬더니 첫 배포가 됐습니다. 생각보다 어렵지 않았습니다.
이미지 로딩이 너무 느렸다
배포 후에 사이트를 열어봤는데, 이미지 로딩이 눈에 띄게 느렸습니다. public 폴더에 PNG 파일들을 그대로 넣어뒀는데, 용량이 꽤 컸습니다. 로컬에서는 어차피 바로 로드되니까 몰랐던 건데, 실제 배포 환경에서는 차이가 확연했습니다. 심리테스트 결과 이미지 같은 게 특히 티가 났습니다.
Gemini한테 말했더니 WebP로 변환하라고 했습니다. 같은 이미지인데 PNG보다 파일 크기가 훨씬 작아진다고. 변환 코드도 짜줬습니다. 이미지들을 전부 WebP로 바꿨더니 체감 로딩 속도가 확실히 달라졌습니다. 이미지 최적화라는 걸 이때 처음 실감했습니다. 로컬에서만 개발하다가 배포 환경을 처음 만져보면 이런 게 눈에 보이는구나 싶었습니다.
카카오톡 공유를 해봤는데 항상 메인으로 갔다
배포하고 나서 카카오톡으로 특정 심리테스트 링크를 공유해봤습니다. 그런데 링크를 눌러도 항상 메인 페이지로 이동하는 겁니다. 제가 보내려던 테스트가 아니라 홈으로 와버리는 상황이었습니다. 왜 그런지 Gemini에게 물었더니, URL이 페이지마다 바뀌도록 라우팅 처리가 안 돼 있어서 그렇다고 했습니다.
라우팅 처리를 Gemini가 해줬는데, 이 과정에서 SPA 특유의 새로고침 404 문제도 같이 해결됐습니다. SPA는 페이지를 클라이언트 사이드에서 렌더링하기 때문에, 특정 URL로 직접 접근하거나 새로고침하면 서버가 해당 경로를 모르고 404를 돌려준다는 거였습니다. 정적 배포 환경에서 이 문제를 처리하는 방법도 있다고 해서, 함께 적용했습니다. SPA가 뭔지는 알고 있었지만, 정적 배포에서 이런 식으로 문제가 생길 수 있다는 건 직접 겪어보기 전까지는 몰랐습니다.
카카오톡 공유 미리보기에 아무것도 안 나왔다
라우팅 문제를 해결하고 다시 카카오톡으로 공유해봤습니다. 이번엔 링크를 누르면 제대로 해당 테스트 페이지로 이동했습니다. 그런데 공유할 때 미리보기가 없었습니다. 다른 서비스 링크를 공유하면 제목이랑 이미지가 뜨는데, Q-Fit 링크는 그냥 URL만 나왔습니다.
Gemini에게 이유를 물었더니 OG 태그가 없기 때문이라고 했습니다. Open Graph 태그라고, 링크를 공유할 때 미리보기 이미지나 제목, 설명이 뜨도록 하는 메타 정보를 HTML에 심어두는 방식이라고 설명해줬습니다. 그러면서 각 페이지마다 동적으로 OG 태그를 생성해야 하는데, 정적 사이트라서 프리렌더링도 필요하다고 했습니다. SEO라는 개념도 이때 처음 제대로 들었습니다. 검색엔진이 페이지를 어떻게 인식하는지, 콘텐츠에 어떤 메타 정보가 필요한지. 배포를 통해 자연스럽게 SEO의 필요성을 체감한 셈이었습니다.
없는 URL로 접근하면 화면이 깨졌다
어느 날 존재하지 않는 URL로 접근했을 때 화면이 그냥 깨지는 걸 발견했습니다. 아무것도 없는 하얀 화면이거나, 레이아웃이 반쯤 무너진 상태로 보였습니다. 404 페이지를 따로 만들어두지 않았던 거죠. 서버 기반 배포를 할 때는 nginx 설정에서 404 처리를 따로 했었는데, 정적 배포에서는 그게 없으니 그냥 빈 화면이 나오는 거였습니다.
404 페이지를 만들어서 해결했습니다. 잘못된 URL로 접근하면 "페이지를 찾을 수 없습니다"라는 안내와 함께 메인으로 돌아갈 수 있는 버튼을 넣었습니다. Cloudflare Pages는 루트에 `404.html` 파일을 두면 알아서 처리해준다고 Gemini가 알려줬습니다. 간단히 해결됐지만, 이것도 직접 겪어보기 전까지는 생각을 못 했던 부분이었습니다.
배포 후에야 보이는 것들
돌이켜보면, 이 모든 문제들은 로컬에서는 발견하기 어려운 것들이었습니다. 이미지는 로컬에서 빠르게 로드되고, 카카오톡 공유는 배포 전엔 해볼 수가 없고, OG 태그 미리보기도 실제 URL이 있어야 확인되고, 404 처리도 잘못된 URL로 접근해보기 전까지는 드러나지 않습니다. 전부 배포하고 나서야 알게 된 것들이었습니다.
백엔드에서 API를 만들 때는 로컬에서도 대부분 재현할 수 있었습니다. 그런데 정적 프론트엔드 배포는 달랐습니다. "실제로 사용자가 사용하는 환경"이 로컬과 꽤 다른 부분이 있었고, 그 차이가 문제로 드러났습니다. 서버 없이 배포한다는 게 단순히 "올리면 끝"이 아니라, 그 환경에 맞게 신경 써야 할 게 따로 있다는 걸 알게 됐습니다.
마치며
정적 배포는 확실히 서버 배포보다 진입 장벽이 낮습니다. 설정도 적고, 비용도 거의 없고, 자동화도 잘 돼 있습니다. 그런데 "서버가 없다"는 게 "신경 쓸 게 없다"는 뜻은 아니었습니다. 오히려 배포 환경에서만 드러나는 이슈들이 있었고, 그걸 하나씩 맞닥뜨리면서 정적 배포가 어떻게 동작하는지를 조금씩 이해하게 됐습니다. 백엔드만 해오던 사람이 프론트엔드 배포를 처음 해보면서 배운 것들이 꽤 있었습니다. 다음에 또 비슷한 프로젝트를 하면, 이번보다는 덜 헤맬 것 같습니다.