미리보기 기능이 정상이지만 배포된 사이트가 빈 화면일 수 있습니다. 이 차이는 유용합니다: 이 차이는 프로덕션 환경, 빌드 자산, 또는 라이브 라우팅을 가리키며, 무작위 디자인 변경이 아닙니다.
30초 해결
라이브 URL을 열고 브라우저 개발자 도구를 열어 새로고침하세요. 첫 번째 빨간색 콘솔 오류와 첫 번째 실패한 네트워크 요청을 기준으로 분기점을 선택하세요:
- 환경 변수가 누락되었거나
undefined→ 배포 호스트에 추가하고 다시 배포하세요 - 자바스크립트 또는 CSS가 404를 반환 → 빌드 출력 또는 base 경로를 수정하세요
Unexpected token <또는 모듈 MIME 오류 → URL이 자바스크립트 대신 HTML을 반환했습니다- 새로고침 후만 중첩 URL이 실패 → 호스트 문서에 명시된 SPA 폴백 규칙를 추가하세요
- 앱이 마운트되기 전에 자바스크립트가 예외를 던짐 → 먼저 이 런타임 예외를 수정하세요
분기점 1 — 프로덕션 환경 변수가 누락됨
앱 빌더 내부에 저장된 비밀은 모든 외부 호스트에 자동으로 존재하지 않습니다. 프로젝트의 변수 이름을 정확한 프로덕션 환경에 설정된 변수와 비교하세요. 시크릿 값은 채팅이나 스크린샷에 절대 복사하지 마세요.
클라이언트 측 Vite 앱의 경우, 프레임워크의 공개용 접두사를 사용해 의도적으로 노출된 변수만 브라우저 코드에서 사용 가능합니다. 서버 키를 노출해 빈 화면이 사라지도록 하지 마세요. 배포 플랫폼에서 변수를 추가하거나 수정한 후 새 배포를 생성하세요. 변수를 변경하는 것만으로 기존 빌드를 재구성하지 않습니다.
분기점 2 — 빌드 자산이 누락됨
네트워크 패널에서 실패한 자바스크립트 또는 CSS 요청을 선택하세요. 404는 일반적으로 배포된 출력과 생성된 자산 URL이 일치하지 않음을 의미합니다. Unexpected token <는 스크립트 URL이 HTML 오류 페이지를 반환했음을 나타냅니다. 모듈 MIME 오류는 소스 파일이 업로드된 대신 컴파일된 출력이 업로드되지 않았음을 의미할 수 있습니다.
로컬에서 깨끗한 프로덕션 빌드를 실행하세요:
npm run build
프레임워크가 실제로 생성하는 디렉토리를 배포하세요. 예를 들어, 표준 Vite 프로젝트의 경우 dist/를 배포하세요. 플랫폼의 현재 빌드 출력 설정을 따르고, 폴더 이름을 추측하지 마세요. 앱이 서브패스 아래에서 제공되는 경우, 프레임워크의 base 경로를 실제 URL과 비교하세요.
분기점 3 — 중첩 라우트가 새로고침 시 실패
만약 /가 작동하지만 /dashboard가 직접 방문 후 빈 화면 또는 404가 되면, 브라우저 라우터와 호스트가 일치하지 않습니다. 호스팅 플랫폼의 문서에 명시된 단일 페이지 앱 폴백 규칙를 구성하여 애플리케이션 라우트가 index.html를 반환하도록 하세요. 자산 파일 또는 API 라우트를 index.html로 리디렉션하지 마세요. 이는 위에서 언급한 Unexpected token < 오류를 유발할 수 있습니다.
리디렉션 후 중첩 라우트에 대한 직접 방문과 새로고침를 모두 테스트하세요.
분기점 4 — 라이브 앱이 런타임 오류를 던짐
첫 번째 예외부터 시작하세요. 아래 메시지 모두를 확인하지 마세요. 일반적인 예시는 undefined에서 속성을 읽거나, 필수 URL 없이 API 클라이언트를 초기화하거나, 브라우저 기능이 사용 가능한 것으로 가정한 코드를 가져오는 것입니다.
정확한 예외, 파일, 줄 번호를 에이전트에게 제공하세요. 해당 값이 누락되었는지 설명해 달라고 요청하세요. 하나의 원인을 수정하고, 다시 빌드한 후, 시크릿 창에서 라이브 URL을 재테스트하세요.
수정 확인
새로운 배포를 사용하고 확인하세요:
- 배포 빌드가 성공적으로 완료되었는지
- 라이브 콘솔에 첫 로드 시 잡히지 않은 예외가 없는지
- 자바스크립트 및 CSS 요청이 예상되는 콘텐츠 유형으로 성공적으로 응답하는지
/및 중첩 라우트가 시크릿 창에서 모두 작동하는지- 주요 상호작용이 작동하는지, 첫 화면만 보이는 데 그치지 않는지
캐시된 탭은 이전 실패를 보여줄 수 있습니다. 최종 확인을 위해 시크릿 창 또는 강제 새로고침을 사용하세요.
여전히 작동하지 않는다면
작동하던 마지막 배포를 복원하고, 실패한 배포와 비교하세요. 환경 변수 이름, 빌드 명령어, 출력 디렉토리, 라우팅 규칙을 비교하세요. 플랫폼이 장애를 알렸다면 코드 변경을 중단하고 기다리세요. 그렇지 않다면, 배포 URL, 첫 번째 콘솔 오류, 첫 번째 실패한 네트워크 요청, 배포 로그를 공식 지원에 전달하세요. 시크릿과 개인정보는 제거한 후 전달하세요.
초보자 요약
미리보기 기능이 정상이지만 배포된 사이트가 흰색이면 라이브 환경이 다릅니다. 첫 번째 빨간색 콘솔 오류를 확인하고 호스트에 필요한 변수가 있는지 확인하세요. 빌드된 출력을 배포하고 중첩 URL을 테스트하세요. AI에게 페이지를 재작성하도록 요청하는 대신, 한 번에 한 분기만 변경하세요.