// Dev Log

SwiftUI Preview 빌드 오류 해결: Xcode 미리보기 점검 순서

2026년 9월

SwiftUI Preview 빌드 오류 해결은 캐시 삭제부터 시작하는 작업이 아닙니다. 가장 빠른 방법은 문제를 코드·타깃 설정, 의존성·SDK, Xcode 캐시·런타임의 세 범주로 나눈 뒤 오류가 발생한 지점을 좁히는 것입니다. 같은 “Preview가 안 된다”는 증상이라도 현재 파일의 컴파일 오류, 누락된 모듈, 잘못된 샘플 데이터처럼 원인은 전혀 다를 수 있습니다.

먼저 일반 앱 빌드가 성공하는지 확인하고, 그다음 Preview 선언과 파일 의존성을 점검하세요. 마지막 단계에서만 빌드 폴더, Derived Data, 시뮬레이터 런타임을 확인하면 불필요한 초기화와 재설치를 피할 수 있습니다.

SwiftUI Preview 오류를 세 가지 상황으로 구분하기

캔버스 자체가 표시되지 않는 경우

소스 편집기 옆에 캔버스가 없다면 빌드 문제라고 단정하기 전에 현재 파일에 Preview 선언이 있는지 확인합니다. 툴바의 Show Canvas를 선택하고, 캔버스가 일시 정지된 상태라면 다시 시작합니다. Apple 문서도 Preview 매크로가 포함된 인터페이스 파일을 열고 Show Canvas로 캔버스를 표시하는 흐름을 안내합니다. 기본 사용법은 Apple의 Xcode Preview 문서에서 확인할 수 있습니다.

캔버스는 열리지만 빌드에 실패하는 경우

“Failed to build scheme”과 비슷한 문구는 하나의 원인을 뜻하지 않습니다. Preview가 선택한 스킴과 실행 대상에 맞춰 코드를 빌드하는 과정에서 실패했다는 상위 수준의 결과일 수 있습니다. Issue navigator 또는 Preview 진단 영역에서 가장 먼저 발생한 컴파일 오류를 찾으세요. 뒤에 이어지는 수십 개의 오류보다 최초 오류 한 개가 원인에 가까운 경우가 많습니다.

특정 Swift 파일에서만 실패하는 경우

다른 화면은 정상인데 한 파일만 실패한다면 Xcode 전체보다 그 View의 입력값과 의존성을 먼저 살펴봅니다. 필수 초기화 인자를 빠뜨렸거나, Preview에서 제공하지 않은 환경 객체를 읽거나, 해당 파일이 현재 앱 타깃에 포함되지 않았을 가능성이 있습니다. 이때 Xcode 재설치는 문제 범위에 비해 지나치게 큰 조치입니다.

가장 먼저 실행할 진단 순서

일반 앱 빌드를 실행합니다. 앱 빌드도 실패하면 Preview가 아니라 공통 컴파일 오류부터 해결합니다.
최초 오류를 확인합니다. 문법 오류, 타입 불일치, 모듈 누락처럼 구체적인 메시지를 우선합니다.
Preview 선언을 최소화합니다. 복잡한 데이터와 modifier를 제거하고 View 하나만 반환해 봅니다.
파일과 리소스의 Target Membership을 확인합니다. View뿐 아니라 참조하는 모델과 에셋도 같은 타깃에서 접근 가능해야 합니다.
선택한 스킴과 실행 대상을 확인합니다. iOS View를 macOS 실행 대상으로 빌드하는 등 플랫폼이 엇갈리지 않아야 합니다.
패키지와 SDK 상태를 확인합니다. 모듈을 찾지 못한다면 패키지 해석과 지원 플랫폼을 살핍니다.
마지막으로 Preview와 캐시를 재시작합니다. 원인을 좁히지 않은 채 모든 데이터를 먼저 지우지는 마세요.

#Preview 코드와 View 자체 점검하기

Preview 클로저가 View를 반환하는지 확인

기본 형태는 간단합니다. Preview 본문은 캔버스에 표시할 SwiftUI View를 생성해야 합니다.

import SwiftUI

struct ProfileCard: View {
    let name: String

    var body: some View {
        Text(name)
            .padding()
    }
}

#Preview {
    ProfileCard(name: "민지")
}

View에 필수 인자를 추가한 뒤 Preview 호출부를 갱신하지 않았다면 “Missing argument”와 유사한 컴파일 오류가 발생할 수 있습니다. Preview 안에서 네트워크 요청이나 실제 사용자 세션을 바로 생성하기보다, 화면을 재현할 수 있는 작은 샘플 값을 전달하는 편이 진단하기 쉽습니다.

@State, @Binding, @Environment 의존성 처리

@State는 보통 View 내부 기본값으로 시작할 수 있지만, @Binding을 받는 자식 View에는 Preview용 바인딩이 필요합니다. 사용하는 Xcode와 SDK가 지원한다면 Preview 내부에서 상태를 준비하고 전달할 수 있습니다. 지원 방식은 버전에 따라 다르므로 컴파일러가 제시하는 진단을 기준으로 작성하세요.

