Xcode 27 SwiftUI Preview 不顯示怎麼辦？2026 新手排錯路線

先分辨三種症狀

請先不要把所有問題都叫作「Preview 壞了」。我們值班時會分成三類：

• 沒有入口：看不到預覽區，或目前檔案根本沒有可用的預覽定義。
• 有入口但空白：Canvas 出現了，卻沒有介面，可能是編譯錯誤、資料初始化失敗或執行時崩潰。
• 有錯誤訊息：Preview 顯示錯誤，但正式 Target 未必同時失敗。
• 畫面卡住：Xcode 仍在編譯，或遠端畫面沒有即時更新，不一定是 SwiftUI 語法錯誤。

對新手來說，Canvas 可以理解成「旁邊的即時草稿紙」，不是完整 App。Apple 說明預覽宏會告訴 Xcode 要在 Canvas 顯示哪個介面；因此，只有打開一個普通的 UIKit、AppKit 或資料模型檔案時，Canvas 不會自動知道要預覽什麼。

檔案與預覽宏清單

請逐項勾選：

• [ ] 目前檔案確實包含 import SwiftUI。
• [ ] 根畫面是 View，而不是只有資料模型或控制器。
• [ ] 檔案內有有效的 #Preview，或專案仍使用相容的預覽定義。
• [ ] 開啟的是目前正在修改的檔案，而不是同名的舊檔案。
• [ ] 預覽所屬 Target 與程式碼平台一致。
• [ ] 沒有把只給其他平台的元件直接放進目前的預覽。

Apple 的 Adding previews to your interface files 說明了如何把預覽加入介面檔案。若勾選後仍沒有入口，先切換到另一個最小 SwiftUI 檔案測試。這一步的停止條件是：最小檔案能顯示，或編輯器明確指出缺少哪個預覽定義。不要在沒有錯誤線索時反覆清除整個專案。

紅色錯誤先於空白畫面

在 Xcode 中先看編輯器的紅色錯誤與 Issue navigator。常見分流如下：

有紅色編譯錯誤

• 觀察位置：錯誤所在行、Issue navigator、目前 Target。
• 低風險動作：先修正第一個錯誤，不要同時修改十個檔案。
• 預期結果：錯誤數量下降，Preview 重新嘗試建立。
• 停止條件：仍有與預覽無關的錯誤時，先完成 Target 編譯，再回頭處理 Canvas。

沒有紅色錯誤，但 Preview 空白

• 觀察位置：預覽使用的資料、初始化參數與外部套件。
• 低風險動作：改用靜態文字、固定顏色和空陣列。
• 預期結果：最小畫面出現，代表原頁面的資料或依賴需要分開檢查。
• 停止條件：最小畫面也失敗，才轉查 Canvas 或執行環境。

Preview 報錯，正式 App 可能仍可建置

Preview 只建立目前頁面所需的預覽內容。它可能因為預覽資料為空、初始化需要登入、讀取檔案失敗或頁面在執行時崩潰而失效。這和整個專案無法編譯不是同一件事。完成 Preview 後，仍要按一次 Build，再用模擬器或實體裝置驗證；Apple 的 Previews in Xcode 文件 也把預覽定位為介面設計與互動工具，不能取代完整驗收。

最小 View 隔離法

先暫時使用不依賴網路、外部套件、登入狀態或真實裝置能力的頁面：

import SwiftUI

struct PracticeView: View {
    var body: some View {
        VStack {
            Text("SwiftUI 練習")
            Circle()
                .fill(.blue)
                .frame(width: 80, height: 80)
        }
        .padding()
    }
}

#Preview {
    PracticeView()
}

這個頁面不是完整 App，只是診斷工具。若它能顯示，代表 Xcode、Canvas 與基本 Target 大致可用；接著一次放回一項資料或元件。若它也不能顯示，請回到檔案、Target、Canvas 開關和 Xcode 執行環境，不要直接判定原始專案的 SwiftUI 程式碼有錯。

先處理畫布，再處理模擬器

Apple 的 Interacting with previews in the Canvas 說明 Canvas 可切換預覽裝置、外觀與互動狀態。排查順序建議如下：

1. 確認 Canvas 沒有被關閉，且目前檔案是可預覽的 SwiftUI 檔案。
2. 選一個專案確實支援的預覽裝置與系統外觀。
3. 等待目前編譯工作完成，不要在同一時間連續修改多個檔案。
4. 以最小 View 重新載入預覽。
5. 再檢查模擬器執行時是否可用，以及專案是否要求真實裝置能力。

模擬器與 Preview 不是同一層。Preview 是快速查看某個 View 的草稿；模擬器則是執行較完整的 App。Preview 顯示成功，不代表所有導覽、權限、相機、推播或真實裝置功能都已通過。

條件式環境決策

