웹 앱의 빈 흰 화면 해결하는 법

빈 흰 화면은 거의 항상 두 가지 중 하나를 뜻해요. 앱의 JavaScript가 아무것도 그리기 전에 크래시했거나, JavaScript가 아예 로드되지 않은 거예요. 개발자 도구의 콘솔을 열고(우클릭 → 검사 → 콘솔) 처음 나오는 빨간색 오류를 읽은 다음, 네트워크 탭에서 로드에 실패한 파일을 확인하세요. 대부분의 원인은 환경 변수 누락, 잘못된 기본 경로, 끝나지 않은 빌드, 또는 한 컴포넌트의 크래시예요.

이 가이드는 React, Vue 등으로 만든 싱글 페이지 앱(AI 빌더로 만든 앱 포함)을 다뤄요. 빈 화면이 가장 흔하게 나타나는 곳이에요.

페이지가 하얀 이유

현대적인 싱글 페이지 앱(SPA)은 브라우저에 거의 비어 있는 HTML 파일을 보내요. 대략 이런 모습이에요.

<body>
  <div id="root"></div>
  <script type="module" src="/assets/index-a1b2c3.js"></script>
</body>

그러고 나서 JavaScript가 그 빈 div 안에 전체 페이지를 만들어요. 스크립트가 로드되지 않거나 렌더링 전에 오류를 던지면, div는 빈 채로 남고 흰 화면이 보여요. 페이지가 눈에 띄게 “고장 난” 것이 아니라, 그냥 아무것도 그려지지 않은 거예요.

그래서 해결은 항상 페이지 자체가 아니라 개발자 도구에서 시작해요.

1단계: 콘솔 읽기

개발자 도구를 열어요. 페이지를 우클릭하고 검사를 선택하거나 F12를 누르세요(Mac은 Cmd+Option+I). 콘솔 탭으로 가서 페이지를 새로 고치세요.

첫 번째 빨간 오류를 보세요. 뒤에 나오는 오류는 대개 부수적인 결과예요. 오류 내용이 원인을 알려 줘요.

파일 이름과 줄 번호를 포함해 전체 오류 텍스트를 복사하세요. AI 빌더를 쓰고 있다면 그대로 채팅에 붙여 넣으세요.

2단계: 파일이 제대로 로드되었는지 확인하기

네트워크 탭을 열고 캐시 사용 안 함을 체크한 뒤 새로 고치세요. .js와 .css 파일 요청을 보세요.

• JavaScript 파일이 404 상태라면, 페이지가 서버에 없는 파일을 요청하고 있는 거예요.
• **200 상태지만 타입이 text/html**이라면, 서버가 스크립트 대신 페이지(보통 SPA 폴백 때문에 index.html 자체)를 반환한 거예요. 근본 원인은 같아요. 파일이 페이지가 기대하는 위치에 없는 거예요.

흔한 이유는 다음과 같아요.

잘못된 기본 경로. 앱이 example.com/app/처럼 하위 폴더에서 제공되는데, /assets/...에서 파일을 로드하도록 빌드되었다면 모든 스크립트 요청이 빗나가요. Vite에서는 vite.config의 base 옵션이고, Create React App에서는 homepage 필드, Next.js에서는 basePath예요. 앱이 실제로 제공되는 위치와 맞아야 해요.

오래된 index.html. 빌드 도구는 파일 이름에 콘텐츠 해시를 붙여요. 예를 들면 index-a1b2c3.js처럼요. 새로 배포되면 옛 파일은 사라져요. 브라우저나 CDN이 여전히 옛 index.html을 캐시하고 있다면, 존재하지 않는 옛 파일을 요청하고 아무것도 받지 못해요. 강력 새로 고침(Cmd+Shift+R 또는 Ctrl+Shift+R)을 하면 이를 확인할 수 있어요. 장기적인 해결책은 해시가 붙은 파일은 길게 캐시하면서, index.html은 짧은 시간이나 캐시 없이 제공하는 거예요.

빌드가 끝나지 않았거나 배포되지 않았어요. 빌드가 실패했다면 호스트는 오래되었거나 빈 결과물 폴더를 제공하고 있을 수 있어요. 빌드 로그에서 오류를 확인하세요.

