문제 해결: 브라우저

임베디드 브라우저 패널의 일반적인 이슈를 해결합니다.

로컬호스트 앱이 로드되지 않음

증상: 브라우저 패널에서 http://localhost:3000으로 이동하지만 연결 오류 또는 빈 페이지가 표시됩니다.

해결:

  • 개발 서버가 실제로 실행 중인지 확인합니다. 터미널을 확인하세요 — 시작 메시지를 찾습니다(예: Next.js의 ready on http://localhost:3000 또는 Vite의 Local: http://localhost:5173/). 서버가 실행 중이 아니면 일반 명령(npm run dev, yarn dev 등)으로 시작합니다.
  • localhost 대신 127.0.0.1을 시도합니다. 일부 시스템은 localhost를 예상과 다르게 해석합니다. URL 바에서 localhost를 127.0.0.1로 바꾸세요 — 예: http://127.0.0.1:3000.
  • Content-Security-Policy 헤더. 앱이 웹뷰에 임베딩을 방지하는 엄격한 CSP 헤더를 설정하면 브라우저 패널이 표시를 거부합니다. 개발 모드에서 이러한 헤더를 완화할 수 있습니다. 예를 들어 Next.js에서 로컬 개발 전용으로 next.config.js에서 frame-ancestors 지시문을 제거하거나 완화할 수 있습니다.

브라우저 패널 높이가 축소됨

증상: 브라우저 패널이 얇은 스트립으로 축소되고 앱을 볼 수 없습니다.

해결: 패널 구분선(브라우저 패널과 위아래 패널 사이의 얇은 바)을 드래그하여 브라우저 크기를 조정합니다. 위로 클릭하고 드래그하여 브라우저에 더 많은 수직 공간을 줍니다.

브라우저가 가능한 많은 공간을 차지하게 하려면 전체 화면 모드를 사용하세요: Cmd+Shift+F (또는 Windows/Linux에서 Ctrl+Shift+F)를 눌러 브라우저 패널을 창을 채우도록 확장합니다. 동일한 단축키를 눌러 일반 레이아웃으로 돌아갑니다.

비디오 또는 오디오가 재생되지 않음

임베디드 브라우저 패널은 모든 미디어 코덱을 지원하지 않습니다. 특정 비디오 형식 또는 오디오 스트림이 패널 내에서 재생에 실패할 수 있습니다.

해결: 브라우저 패널 내에서 우클릭하고 Open in External Browser를 선택합니다. 현재 URL이 시스템의 기본 브라우저(Safari, Chrome, Firefox 등)에서 열리며 완전한 코덱 지원을 제공합니다. 미디어 중심 페이지, 비디오 플레이어 또는 브라우저 플러그인이 필요한 것에 사용하세요.

페이지가 빈/흰 화면 표시

빈 흰 화면은 일반적으로 페이지가 로드되었지만 콘텐츠가 표시되기 전에 JavaScript에서 무언가 잘못되었음을 의미합니다.

해결:

  1. 브라우저 패널 툴바에서 DevTools 버튼을 클릭합니다 (렌치 또는 </> 아이콘).
  2. Console 탭을 엽니다.
  3. 빨간색 오류 메시지를 찾습니다.

로컬 개발에서 가장 일반적인 원인은 CORS 오류입니다 — 프론트엔드가 로컬 API에 요청을 보내고 API가 localhost가 아닌 webview 오리진에서 요청이 오므로 거부합니다. 개발에서 이를 수정하려면 API 서버가 모든 오리진을 허용하도록 구성합니다:

  • Express / Node: cors 패키지로 app.use(cors())를 추가합니다.
  • FastAPI: 개발용 allow_origins=["*"]로 CORSMiddleware를 추가합니다.
  • Next.js API 라우트: 라우트 핸들러의 응답 헤더에 Access-Control-Allow-Origin: *를 추가합니다.

프로덕션에 배포하기 전에 오리진을 다시 제한하는 것을 기억하세요.