struct ToggleRow: View {
    @Binding var isEnabled: Bool

    var body: some View {
        Toggle("알림", isOn: $isEnabled)
    }
}

#Preview {
    ToggleRow(isEnabled: .constant(true))
}

@EnvironmentObject, 모델 컨텍스트, 데이터베이스 또는 서비스 객체를 읽는 화면은 Preview에도 동일한 종류의 의존성을 제공해야 합니다. 캔버스가 나타난 뒤 런타임 오류로 종료된다면 누락된 환경 값이 없는지 확인하고, 메모리 기반 저장소나 가짜 서비스를 주입해 외부 상태와 분리합니다.

#Preview와 PreviewProvider의 차이

최신 도구 체계에서는 간결한 #Preview 매크로가 일반적인 선택입니다. Apple은 매크로의 body가 미리 볼 View와 필요한 입력·모델 데이터를 생성한다고 설명합니다. 반면 기존 코드는 PreviewProvider를 구현해 static var previews에서 View를 반환할 수 있습니다. 관련 관계는 Apple의 SwiftUI Previews 문서에서 확인할 수 있습니다.

#Preview가 무조건 모든 프로젝트에 적합한 것은 아닙니다. 오래된 Xcode, Swift 도구 체계 또는 낮은 배포 대상과 조합할 때 가용성 진단이 나타날 수 있습니다. 오류 문구가 Preview 매크로의 가용성을 가리킨다면 제품 요구사항을 무시하고 Deployment Target부터 올리지 말고, 현재 도구 체계가 지원하는지 확인한 뒤 필요하면 PreviewProvider를 사용합니다.

타깃 멤버십과 플랫폼 설정 확인

파일이 올바른 타깃에 포함되어 있는가

Project navigator에서 문제가 있는 Swift 파일을 선택하고 File inspector의 Target Membership을 확인합니다. View 파일만 체크한다고 끝나지 않습니다. View가 참조하는 모델, extension, 생성 코드, 이미지나 JSON도 해당 타깃에서 사용 가능해야 합니다. 여러 앱 타깃이나 위젯 확장을 함께 운영한다면 같은 이름의 타입이 어느 모듈에 속하는지도 확인하세요.

플랫폼 조건이 Preview와 일치하는가

#if os(iOS) 내부에 정의된 타입을 macOS Preview에서 사용하거나 UIKit 전용 API를 다중 플랫폼 View가 무조건 호출하면 실패할 수 있습니다. 현재 스킴, 실행 대상, View가 지원하는 플랫폼을 나란히 비교하세요. 조건부 컴파일을 사용했다면 Preview 선언도 같은 조건에서 유효한지 점검해야 합니다.

Deployment Target과 SDK 조합 확인

최근 SDK에서 추가된 API를 더 낮은 운영체제 배포 대상으로 빌드할 때는 가용성 처리가 필요합니다. 반대로 프로젝트가 요구하는 시뮬레이터 런타임이 설치되지 않았거나 선택한 Xcode에서 지원되지 않으면 Preview 실행 환경을 만들지 못할 수 있습니다. 이 문제는 버전에 따라 동작과 메시지가 달라지므로, 추측보다 Xcode에 표시된 API 가용성 및 런타임 진단을 기준으로 판단합니다.

“No such module”과 패키지 오류 해결

“No such module”과 유사한 오류가 보이면 캐시보다 모듈 연결 상태를 먼저 확인합니다. 일반적으로 다음 항목을 순서대로 살펴볼 수 있습니다.

패키지 제품이 현재 앱 타깃의 의존성에 추가되어 있는지 확인합니다.
import 이름이 패키지 저장소 이름이 아니라 실제 모듈 이름과 일치하는지 확인합니다.
패키지가 Preview에서 선택한 플랫폼과 배포 대상을 지원하는지 확인합니다.
패키지 해석 또는 다운로드 과정에 별도의 오류가 없는지 확인합니다.
로컬 패키지라면 경로 변경, 삭제된 파일, Target Membership과 비슷한 소스 포함 설정을 점검합니다.

앱 실행 시에만 필요한 분석 SDK, 푸시 서비스, 보안 저장소가 View 초기화 단계에서 즉시 생성되면 Preview도 그 구현을 요구할 수 있습니다. 프로토콜을 통해 서비스를 주입하고 Preview에는 가짜 구현을 제공하면 빌드 문제와 외부 서비스 문제를 분리할 수 있습니다. 다만 실제 앱과 다른 동작을 숨기지 않도록 가짜 데이터의 범위는 화면 표현에 필요한 수준으로 제한합니다.

오류 메시지별 빠른 진단표

표시되는 증상 또는 예시 문구	먼저 확인할 항목	다음 조치
Cannot preview in this file	Preview 선언, 지원 플랫폼, 파일의 컴파일 상태	최소 View를 추가하고 스킴과 타깃을 비교
Failed to build scheme	Issue navigator의 최초 컴파일 오류	일반 앱 빌드에서도 재현되는지 확인
No such module	패키지 제품 연결과 모듈 이름	플랫폼 지원 및 패키지 해석 오류 확인
Missing argument	View 초기화 인자 변경	Preview용 샘플 값을 명시적으로 전달
환경 객체 관련 런타임 실패	Environment 주입 여부	메모리 기반 모델 또는 가짜 서비스 제공
Preview가 계속 준비 중	최초 진단, 무한 작업, 런타임 상태	Preview를 최소화한 뒤 캔버스 재시작

