애플 공식 문서는 Xcode Canvas에서 SwiftUI, UIKit, AppKit 미리보기를 다룬다고 설명합니다. Canvas 미리보기 상호작용 안내를 기준으로 보면, Preview가 안 보일 때는 먼저 화면 상태와 진단 기록을 확인해야 합니다.
증상 → 빠른 조치: 캔버스가 비어 있거나 갱신 오류가 나면 Preview Diagnostics에서 첫 유효 오류를 확인하세요. 전체 캐시 삭제나 Xcode 재설치부터 시작하지 말고, 최소 예제·일반 Build·올바른 실행 대상을 비교해 원인을 좁히세요.
이 글은 원격 맥에서 SwiftUI 파일을 편집하지만 Xcode Canvas가 비어 있거나 업데이트 오류를 표시하는 독립 개발자를 위한 안내입니다. 일반 Build는 성공하는데 Preview만 시작되지 않아 코드와 실행 환경을 구분해야 하는 유지보수 담당자도 참고할 수 있습니다. 여러 사람이 한 원격 맥을 함께 쓰며 계정이나 디렉터리 소유권을 의심하는 소규모 팀에도 해당합니다.
SECTION 01먼저 구분할 Preview 실패 유형
Canvas가 접혀 있거나 일시 정지된 상태라면 실행 오류처럼 보여도 미리보기 프로세스 문제는 아닐 수 있습니다. 반면 업데이트 오류, 시작 지연, 실행 직후 종료는 각각 확인할 단서가 다릅니다. Canvas 조작과 미리보기 진단 위치는 애플의 Canvas 안내에서 확인할 수 있습니다.
이슈 탐색기와 Preview Diagnostics에서 가장 먼저 실패한 항목을 찾으세요. 뒤에 이어지는 모듈 로드 실패나 실행 오류는 첫 실패에서 파생된 결과일 수 있습니다. 로그를 공유하거나 기록할 때 프로젝트 이름, 사용자 이름, 경로, 기기 이름은 가려야 합니다.
| 관찰된 증상 | 우선 확인할 곳 | 다음 비교 |
|---|---|---|
| 캔버스가 보이지 않거나 멈춤 | Canvas 표시 상태와 일시 정지 여부 | 캔버스를 다시 열고 미리보기 갱신 여부 확인 |
| Preview Update Error | Preview Diagnostics의 첫 실패 항목 | 실패한 대상, 모듈, 파일 경로 추적 |
| 시작 중 멈추거나 실행 직후 종료 | 실행 대상과 런타임, 초기화 데이터 | 같은 대상으로 일반 Build와 Simulator 실행 비교 |
| JIT 또는 파일 접근 오류 | 실행 계정과 미리보기 경로 소유권 | 같은 계정으로 연 최소 예제에서 재현 확인 |
일반 Build가 성공해도 Preview 실행이 정상이라고 단정할 수는 없습니다. Preview는 편집 중인 화면을 별도로 구성하고 실행하므로, 미리보기 데이터나 실행 경로에서만 문제가 드러날 수 있습니다.
SECTION 02최소 화면으로 파일과 미리보기 코드를 분리하기
현재 파일이 제대로 열려 있는지 확인한 뒤, 프로젝트 안에 의존성이 거의 없는 작은 SwiftUI 화면을 만들어 비교하세요. 해당 화면의 Preview 선언은 미리보기 추가 문서에 맞춰 작성합니다. 최소 화면이 표시되면 Xcode 전체보다는 기존 화면의 초기화 매개변수, 미리보기 데이터 또는 화면에서 참조하는 의존성을 우선 살펴볼 수 있습니다.
최소 화면도 표시되지 않는다면 선택한 Scheme과 미리보기 대상, 플랫폼 설정을 확인하세요. 이 비교는 문제 범위를 가르는 데 유용하지만 프로젝트를 대신 검증하지는 않습니다. 실제 화면에서 필요한 데이터가 미리보기 환경에서도 만들어지는지 별도로 확인해야 합니다.
진단 로그에서 실패한 파일이나 대상이 확인되기 전에는 DerivedData 전체를 지우지 마세요. 캐시를 지우면 재생성에 시간이 들고, 권한이나 잘못된 대상 선택 같은 원인은 그대로 남을 수 있습니다.
SECTION 03빌드 대상과 런타임 비교표
Preview에서 선택한 기기 환경이 Scheme의 대상 플랫폼과 맞는지 확인하세요. 필요한 Simulator 런타임이 설치되지 않았거나 배포 대상과 맞지 않으면, 이를 원격 접속 문제로 오인할 수 있습니다. Xcode의 빌드 설정 참고 문서에서 프로젝트 설정을 살피고, Simulator와 실제 기기 실행 안내를 기준으로 실행 대상을 구분하세요.
| 비교 항목 | 확인할 내용 | 불일치가 의심될 때 |
|---|---|---|
| Scheme와 Preview 대상 | 현재 앱 대상과 미리보기 대상이 같은지 | 올바른 Scheme과 대상을 다시 선택 |
| 플랫폼과 배포 대상 | 프로젝트 설정이 선택한 실행 환경을 지원하는지 | 변경 영향 검토 후 대상 설정 조정 |
| Simulator 런타임 | 선택한 런타임을 사용할 수 있는지 | 설치 여부와 선택 대상을 확인 |
| 일반 Build와 Preview | 같은 프로젝트 대상에서 각각 어떤 결과인지 | Build 성공 여부와 Preview 실패 로그를 별개로 기록 |
배포 대상이나 빌드 설정을 바꾸면 다른 빌드와 테스트 결과에도 영향이 생길 수 있습니다. Preview만 살리려고 프로젝트 설정을 넓게 변경하기보다, 변경 전후에 어떤 실행 대상이 달라지는지 확인하세요.
증상에 따른 다음 조치 결정
아래 순서대로 조건을 대조하고, 처음 맞는 항목의 조치를 선택하세요. 뒤쪽 단계로 건너뛰어 캐시나 권한을 한꺼번에 바꾸지 마세요.
- Canvas가 닫혔거나 일시 정지된 상태라면 → Canvas를 다시 열고 갱신하세요. 오류 기록이 없다면 캐시 삭제는 보류합니다.
- 최소 화면은 보이지만 기존 화면만 실패한다면 → 기존 화면의 초기화 매개변수, 미리보기 데이터, 연결된 의존성을 수정하세요.
- 일반 Build도 실패한다면 → Preview 전용 문제로 분류하지 말고 먼저 대상 프로젝트의 빌드 오류를 해결하세요.
- 일반 Build는 성공하지만 Preview만 실패한다면 → Preview Diagnostics의 첫 오류와 선택한 런타임을 대조하세요.
- 로그가 JIT 경로나 사용자 소유권을 지목한다면 → 해당 계정과 경로를 검증하세요. 단서가 없다면 전역 권한 변경은 하지 마세요.
- 로그가 원인을 특정하지 못한다면 → 같은 계정과 같은 대상으로 최소 예제를 다시 실행하고, 그 결과를 기준으로 대상 설정과 프로젝트 코드를 나눠 조사하세요.
SECTION 04의존성과 JIT 오류는 첫 실패 지점부터 추적하기
진단 로그가 모듈을 찾지 못하거나 개체 파일을 불러오지 못했다고 표시하면, 프로젝트 전체 캐시보다 오류에 적힌 Target과 의존 제품, 빌드 경로를 먼저 확인하세요. 코드 서명이나 JIT가 언급돼도 로그가 가리키는 대상과 계정을 맞춰 봐야 합니다. 서로 다른 원인을 단순히 “DerivedData 문제”로 묶으면 잘못된 조치로 이어질 수 있습니다.
원격 맥을 여러 계정이 함께 사용한다면 Xcode를 실행한 사용자, 프로젝트 파일을 읽고 쓸 수 있는 사용자, 미리보기 빌드 디렉터리의 소유자가 일치하는지 확인하세요. 다른 계정으로 로그인된 세션에서 만들어진 파일이 섞였는지도 살펴봅니다. Xcode 27.2 베타 릴리스 노트에는 다른 사용자 계정이 소유한 Previews JIT 디렉터리와 관련된 특정 실패 상황의 오류 안내 개선이 기록돼 있습니다. 이는 해당 사례에 한정된 내용이며 모든 Preview 문제의 원인이라는 뜻은 아닙니다. Xcode 27.2 베타 릴리스 노트에서 적용 범위를 확인하고, 사용 중인 버전의 공식 자료와 실제 로그를 대조하세요.
SECTION 05자주 묻는 Preview 점검 질문
Build는 되는데 Preview만 비어 있으면
먼저 Canvas가 숨겨졌거나 멈춘 상태인지 확인한 다음 진단 기록의 첫 오류를 살펴보세요. 이어서 최소 화면을 만들어 비교하고, 기존 화면에서만 실패하면 초기화 값과 미리보기 데이터, 의존성을 확인합니다. Preview 실행과 일반 Build는 서로 다른 검증 결과이므로 하나의 성공으로 다른 쪽을 통과 처리하지 마세요.
Preview Update Error의 진단 정보를 읽을 때
오류가 여러 줄이라면 맨 처음 실패한 항목이 어디를 가리키는지 확인하세요. 그 대상이 모듈인지, 빌드 산출물인지, 서명 또는 실행 경로인지 분류하면 조사 범위를 줄일 수 있습니다. 이후 메시지는 앞선 실패의 결과일 수 있으므로, 모든 문구를 각각 독립적인 원인으로 취급하지 마세요.
JIT 오류와 권한 문제를 확인할 때
로그에 경로가 표시됐다면 그 경로의 소유 사용자와 현재 Xcode 세션의 사용자를 비교하세요. 공식 릴리스 노트가 언급한 특정 사용자 소유권 문제는 적용되는 Xcode 버전과 오류 상황을 함께 확인해야 합니다. 근거 없이 전체 권한을 바꾸거나 다른 사용자의 파일을 일괄 수정하는 것은 피하세요.
Preview와 Simulator를 구분할 때
Canvas Preview는 편집 중인 화면의 미리보기 경로이고 Simulator는 해당 런타임에서 앱을 실행하는 경로입니다. Preview가 시작되지 않아도 Simulator가 정상일 수 있으며, 그 반대도 가능합니다. Simulator와 실제 기기는 실행 검증의 대상이 다르므로 각각의 결과를 기록하고, 실제 배포 검증이 필요하면 앱 배포 안내에 따라 별도 빌드 절차도 확인하세요.
SECTION 06수정 뒤에는 검증 결과를 나눠 기록하기
- 같은 파일과 같은 대상으로 Canvas를 다시 열어 Preview가 갱신되는지 확인합니다.
- 같은 Scheme에서 일반 Build를 실행하고 결과를 따로 기록합니다.
- 설치된 런타임에서 Simulator로 앱을 실행해 미리보기와 다른 실행 경로를 확인합니다.
- 배포가 목적이라면 Archive를 별도 검증합니다. Preview가 정상이라는 사실만으로 Archive 성공을 보장할 수 없습니다.
- 화면 동작이 기기별 차이에 좌우되면 실제 기기에서도 확인합니다. Simulator나 Canvas 결과를 실제 기기 검증으로 대신하지 마세요.
현재 작업을 로컬 맥에서 처리하면 계정과 파일 접근을 직접 통제하기 쉽지만, Xcode 전용 장비를 따로 마련하면 초기 하드웨어 비용과 유지 관리가 필요하고, 여러 사람이 함께 쓰는 환경을 구성할 때 접근 권한과 세션 관리도 직접 맡아야 합니다. 반대로 원격 맥은 필요한 기간에 전체 macOS 개발 환경을 이용할 수 있지만, 사용자 분리와 프로젝트 접근 권한, 런타임 구성이 프로젝트에 맞는지 먼저 확인해야 합니다. 이런 환경 조건이 장애 원인으로 의심되면 원격 맥 개발 환경을 살펴보고, 비용과 이용 기간은 요금 안내에서 확인한 뒤 판단하세요. 지속적으로 같은 장비를 사용하거나 물리 기기 연결이 필수라면 로컬 맥이 더 적합할 수 있고, 임시 개발이나 원격 검증 환경이 필요하다면 MACNOX 대여도 비교 대상이 될 수 있습니다.