SwiftUI Preview가 열리지 않거나 계속 새로 고침에 실패하면 전체 캐시 삭제나 Xcode 재설치부터 시작하지 않아야 합니다. 이 글은 진단 보고서를 기준으로 단순한 SwiftUI 프로젝트, 데이터 기반 앱, 패키지 의존성, 원격 맥 환경을 나누어 복구 순서를 제시합니다.
SwiftUI Preview가 열리지 않거나 계속 새로 고침에 실패하면 전체 캐시 삭제나 Xcode 재설치부터 시작하지 않아야 합니다. 이 글은 진단 보고서를 기준으로 단순한 SwiftUI 프로젝트, 데이터 기반 앱, 패키지 의존성, 원격 맥 환경을 나누어 복구 순서를 제시합니다.
Apple은 Xcode 14 출시 문서에서 캔버스의 미리보기 진단 보고서 생성 기능을 안내합니다. Xcode 14 출시 문서의 진단 절차를 먼저 실행하는 것이 가장 빠른 출발점입니다. SwiftUI Preview가 작동하지 않을 때 전체 캐시를 먼저 지우거나 Xcode를 다시 설치하지 말고, 진단 보고서로 코드, 의존성, 시뮬레이터 실행 환경, 시스템 권한을 구분해야 합니다.
이 글은 SwiftUI로 화면을 반복 제작하는 독립 개발자, 시뮬레이터에서는 앱이 실행되지만 캔버스만 실패하는 개발자, VNC나 원격 데스크톱으로 맥을 사용하며 장기 개발 환경을 관리하는 소규모 팀을 위한 점검 가이드입니다.
Preview 빌드와 일반 빌드는 같은 결과를 보장하지 않습니다. Apple의 SwiftUI 미리보기 작동 방식 문서는 캔버스에서 화면을 구성하고 미리보기 데이터를 실행하는 별도 흐름을 설명합니다. 반면 시뮬레이터와 실제 기기 실행 문서는 앱을 목적지에 설치하고 실행하는 절차를 다룹니다.
따라서 다음 상태를 한 번에 기록해야 합니다.
캔버스에서 진단 메뉴를 열어 보고서를 저장합니다. Apple 개발자 포럼의 Preview 진단 보고서 관련 논의에서도 로그를 먼저 확인하는 방식이 문제 분리에 사용됩니다. 보고서에는 첫 번째 컴파일 오류, 로딩 실패, 런타임 연결 오류가 함께 나타날 수 있으므로 마지막 오류보다 먼저 나온 의미 있는 오류를 우선 기록해야 합니다.
시뮬레이터에서는 실행되는데 Xcode Preview만 열리지 않는 경우에는 어떻게 판단해야 합니까?
앱 실행 성공은 Preview 성공의 증거가 아닙니다. Preview가 사용하는 미리보기 매크로, 샘플 데이터, 별도 로딩 과정이 일반 실행에서 호출되지 않을 수 있습니다. 새 SwiftUI 프로젝트에 같은 단순 화면을 옮겨 확인했을 때 정상이라면 현재 프로젝트의 의존성이나 초기화 코드가 우선 의심 대상입니다.
단일 대상 프로젝트에서는 화면 자체와 미리보기 생성 코드를 먼저 분리합니다. 파일에 유효한 Preview 매크로가 있는지 확인하고, 미리보기 객체를 만드는 순간 네트워크 요청, 파일 읽기, 데이터베이스 연결, 로그인 확인이 실행되는지 살펴봅니다. Apple 문서에 설명된 Preview 매크로 사용 방식과 실제 프로젝트의 초기화 순서를 나란히 비교해야 합니다.
화면을 다음 순서로 줄입니다.
Cannot preview in this file와 비슷한 문구가 보인다면 파일 자체가 잘못되었다고 단정하지 않아야 합니다. 대상 스킴, 플랫폼, 매크로 인식, 컴파일 실패가 같은 화면에서 함께 표시될 수 있기 때문입니다. 정적 화면도 실패하면 코드 한 파일보다 프로젝트 설정이나 도구 환경을 먼저 비교합니다.
미리보기 데이터는 운영 데이터와 분리해야 합니다. 로그인 상태에 의존하는 전역 객체, 원격 API 응답을 기다리는 초기화, 매번 다른 값을 반환하는 싱글턴은 캔버스의 반복 실행과 맞지 않습니다. 고정 샘플과 메모리 저장소를 준비하면 객체 생성 실패, 빈 데이터, 실제 화면 렌더링 실패를 서로 나누어 볼 수 있습니다.
SwiftData를 사용하는 앱은 미리보기 전용 컨테이너를 준비하는 편이 안전합니다. 운영 데이터베이스 경로를 그대로 연결하지 말고, 예측 가능한 샘플 객체를 메모리에서 생성합니다. 외부 서비스도 같은 원칙을 적용합니다.
SwiftData의 특정 버전 동작을 근거 없이 일반화하면 안 됩니다. Xcode 26 출시 문서에 변경 사항이 있는지 확인하고, 공식 문서에 없는 현상은 특정 프로젝트에서만 확인된 사례로 남겨야 합니다. 개발자 포럼의 Xcode Previews 사례 모음도 해결책의 확정 근거가 아니라 비교용 단서로 사용합니다.
여러 대상이나 Swift Package를 사용하는 프로젝트에서는 Preview가 어느 대상에 속했는지부터 확인합니다. 일반 컴파일이 성공해도 캔버스의 실행 시점 연결이 성공한다는 뜻은 아닙니다. 의존성 해결, 일반 빌드, Preview 런타임 연결은 각각 독립적으로 검증해야 합니다.
| 확인 영역 | 정상으로 볼 조건 | 실패 때 우선 확인할 곳 | 판단 |
|---|---|---|---|
| 대상과 스킴 | 화면 파일과 선택 대상이 일치함 | 대상 설정과 활성 스킴 | 설정 문제 가능성 |
| 패키지 제품 | 필요한 제품이 대상에 연결됨 | 패키지 제품 연결 | 연결 수정 우선 |
| 자원 파일 | 캔버스 실행 위치에서 읽힘 | 복사 단계와 자원 경로 | 자원 경계 문제 |
| 런타임 연결 | 첫 연결 오류가 없음 | 링크 로그와 모듈 이름 | Runtime Linking Failure 조사 |
| 최소 프로젝트 | 같은 화면이 독립 실행됨 | 현재 프로젝트와 차이 | 환경 또는 프로젝트 분리 |
대상 구성은 Xcode 대상 설정 문서에서 확인하고, 제품과 자원의 연결은 Build Phases 설정 문서를 기준으로 대조합니다. 오류 로그에 표시되는 모듈 이름과 가상의 경로는 외부에 공유하기 전에 가려야 합니다.
SwiftUI Preview의 Runtime Linking Failure는 어디서 시작해야 합니까?
첫 번째 링크 오류를 시작점으로 삼아야 합니다. 누락된 모듈, 대상 플랫폼이 맞지 않는 패키지, 대상에 연결되지 않은 제품, 자원 파일 누락을 순서대로 확인합니다. Package.resolved를 반복해서 삭제하는 것은 의존성 상태를 새로 만드는 조치일 뿐, 잘못된 대상 연결을 고치는 방법은 아닙니다. 삭제 전에는 현재 파일을 보관하고, 변경 후에는 같은 스킴으로 일반 빌드와 Preview를 각각 다시 확인합니다.
원격 맥에서 Xcode Canvas가 계속 새로 고쳐진다면 네트워크 지연만 의심하지 않아야 합니다. Xcode가 실제 그래픽 로그인 세션 안에서 실행되는지, VNC 연결이 잠금 화면이나 끊긴 세션을 다시 보여 주는 상태인지 먼저 확인합니다. 그래픽 세션이 유효하지 않으면 캔버스와 시뮬레이터가 같은 방식으로 보이지 않을 수 있습니다.
프로젝트 디렉터리, DerivedData, 시뮬레이터 데이터, 임시 디렉터리의 소유자와 쓰기 권한도 확인합니다. 보호된 위치와 일반 개발 폴더에 최소 프로젝트를 각각 두고 결과를 비교하면 파일 접근 제한 여부를 좁힐 수 있습니다. 전체 디스크 접근 권한을 무조건 부여하는 방식은 권장하지 않습니다. 필요한 폴더와 실제 오류를 먼저 확인한 뒤 최소 범위로 조정해야 합니다.
장기 원격 환경을 선택할 때는 VNCMac의 원격 맥 이용 방식을 참고하되, Preview가 실제 프로젝트에서 복구되는지 별도로 검증해야 합니다. 원격 맥에서 시뮬레이터를 함께 사용할 예정이라면 로그인 세션, 그래픽 표시, 런타임 설치 상태를 작은 테스트 프로젝트로 먼저 확인하는 편이 안전합니다.
DerivedData를 지우면 SwiftUI Preview가 고쳐집니까?
가능성은 있지만 보장되지 않습니다. DerivedData 정리는 이전 빌드 산출물이나 인덱스를 다시 만들게 하는 국소 조치입니다. 소스 코드의 초기화 오류, 패키지 연결 오류, 권한 오류, 그래픽 세션 문제까지 해결하지는 않습니다.
다음 조건을 만족할 때만 정리를 고려합니다.
정리 뒤에는 Xcode를 다시 열고 일반 빌드, 정적 Preview, 데이터 의존 Preview를 차례로 확인합니다. 무차별적인 전체 삭제 명령은 범위가 넓고 복구 비용이 있으므로, 경로를 확인하지 않은 상태에서 실행하지 않아야 합니다.
모든 개발자가 같은 해결책을 선택할 필요는 없습니다. 다음 조건으로 조치 범위를 정하면 불필요한 재설치를 줄일 수 있습니다.
복구 판정은 캔버스가 한 번 열린 것만으로 끝내지 않습니다. 정적 화면, 상호작용 화면, 의존성이 있는 화면, Xcode 재시작 뒤의 재현 여부를 모두 확인해야 합니다. 수정 전후의 도구 버전, 선택 스킴, 프로젝트 경로, 그래픽 세션 상태, 진단 보고서를 남기면 다음 장애 때 같은 실험을 반복하지 않아도 됩니다.
현재 맥에서 최소 프로젝트조차 안정적으로 복구되지 않는다면, 기존 환경을 계속 붙잡는 것보다 권한과 런타임을 독립적으로 초기화할 수 있는 환경에서 실제 SwiftUI 프로젝트를 먼저 검증하는 편이 합리적입니다. 개인 맥은 저장 공간과 장시간 실행 부담이 있고, 일반 클라우드 개발 환경은 Xcode와 macOS 전용 도구를 직접 제공하지 못할 수 있으며, 불안정한 원격 세션은 캔버스와 시뮬레이터 확인을 방해합니다. 이런 조건에서는 VNCMac의 맥 임대 환경을 테스트 작업 공간으로 사용해 로그인 세션, 폴더 권한, 시뮬레이터 런타임, Preview 재시작 복구를 실제 프로젝트로 먼저 검증할 수 있습니다. 다만 물리 장치 연결이 항상 필요하거나 장기간 고정 부하가 핵심이면 직접 보유한 맥이 더 적합할 수 있습니다.