정적 사이트는 배포 후 반쯤 살아 있는 것처럼 깨질 때가 있다. HTML 페이지는 열리는데 이미지가 사라지고, 레이아웃이 무너지고, 스크립트가 돌지 않는다. 보기에는 크게 망가진 것 같지만, 원인은 생각보다 작고 기계적인 경우가 많다.

실전에서는 프레임워크가 실패했다기보다, 그 뒤 단계에서 페이지 경로와 자산 경로, 공개 호스트가 서로 안 맞기 시작한 경우가 더 흔하다.

이 글은 더 깊이 내려가기 전에 먼저 봐야 할 것들을 정리한다. 목표는 “배포가 망가졌다”는 막연한 느낌을 “어느 자산 요청이 왜 실패하는가”라는 작은 질문으로 줄이는 것이다.

1. 사람들이 자주 틀리는 지점은 사이트를 먼저 디버깅하고 자산 요청은 나중에 보는 것이다

정적 사이트가 깨져 보이면 많은 팀이 바로 설정 파일을 뒤지거나 로컬 빌드부터 다시 해본다. 대개는 너무 이르다.

브라우저가 CSS, JS, 이미지 자산을 잘못된 위치에서 찾고 있다면, 컴포넌트나 템플릿을 아무리 들여다봐도 도움이 안 된다. 이미 화면이 “이건 자산 요청 문제다”라고 먼저 말해주고 있는 셈이다.

2. 가장 중요한 점검은 페이지 경로와 자산 경로가 같은 배포 형태에 속해 있는지 보는 것이다

여기가 핵심 운영 질문이다. 페이지는 잘 열리는데 자산 요청만 호스트가 제공하지 않는 다른 위치를 가리킬 수 있다.

이 불일치는 몇 가지 패턴으로 자주 나타난다. 사이트가 서브패스로 옮겨졌는데 자산 URL은 여전히 루트를 가리킨다. 호스트는 바뀌었는데 생성된 자산 prefix는 그대로다. 또는 배포 결과물이 nested folder 아래에 놓였는데 HTML은 여전히 예전 레이아웃을 가리킨다.

그래서 증상이 더 헷갈린다. 사이트가 완전히 죽은 게 아니라 부분적으로만 존재한다. 첫 문서는 열리니 배포는 성공한 것처럼 보이지만, 그 아래 artifact network는 이미 갈라져 있다.

차분하게 보려면 네 가지만 비교하면 된다. 공개 페이지 URL, 사라진 이미지 요청 하나, 실패한 CSS나 JS 요청 하나, 그리고 실제 배포 결과물의 폴더 레이아웃이다. 이 넷을 나란히 놓으면 어긋남이 대부분 보인다.

3. 다시 빌드하기 전에 먼저 볼 기준

• 페이지는 루트에서 열리는가, 서브패스에서 열리는가
• 자산 URL이 페이지와 같은 경로 계열을 쓰는가
• 배포 폴더 레이아웃이 직전 릴리스와 달라졌는가
• 호스트가 빌드가 가정한 공개 경로를 실제로 제공하고 있는가

4. 깨진 가지 하나가 전체 증상을 설명하는 경우가 많다

예를 들어 홈은 열리는데 이미지만 전부 404이고 CSS와 JS는 살아 있다고 하자. 이런 경우 문제는 전체 배포가 아니라 더 좁다. 이미지 가지가 다른 폴더, 다른 호스트, 다른 prefix를 가리키고 있을 가능성이 높다.

반대도 가능하다. 이미지는 CDN 경로라 살아 있는데 CSS와 JS만 잘못된 local prefix로 가면, 일부 자산만 남아서 페이지가 더 이상하게 보인다.

5. 점검 순서는 고정해두는 편이 낫다

먼저 live 페이지를 연다. 그다음 실패한 자산 요청 하나를 본다. 그 경로를 공개 페이지 URL과 비교하고, 둘 다 실제 build output 폴더 구조와 대조한다. 이 세 뷰가 맞기 전에는 코드 수정으로 내려가지 않는 편이 맞다.

1. 깨진 페이지를 연다
2. 실패한 자산 요청 하나를 본다
3. 요청 경로를 페이지 URL 경로와 비교한다
4. 둘 다 배포 폴더 레이아웃과 대조한다
5. 그다음에야 설정, 경로, 호스트 중 어디를 고칠지 판단한다

무엇부터 시작할까

live 페이지 URL 하나와 실패한 자산 URL 하나를 나란히 적어라. 이 둘이 같은 배포 형태에 속하지 않으면, 앱을 디버깅하지 말고 경로부터 디버깅해야 한다.