배포된 페이지가 완전히 망가져 보일 때가 있다. HTML 자체는 열리는데 레이아웃이 사라지고, 스크립트가 안 돌고, 아이콘이나 스타일이 빠진다. 이때 사람들은 프레임워크 설정이나 빌드 결과부터 의심하는 경우가 많다.

하지만 실전에서는 원인이 훨씬 더 단순하고 기계적인 경우가 많다. 페이지는 한 경로에서 열리는데, 생성된 CSS와 JS는 다른 경로에서 요청되고 있는 것이다.

이 글은 더 깊은 앱 버그를 추측하기 전에 base path와 자산 라우팅부터 확인하는 방법을 다룬다. 목표는 스타일과 스크립트가 깨진 상황을 막연한 앱 오류로 보지 않고, 먼저 경로 문제로 읽게 만드는 것이다.

1. 사람들이 자주 틀리는 지점은 CSS나 JS 누락을 렌더링 버그로 먼저 보는 것이다

배포 후 페이지에서 스타일이나 동작이 사라지면, 많은 사람이 바로 프레임워크 설정, hydration 문제, 컴포넌트 오류 쪽으로 내려간다. 이해는 되지만 첫 점검으로는 너무 깊다.

생성된 자산 파일이 잘못된 위치로 요청되고 있다면, 앱 코드가 아무리 맞아도 페이지는 깨져 보일 수밖에 없다. 이건 아직 렌더링 문제가 아니라 경로 문제다.

2. 가장 중요한 지점은 페이지 경로와 자산 경로가 서로 다를 수 있다는 걸 이해하는 것이다

여기가 핵심이다. 페이지가 200으로 잘 열려도 CSS와 JS 요청이 다른 데로 가면 운영 기준으로는 이미 깨진 페이지다.

이 상황은 보통 실제 배포 경로, 프레임워크의 base path, 생성된 자산 경로, 공개 호스트 가정이 서로 안 맞을 때 생긴다. 페이지는 서브패스 아래에 있는데 자산은 여전히 루트에서 찾거나, 반대로 앱은 서브패스를 기대하는데 실제 배포는 루트에서 열리고 있는 식이다.

그래서 증상이 이상하게 느껴진다. 첫 문서는 열리니 배포는 된 것처럼 보인다. 하지만 브라우저가 스타일, 스크립트, 폰트, 이미지 번들을 요청하는 순간부터 어긋남이 드러난다. 결과는 “반쯤 살아 있는 페이지”다. 내용은 보이는데 레이아웃은 무너지고 동작은 사라진다.

많은 사람이 여기서 페이지가 어떻게 보이는지만 보고 원인을 추측한다. 하지만 브라우저가 실제로 말해주는 건 “앱이 망가졌다”가 아니라 “자산을 잘못된 위치에서 찾고 있다”에 가깝다. 이 둘은 전혀 다른 문제고, 해결 방법도 완전히 다르다.

이 차이를 보는 순간 점검 순서가 훨씬 차분해진다. 컴포넌트 디버깅으로 내려가기 전에 네 가지를 비교하면 된다. 공개 페이지 URL, 실제 요청된 자산 경로, 설정된 base path, 그리고 배포 결과가 만든 경로 레이아웃이다. 대부분의 경우 어긋남은 여기서 드러난다.

3. 앱 코드를 건드리기 전에 먼저 볼 기준

• 페이지는 루트 경로에서 열리는가, 서브패스에서 열리는가
• CSS와 JS 요청 경로가 페이지와 같은 경로 계열에 속하는가
• 프레임워크 설정이 호스트가 실제로 제공하지 않는 base path를 기대하고 있지 않은가
• 배포 결과가 자산을 접두 경로 아래에 두었는데 링크는 여전히 루트를 가리키고 있지 않은가

4. 대표적인 실패 장면 하나만 봐도 대부분 이해된다

예를 들어 사이트가 /docs/ 아래에 배포됐다고 하자. HTML 페이지는 그 경로에서 잘 열리는데, 자산 링크는 여전히 /assets/...로 가고 있다면 브라우저는 /docs/assets/...가 아니라 루트의 자산을 찾게 된다. 운영자는 페이지가 “반쯤 깨졌다”고 느끼지만, 브라우저 기준으로는 아주 정확한 경로 불일치다.

반대 경우도 있다. 빌드는 서브패스용으로 생성됐는데 실제 호스트는 루트에서 사이트를 열고 있으면, 모든 자산 요청이 호스트가 모르는 접두 경로를 달고 나간다.

5. 점검 순서는 매번 같게 간다

코드 수정부터 시작하지 마라. 먼저 공개 페이지 URL을 보고, CSS 요청 하나와 JS 요청 하나를 확인하고, 그 둘을 설정된 base path와 실제 배포 폴더 구조에 대조해라. 이 네 가지가 안 맞으면 다른 디버깅은 기다리는 편이 맞다.

• 깨진 페이지를 연다
• CSS 요청 하나와 JS 요청 하나를 본다
• 요청 경로가 실제 공개 URL 구조와 맞는지 비교한다
• 둘 다 설정된 base path와 대조한다
• 그다음에야 설정 문제인지, 배포 경로 문제인지, 생성 링크 문제인지 판단한다

무엇부터 시작할까

깨진 페이지 하나를 열고 세 문자열을 나란히 적어라. 공개 페이지 URL, CSS 요청 URL 하나, JS 요청 URL 하나다. 이 셋이 같은 경로 계열에 속하지 않으면, 더 깊은 앱 버그를 의심하기 전에 base path나 자산 라우팅 문제로 먼저 다뤄라.