표의 문구는 Xcode 버전과 실패 단계에 따라 다르게 표시될 수 있는 예시입니다. 제목만 검색하기보다 오류 상세 정보에서 실패한 파일, 타깃, 모듈 이름을 함께 읽어야 정확한 원인을 찾을 수 있습니다.

Xcode 캐시와 Preview 실행 환경 초기화

코드와 설정이 올바르고 같은 소스가 이전에는 정상 동작했다면 실행 환경을 점검합니다. 먼저 캔버스의 재시작 기능을 사용하고 Xcode를 종료했다가 프로젝트를 다시 엽니다. 이어서 Product 메뉴의 Clean Build Folder를 사용할 수 있습니다. 메뉴 구성은 Xcode 버전에 따라 달라질 수 있으므로 현재 설치본에서 이름을 확인하세요.

Derived Data는 다음 단계입니다. Xcode Settings의 Locations에서 현재 경로를 확인하고, 다른 프로젝트까지 한꺼번에 지우기보다 문제가 된 프로젝트의 데이터만 대상으로 삼는 편이 안전합니다. 삭제하면 인덱싱과 패키지 빌드에 시간이 다시 들 수 있으며, 캐시가 원인이 아니라면 문제가 그대로 남습니다.

선택한 Preview 디바이스에 필요한 시뮬레이터 런타임이 설치되어 있는지도 확인하세요. 특정 기기에서만 실패한다면 다른 지원 기기를 선택해 범위를 좁힐 수 있습니다. 다만 다른 기기에서 열린다는 사실만으로 원래 기기의 호환성 문제가 해결된 것은 아니므로 배포 대상과 런타임 조합을 다시 검토해야 합니다.

그래도 실패할 때 문제 범위 줄이기

같은 파일에 Text("Preview Test")만 반환하는 임시 Preview를 추가합니다. 이것이 표시되면 캔버스 기반 기능은 작동하며 원인은 원래 View의 입력이나 의존성에 가깝습니다. 다음으로 View를 감싼 NavigationStack, 환경 객체, 모델 컨텍스트, 비동기 작업을 하나씩 되돌립니다. 어느 요소를 추가했을 때 실패하는지 기록하면 재현 가능한 최소 사례를 만들 수 있습니다.

반대로 최소 View도 실패한다면 새 프로젝트를 만드는 대신 현재 프로젝트의 스킴, 타깃, SDK 및 패키지 단계로 돌아갑니다. Xcode 또는 SDK를 업데이트한 직후라면 소스 변경뿐 아니라 선택된 Command Line Tools, 설치된 런타임, 패키지 버전 변화도 함께 기록하세요. 팀원의 동일 커밋에서 재현되는지 비교하면 로컬 환경 문제와 프로젝트 문제를 구분하는 데 도움이 됩니다.

Preview 빌드 실패를 예방하는 개발 습관

View 초기화 인자가 바뀌면 같은 커밋에서 Preview 샘플도 수정합니다.
네트워크·데이터베이스·인증 객체를 View 내부에서 직접 만들기보다 주입 가능한 경계로 분리합니다.
로딩, 성공, 빈 데이터, 오류 상태별로 작고 이름 있는 Preview를 유지합니다.
다중 플랫폼 코드는 조건부 컴파일 범위와 지원 타깃을 명확히 관리합니다.
패키지 업데이트 후에는 앱 빌드와 대표 Preview를 함께 확인합니다.
오류를 공유할 때 Xcode 버전, SDK, 배포 대상, 선택한 스킴과 최초 오류를 기록합니다.

SwiftUI Preview 빌드 오류 해결 체크리스트

일반 앱 빌드의 성공 여부를 확인했는가?
연쇄 오류가 아닌 최초 컴파일 오류를 읽었는가?
#Preview 또는 PreviewProvider가 유효한 View를 반환하는가?
필수 초기화 인자와 Binding, Environment 의존성을 제공했는가?
관련 파일과 리소스가 올바른 타깃에 포함되어 있는가?
스킴, 플랫폼, Deployment Target, SDK 조합이 맞는가?
패키지 제품과 실제 모듈 이름이 타깃에 올바르게 연결되었는가?
최소 View에서도 같은 문제가 재현되는가?
코드와 설정을 점검한 뒤 Preview 재시작과 선택적 캐시 정리를 시도했는가?

SwiftUI Preview 빌드 오류 해결의 핵심은 큰 초기화 작업이 아니라 실패 범위를 단계적으로 줄이는 데 있습니다. 앱 빌드와 최소 Preview로 코드 문제를 가르고, 타깃과 패키지, SDK를 확인한 뒤 마지막에 캐시와 런타임을 점검하세요. 이 순서를 따르면 “Xcode Preview 안됨”이라는 모호한 증상을 수정 가능한 하나의 원인으로 바꿀 수 있습니다.