내 컴퓨터에서 잘 돌아가던 서비스가 배포하자마자 하얀 화면이 되거나 에러를 뱉는 일은 바이브코딩에서 가장 흔한 사고입니다. 원인은 거의 정해져 있습니다. 아래 7가지를 순서대로 확인하면 대부분 여기서 잡힙니다.
왜 로컬과 배포 환경이 다른가요?
내 컴퓨터에는 개발하면서 쌓인 설정과 파일이 있지만, 배포 서버는 매번 빈 상태에서 시작하기 때문입니다. 내 컴퓨터에만 있고 서버에는 없는 것이 하나라도 있으면 그 지점에서 멈춥니다. 그래서 확인 순서는 항상 "서버에 없는 것이 무엇인가"부터입니다.
순서대로 확인할 7가지
- 환경변수를 배포 서버에도 등록했는가 — .env 파일은 서버에 올라가지 않습니다. Vercel·Cloudflare 등 배포 서비스의 설정 화면에 따로 넣어야 합니다.
- 파일명 대소문자가 정확한가 — 맥과 윈도우는 대소문자를 구분하지 않지만 배포 서버(리눅스)는 구분합니다. Header.tsx와 header.tsx는 서버에서 다른 파일입니다.
- 빌드가 실제로 성공했는가 — 배포 서비스의 빌드 로그를 끝까지 읽어보세요. 빨간 글씨가 있으면 배포된 것은 예전 버전입니다.
- 외부 서비스에 새 주소를 알려줬는가 — 결제사, 로그인, 데이터베이스의 허용 주소 목록에 배포 도메인을 추가해야 합니다.
- 개발용 키를 그대로 쓰고 있지 않은가 — 테스트 키와 운영 키가 다른 서비스가 많습니다.
- 설치되지 않은 라이브러리를 쓰고 있지 않은가 — 내 컴퓨터에만 설치해 두고 목록 파일에 기록하지 않은 경우입니다.
- 브라우저에서만 되는 코드를 서버에서 실행하고 있지 않은가 — window나 localStorage를 서버가 먼저 읽으면 그 자리에서 멈춥니다.
원인을 빨리 찾는 방법은?
배포 서비스의 로그와 브라우저 개발자 도구(F12)의 콘솔, 이 두 곳만 보면 됩니다. 화면이 하얗다면 콘솔의 첫 번째 빨간 줄이 범인입니다. 그 문장을 그대로 복사해서 AI에게 붙여넣고 "이 에러가 배포 환경에서만 나는 이유와 해결 방법"을 물어보세요.
배포는 매번 처음부터 다시 조립하는 과정입니다. 내 컴퓨터에만 있는 것을 하나씩 줄이면 배포 사고도 같이 줄어듭니다.
이 7가지를 포함해 출시 전에 확인해야 할 항목을 전부 정리한 체크리스트를 무료로 배포하고 있습니다. 보안, 개인정보, 성능, 결제까지 9개 장으로 되어 있고 각 항목마다 AI에게 그대로 붙여넣을 프롬프트가 붙어 있습니다.