잘못된 폴더가 게시되었어요. 호스트는 프로젝트의 소스 폴더가 아니라 빌드 결과물(보통 dist나 build)을 제공해야 해요. 소스를 제공하면 /src/main.tsx를 가리키는 index.html이 나오는데, 브라우저는 이를 실행할 수 없어요.

3단계: 환경 변수 확인하기

프런트엔드 앱은 API URL이나 공개 키 같은 설정을 빌드 시점에 읽는 경우가 많아요. 라이브 빌드에 변수가 없으면, createClient(undefined, undefined) 같은 코드가 즉시 예외를 던지고 페이지가 하얗게 변해요.

알아 둘 점은 다음과 같아요.

• Vite에서는 VITE_로 시작하는 변수만 브라우저 코드에서 쓸 수 있고, import.meta.env.VITE_NAME으로 읽어요. Create React App은 REACT_APP_, Next.js는 NEXT_PUBLIC_이에요.
• 이 값들은 앱을 빌드할 때 고정돼요. 빌드 후에 변수를 추가해도 다시 빌드하고 재배포하기 전까지는 아무 효과가 없어요.
• 미리보기나 로컬 컴퓨터에는 프로덕션 빌드에 없는 .env 파일이 있을 수 있어요. 같은 변수를 호스트에도 설정하세요.
• 이 접두사가 붙은 값은 모두 공개 JavaScript에 들어가요. 공개해도 되는 값만 넣고, 비밀 키는 절대 넣지 마세요.

빠른 확인 방법은 콘솔 오류에서 설정 이름 근처의 undefined를 찾아보거나, 다음과 같이 물어보는 거예요.

게시된 앱이 빈 페이지를 보여 줘. 프런트엔드가 읽는 모든 환경 변수를 나열하고, 라이브 빌드에서 누락되었거나 비어 있는 것을 확인한 뒤, 변수가 없을 때 빈 화면 대신 분명한 오류 메시지를 보여 주도록 해 줘.

4단계: 크래시 고치기

콘솔에 평범한 JavaScript 오류가 나온다면, 렌더링 중에 코드가 크래시한 거예요. AI로 만든 앱에서 흔한 원인은 다음과 같아요.

• 데이터가 아직 로드되지 않음. 컴포넌트가 user가 도착하기 전에 user.name을 읽어요. 해결책은 로딩 상태를 두거나 옵셔널 체이닝(user?.name)을 쓰는 거예요.
• 데이터가 비어 있음. 새 계정에는 기록이 없는데, 코드는 목록에 최소 한 개가 있다고 가정해요.
• 예상과 다른 데이터 형태. API가 목록 대신 오류 객체를 반환했어요.
• 누락된 import. 파일 이름을 바꾸거나 옮긴 뒤 import가 빠졌어요.
• 서버 측 렌더링 중 브라우저 전용 API 사용. Next.js 서버 컴포넌트에서 window나 localStorage를 쓰는 경우예요.

AI에게는 전체 오류, 페이지, 그리고 여러분이 어떤 계정으로 로그인했는지 알려 주세요.

대시보드 페이지가 신규 사용자에게 빈 화면으로 나와. 콘솔: ProjectList.tsx:18에서 TypeError: Cannot read properties of undefined (reading 'map'). 프로젝트가 있는 내 계정에서는 잘 동작해. 빈 계정에서는 “아직 프로젝트가 없습니다”라고 보이게 고치고, 미리보기에서 새 계정으로 확인해 줘.

5단계: 에러 바운더리 추가하기

React에서는 컴포넌트 하나가 크래시해도 앱 전체가 언마운트될 수 있어서, 작은 버그 하나로 완전히 빈 페이지가 나올 수 있어요. 에러 바운더리는 아래에서 발생한 렌더링 오류를 잡아서, 대신 대체 화면을 보여 주는 컴포넌트예요.

주요 라우트 주변에 에러 바운더리를 추가해 줘. “문제가 발생했습니다”와 다시 불러오기 버튼을 보여 주고, 오류를 콘솔에 기록하게 해. 헤더와 내비게이션은 바운더리 밖에 두어서 계속 보이게 해 줘.

