빌드 및 미리보기 문제 해결

빌드에 실패하거나 미리보기가 로드되지 않으면, 먼저 화면에 보이는 첫 번째 오류부터 확인하고 해당 증상에 맞는 복구 경로를 따라 진행하세요. 이 페이지에서는 App 뷰어, Preview, 빌드 오류, 그리고 문제를 신고하기 전에 수행해야 할 단계를 다룹니다.

여기서 시작하세요

에이전트가 작업을 마치면 App 뷰어가 앱을 로드합니다. 터미널에는 작업 활동과 오류가 표시되며, App 뷰어 도구 모음에서는 Reload App Viewer 컨트롤, 기기 보기 전환, 새 탭에서 미리보기를 여는 옵션, 그리고 Console을 사용할 수 있습니다.

1. 최신 변경 사항을 저장하고 현재 작업 또는 빌드가 완료될 때까지 기다리세요.
2. 미리보기가 오래된 상태로 보이거나 로딩 화면에 계속 머무르면 Reload App Viewer를 한 번 선택하세요.
3. 내장된 App 뷰어가 멈추었거나 응답하지 않으면 새 탭에서 미리보기를 여세요.
4. Console을 열고 처음으로 보이는 오류를 복사하세요. 프로젝트 링크와 오류가 발생한 시간도 함께 보관하세요.

빌드가 실패할 때

먼저 Resolve를 시도하세요

Atoms가 빌드 문제를 감지하면 왼쪽 하단에 문제 신고 알림이 표시됩니다. 알림에 Resolve가 포함되어 있으면 다른 조치를 취하기 전에 먼저 한 번 복구를 시도하세요.

1. Resolve를 선택하고 현재 시도가 완료될 때까지 기다리세요.
2. 실행 중일 때는 Resolve를 다시 선택하지 마세요.
3. 시도가 완료되지 않으면 화면에 보이는 상태를 기록하고 아래의 신고 단계로 진행하세요. Resolve를 다시 시도하지 마세요.
4. 시도가 완료되면 새로고침된 미리보기를 확인하세요. 업데이트되지 않으면 브라우저를 한 번 새로고침하세요.
5. 문제를 일으킨 작업을 다시 반복하세요. 문제가 계속되면 문제 신고를 펼치고 아래의 신고 단계로 진행하세요.

빌드 오류 또는 누락된 종속성

Preview 패널에 빌드 오류, 빨간 오류 배너 또는 누락된 패키지에 대한 메시지가 표시되면, 다음 단계를 좁히기 위해 정확한 메시지를 사용하세요.

1. Console을 열고 거기에 표시되는 전체 오류 메시지를 복사하세요.
2. Resolve를 사용할 수 있으면 한 번 사용하고 시도가 완료될 때까지 기다리세요.
3. Resolve 버튼이 없으면 정확한 오류를 Project chat에 붙여넣고 에이전트에게 해당 빌드 오류를 수정해 달라고 요청하세요.
4. 특정 변경 이후 오류가 시작되었다면 History를 열고 현재 버전을 마지막으로 정상 작동한 버전과 비교하세요.
5. 오류를 분리하기 어렵다면 마지막 안정 버전에서 리믹스하고 변경 사항을 점진적으로 다시 적용하세요.

App 뷰어, 시작 스크립트, Publish, 배포 기록 또는 서드파티 패키지의 내부 파일을 언급하는 오류는 플랫폼 문제를 나타낼 수 있습니다. Support에 문의할 때 전체 오류 메시지를 포함하세요.

빌드가 계속 진행 중으로 남아 있음

다시 시도하기 전에 터미널에서 현재 작업 활동을 확인하세요. 작업 또는 빌드가 아직 실행 중이면 완료될 때까지 기다리세요. 현재 시도가 끝난 뒤에도 계속 진행 중으로 남아 있으면 상태, 타임스탬프, 프로젝트 링크, 그리고 화면에 보이는 오류 세부 정보를 기록한 다음 문제를 신고하세요.

Preview 또는 App 뷰어가 로드되지 않을 때

로딩 화면 또는 응답하지 않는 미리보기

먼저 내장된 App 뷰어만 영향을 받는지, 아니면 Preview URL과 게시된 사이트도 영향을 받는지 확인하세요.

1. 현재 작업 또는 빌드가 아직 실행 중인지 확인하세요.
2. Reload App Viewer를 한 번 선택하세요.
3. 새 브라우저 탭에서 Preview를 여세요.
4. 같은 URL을 시크릿 창에서 테스트하세요.
5. 마지막으로 정상 작동한 버전이 로드되면, 문제를 일으킨 최근 변경 사항과 비교하세요.

제품에서 Cloud & AI 잔액 부족 또는 앱 일시 중지를 명시적으로 보고하는 경우 Settings → Cloud & AI를 열어 해당 상태를 검토하세요. 단순히 빈 화면만 보고 충전하지 마세요.

빈 화면 또는 불완전한 미리보기

빈 화면이 전체 앱에 영향을 주는지, 아니면 한 페이지나 컴포넌트에만 영향을 주는지 확인하세요. 한 영역만 영향을 받는다면 페이지 선택기를 사용해 해당 페이지를 직접 열고, 그 페이지에 도달하는 가장 작은 사용자 여정을 다시 수행하세요. 전체 미리보기가 비어 있다면 빌드 결과로 돌아가 첫 번째 빌드 또는 런타임 오류를 해결한 뒤 다시 테스트하세요.

