문제 해결
라우트가 표시되지 않음
- 애플리케이션 라우터에 맞는 어댑터를 설치했는지 확인합니다.
- PageFlow가 프로덕션 미리보기가 아닌 개발 서버에서 실행되는지 확인합니다.
- 분석 가능한 라우터가 없는 일반 Vite 설정에서는 통합이 지원할 경우 명시적 라우트를 제공합니다.
동적 페이지가 열리지 않음
dynamicParams에 안전한 예시 값을 추가하세요. 라우트 패턴을 확인하고 생성된 URL을 직접 열어 인증이나 로더 리디렉션을 확인합니다.
미리보기가 비어 있거나 계속 로딩됨
- 애플리케이션 콘솔과 네트워크 요청을 확인합니다.
- 현재 브라우저 세션에서 페이지가 렌더링되는지 확인합니다.
- 필요한 글꼴과 이미지가 로드될 때까지 기다립니다.
- 비동기 작업이 오래 걸리면 페이지 준비 후
window.__UNPLUGIN_PAGEFLOW_READY__?.()를 호출합니다.
탐색이 누락됨
PageFlow는 지원되는 링크와 리터럴 대상을 찾습니다. 계산된 프로그래밍 대상은 상호작용 후에만 나타날 수 있습니다. Astro island 내부는 의도적으로 분석하지 않으므로 필요하면 동일 출처 앵커나 data-pageflow-to를 사용하세요.
썸네일이 오래됨
캡처 대기열이 보이는 페이지를 갱신할 시간을 주세요. 캐시가 더 이상 필요하지 않으면 개발 서버를 중지하고 .unplugin-pageflow/cache를 삭제합니다.
인증 페이지가 표시됨
인증은 현재 브라우저 세션을 사용합니다. 같은 세션에서 로컬 애플리케이션에 로그인하거나 정상적인 로그인·접근 거부 화면을 정확한 미리보기로 간주하세요.
테스트가 연결되지 않음
자동 연결 규칙을 확인한 뒤 명시적 pageTests 매핑을 추가하세요. 테스트 종류에 testCommands 항목이 설정되어야 실행할 수 있습니다.
Next.js sidecar 실패
애플리케이션이 실행 중인지, sidecar 호스트와 포트를 사용할 수 있는지, 두 화면이 예상한 동일 출처 설정을 사용하는지 확인하세요. Next.js 가이드를 참고하세요.