이것이 버그를 고쳐 주지는 않지만, 방문자는 빈 화면 대신 메시지를 보고, 여러분은 어디서 깨졌는지 알 수 있어요.

6단계: 오류는 없는데 여전히 빈 화면

콘솔이 깨끗하고 스크립트도 로드되었다면:

• Elements 탭을 확인하세요. <div id="root"> 안에 콘텐츠가 있나요? 있다면 렌더링은 되었지만 보이지 않는 거예요. 흰 글자가 흰 배경 위에 있거나, opacity: 0, display: none이거나, 전체 화면을 덮는 요소가 있을 수 있어요.
• 라우터를 확인하세요. 현재 URL과 맞는 라우트가 없고 “찾을 수 없음” 라우트도 없으면, 일부 라우터는 아무것도 렌더링하지 않아요. 404 페이지를 보여 주는 캐치올 라우트를 추가하세요.
• 마운트 지점을 확인하세요. 코드는 존재하는 요소에 마운트해야 해요. index.html에 id="app"이 있는데 코드가 root를 찾으면 아무것도 나타나지 않아요(보통 React가 오류를 기록해요).
• 브라우저 확장 프로그램을 확인하세요. 비공개 창에서 시도해 보세요. 광고 차단기가 analytics나 ads 같은 이름의 스크립트를 가끔 막기도 해요.

새로 고침할 때만 빈 화면인가요?

홈페이지는 잘 되는데 /dashboard를 새로 고치면 빈 화면이나 404가 나온다면, 서버가 앱 경로에 대해 index.html을 보내는 법을 모르는 거예요. 이는 라우팅 폴백 문제이며, 배포 후 404 오류 해결하는 법에서 다뤄요.

흔한 실수

• 첫 번째가 아니라 마지막 오류를 읽기. 보통 원인은 맨 처음의 빨간 줄이에요.
• 다시 빌드하지 않고 환경 변수 설정하기. 프런트엔드 변수는 빌드 시점에 고정돼요.
• 내 계정으로만 테스트하기. 빈 계정에서 발생하는 크래시는 가장 흔한 빈 화면 원인 중 하나예요.
• 배포가 성공했다고 가정하기. 코드를 디버깅하기 전에 빌드 로그를 확인하세요.
• 모든 것을 브라우저 캐시 탓으로 돌리기. 강력 새로 고침으로 몇 초 만에 배제할 수 있어요. 그래도 빈 화면이라면 다른 문제예요.

Mythex에서의 빈 화면

미리보기가 비어 있다면, 먼저 앱이 실행 중인지 확인하세요(코드 → 터미널 열기). 그다음 Mythex에 올바른 서버를 시작해 달라고 요청하거나, 미리보기 도구 모음의 새로 고침을 누르거나, **/fix**를 사용하세요. 게시된 URL이 빈 화면이라면, 문서에서는 1분 정도 기다렸다가 강력 새로 고침을 하고, 게시 전에 환경 변수와 데이터베이스가 설정되었는지 확인하고, 호스팅 한도를 점검하라고 안내해요. 게시된 앱은 스냅샷이므로, 무엇인가를 고친 후에는 다시 게시하세요. 변경 때문에 생긴 문제라면, 마지막으로 잘 동작했던 답변의 이 시점으로 되돌리기로 프로젝트를 되돌릴 수 있어요. 자세한 내용은 문서의 문제 해결과 게시 문제 해결, 그리고 일반적인 AI로 만든 앱 디버깅하는 법 가이드를 참고하세요.

흰 화면 체크리스트

• 콘솔의 첫 번째 빨간 오류를 읽음
• 404 상태이거나 HTML을 반환하는 .js/.css 파일을 네트워크 탭에서 확인함
• 기본 경로가 앱이 제공되는 위치와 일치함
• 빌드가 끝났고, 빌드 결과물 폴더가 게시됨
• 라이브 빌드에 모든 프런트엔드 환경 변수가 설정되었고, 다시 빌드함
• 빈 계정과 신규 계정에서도 크래시가 해결됨
• 앞으로의 크래시가 메시지로 보이도록 에러 바운더리가 있음
• 알 수 없는 URL을 위한 캐치올 라우트가 있음
• 강력 새로 고침과 비공개 창에서 테스트함

자주 묻는 질문