• 若最小 View 有紅色編譯錯誤，選 A：先修正程式碼與 Target；不要重裝 Xcode。
• 若最小 View 可編譯但 Canvas 被關閉，選 A：恢復 Canvas、重新選擇預覽裝置，再觀察一次。
• 若 Canvas 有畫面，但原頁面失敗，選 A：移除網路、套件與動態資料，逐項加回。
• 若本機沒有相容的 Mac，且課程需要 Xcode 預覽，回退到 B：借用合適的 Apple silicon Mac，或短期使用遠端 Mac。
• 若只是想學 Swift 語法與閱讀專案，可暫時留在 Windows；但不要把它當成 Xcode Canvas 的替代環境。
• 若課程作業接近截止日，而 Xcode 27 仍是 Beta 狀態，先保留能交作業的既有環境，將新環境用於獨立驗收。Beta 的版本與支援條件要重新查看 Apple 的 Xcode Release Notes 索引。

沒有本地 Mac 時，遠端 Mac 可以解決「無法取得 Xcode 與 macOS」的問題，但不會自動修正 SwiftUI 程式碼。先把問題拆成三層：

1. 主機層：終端機是否能連線？可執行 swift --version 或 xcodebuild -version 嗎？
2. Xcode 層：Xcode 是否已開啟？專案是否正在編譯？目前 Target 與平台是否正確？
3. 畫面層：Canvas 是否只是更新較慢？滑鼠操作是否有回應？遠端畫面是否停止刷新？

如果終端機仍能執行，但 Canvas 看起來沒有變化，先等待編譯完成，再重新載入預覽。若終端機也沒有回應，先處理連線或遠端主機狀態。不要一看到卡住就反覆修改程式碼，否則會把網路延遲變成新的編譯錯誤。

需要短期進入 Xcode 的學生，可先查看 MESHLAUNCH 的遠端 Mac 方案，再依課程要求確認 macOS、Xcode、連線方式與可用時間。這只是環境選項，不代表每一個 Preview 問題都應交給遠端主機處理。

完成以下流程，才算排錯有結果：

• [ ] 建立或開啟一個只含 Text、形狀與固定顏色的 SwiftUI View。
• [ ] 確認檔案有有效的 #Preview。
• [ ] 確認檔案所屬 Target、平台與預覽裝置一致。
• [ ] 等待編譯完成，記錄是否有紅色錯誤。
• [ ] 在 Canvas 看見文字與圖形。
• [ ] 修改一次文字或顏色，確認預覽會更新。
• [ ] 按一次 Build，確認正式 Target 也能建置。
• [ ] 再視課程需要使用模擬器或實體裝置驗收。
• [ ] 若使用遠端 Mac，另外記錄終端機、Xcode 與畫面是否都能回應。

最後兩步很重要。Preview 能顯示，只代表「這個介面草稿可建立」；完成 Build 才能確認專案的基本編譯鏈沒有被忽略。

Xcode 27 的 SwiftUI Preview 為什麼會空白？

先檢查檔案是否有有效的 #Preview、目前 Target 是否支援該平台，以及編輯器是否有紅色編譯錯誤。若最小 View 可顯示，問題通常在原頁面的資料、外部套件或執行時初始化。若 Xcode 27 仍處於 Beta，還要按官方 Release Notes 重新核對當前版本狀態。

SwiftUI Canvas 不顯示要先檢查什麼？

先確認 Canvas 沒有被關閉，再確認目前開啟的是 SwiftUI 介面檔案，而不是 UIKit、AppKit 或資料模型檔案。接著查看是否有預覽宏，並用固定文字與顏色建立最小 View。這樣可以先排除畫布設定，再判斷程式碼是否真的有問題。

沒有本地 Mac 怎麼排查 SwiftUI 預覽？

Windows 可以用來學 Swift 語法、閱讀專案和整理檔案，但不能直接取代 Xcode 的 macOS Canvas。若課程需要實際預覽，先借用相容的 Apple silicon Mac，或短期連到遠端 Mac。連線後先測試終端機與 Xcode，再測試最小 SwiftUI 頁面。

Preview 報錯和專案編譯失敗有什麼差別？

Preview 報錯可能只影響目前頁面的預覽資料、初始化或執行時狀態；專案編譯失敗則通常會在 Issue navigator 顯示 Target 層級的錯誤。兩者可能同時發生，但處理順序仍是先修正第一個編譯錯誤，再用最小 View 分離預覽問題。

遠端 Mac 執行 Xcode Preview 卡住怎麼辦？

先看 Xcode 是否仍在編譯，並從終端機確認遠端主機仍可回應。如果終端機正常，可能是畫面刷新或預覽建立時間較長；如果終端機也停止回應，先處理遠端連線。把專案縮成不含網路與外部套件的最小頁面，可避免把連線問題誤判成 SwiftUI 錯誤。

先用最小頁面完成一次「預覽出現、文字更新、Build 成功」的驗收，再決定是否需要長期使用 Mac。若本地 Windows 或學校電腦只是不能安裝 Xcode，短期遠端 Mac 能補上 macOS 與 Xcode 這一段；但它仍受網路畫面延遲、連線中斷和啟動等待影響，不適合在沒有備份環境時壓線完成重要作業。

如果您需要的是臨時課程環境，可先閱讀 MESHLAUNCH 的遠端 Mac 連線入口，並把本文的最小頁面清單當作驗收標準。若已確定要使用遠端主機，也可以參考 Apple silicon Mac 的遠端方案說明；先核對課程交付物，再決定租用時間，通常比在截止日前盲目重裝 Xcode 更穩妥。