쿠키, 토큰 또는 비밀 값을 공유하지 않은 상태로 Console 또는 Network 오류를 기록하세요. 문제가 계속되면 정리된 오류 세부 정보를 신고에 포함하세요.

Preview에 이전 버전이 표시됨

Preview와 게시된 사이트는 별도의 채널입니다. 미리보기를 새로고침하기 전에 최신 변경 사항이 저장되었고 최신 빌드가 완료되었는지 확인하세요. 빌드가 완료된 후 Preview를 다시 여세요. 그래도 이전 콘텐츠가 표시되면 History에서 현재 버전을 마지막으로 정상 작동한 버전과 비교하세요.

미리보기가 잘못 표시될 때

상호작용 또는 탐색이 작동하지 않음

페이지가 렌더링된다고 해서 페이지가 제대로 작동하는 것은 아닙니다. 중요한 모든 탐색 링크를 열고, 주요 버튼을 누르고, 핵심 양식을 제출하고, 시작부터 끝까지 주요 사용자 여정을 따라가세요. 하나의 상호작용이 실패하면 예상한 결과가 멈추는 정확한 작업을 기록하고, 각 수정 후 그 경로를 다시 테스트하세요.

모바일 레이아웃이 깨짐

1. App 뷰어 도구 모음의 기기 전환을 사용해 모바일 보기로 전환하세요.
2. 사용 가능하면 Design mode에서 깨진 요소를 선택하세요.
3. 기대한 모바일 레이아웃과 변경되면 안 되는 사항을 설명하세요.
4. 한 번에 하나의 변경만 적용한 다음 데스크톱 및 모바일 보기와 로딩, 빈 상태, hover, 오류 상태를 확인하세요.

이미지 또는 기타 에셋이 누락됨

1. Files 섹션을 열고 참조된 파일이 존재하는지 확인하세요.
2. 경로, 파일 이름, 형식이 앱에서 사용하는 참조와 일치하는지 확인하세요.
3. 에셋이 최근 이동되었거나 이름이 변경되었다면 참조를 복원하거나 의도적으로 업데이트하세요.
4. Reload App Viewer를 선택하고 영향을 받은 페이지를 다시 테스트하세요.

에이전트가 잘못된 요소를 변경했거나 다른 영역을 망가뜨림

1. History를 열고 마지막 안정 버전에서 리믹스하세요.
2. 사용 가능하면 Design mode를 사용해 정확한 요소를 지정하세요.
3. 변경되면 안 되는 사항을 명시하고 프롬프트당 하나의 변경만 수행하세요.
4. 다음 변경으로 넘어가기 전에 결과를 확인하세요.

문제 신고

Resolve를 사용할 수 없거나, 완료된 Resolve 시도 후에도 문제가 계속되거나, Preview가 응답하지 않지만 Project chat은 여전히 작동하거나, 에이전트가 조사한 후에도 예상치 못한 동작이 계속되면 문제를 신고하세요.

Project chat에서 Feedback 열기

1. 영향을 받은 Project chat을 열고 가장 최근의 관련 에이전트 메시지를 찾으세요.
2. ... (추가 옵션)을 선택한 다음 Feedback을 선택하세요.
3. 지원 메신저에서 Send us a message를 선택하고, 기존 대화가 이미 있으면 그 대화에서 신고를 보내세요.

전체 문제 신고 흐름은 문제 신고를 참조하세요.

문제를 재현할 수 있을 만큼 충분한 세부 정보를 포함하세요

• 문제 요약. 문제를 한두 문장으로 설명하세요.
• 프로젝트 또는 채팅 링크. 문제가 발생한 URL을 포함하세요.
• 날짜 및 시간. 시간대를 포함하세요.
• 재현 단계. 정확한 작업을 순서대로 나열하세요.
• 예상 결과와 실제 결과. 어떤 일이 일어났어야 했는지와 실제로 어떤 일이 일어났는지 명시하세요.
• 이미 시도한 내용. Resolve가 표시되었는지, 완료 후 어떤 일이 있었는지, 새로고침이나 리믹스로 결과가 바뀌었는지 알려주세요.
• 브라우저 및 기기. 브라우저, 운영 체제, 기기 유형을 포함하세요.
• 증거. 스크린샷 또는 녹화와 관련된 화면상의 문제 신고 또는 Console 세부 정보를 첨부하세요.

스크린샷이나 로그를 공유하기 전에 비밀번호, API 키, 인증 토큰, 쿠키, 결제 정보, 그리고 관련 없는 개인 또는 기밀 데이터를 제거하세요.

문제가 해결된 후

주요 사용자 여정을 처음부터 끝까지 실행하세요. 데스크톱 및 모바일 보기 모두에서 Preview를 확인하고, 페이지 선택기에서 각 페이지를 열고, Console에 빨간 오류 메시지가 없는지 확인하세요. 앱을 게시할 준비가 되었다면 자리표시자 콘텐츠를 교체하고 App 뷰어에서 게시 점검을 완료하세요.

FAQ