Canvas 一直空白，或刚改完代码就出现 Preview Update Error？ 先看 Preview Diagnostics 中最早的有效错误，再用最小视图、普通 Build 和正确的目标运行时交叉验证；先修复明确指向的代码、依赖或环境问题，不要一上来清空全部缓存或重装 Xcode。
这篇文章适合在远程 Mac 上编辑 SwiftUI、但 Xcode Canvas 空白或更新失败的独立开发者。
如果普通 Build 能通过而 Preview 起不来，你可以据此区分构建成功与预览执行成功。
多人共用远程 Mac、怀疑用户会话或预览目录权限不一致的小团队，也可以按后面的分支核对。
SECTION 01先区分画布状态、更新失败与启动崩溃
“Preview 不显示”不是单一故障。先看见到的症状，再决定检查哪一层：
- Canvas 没显示或处于暂停状态：确认当前打开的是包含预览宏的 SwiftUI 文件，并检查 Canvas 是否已显示、预览是否暂停。Apple 的 Canvas 交互说明提到，暂停的画布可以通过 Restart 重新运行；这与构建错误不是一回事。
- 出现 Preview Update Error：记录完整的 Preview Diagnostics，优先找第一条能对应到具体 Target、文件、依赖或路径的失败信息。不要只抄最后一行总括错误。
- 预览开始后超时或崩溃：看日志是否已进入启动阶段，再检查初始化代码、预览数据、运行时和进程错误。若只是 Canvas 没打开，重试预览构建并不能解决问题。
- 普通 Build 成功、Preview 仍失败：这只能说明普通构建动作通过，不能证明预览专属的发现、启动与更新过程也正常。
排查时，把日志中的项目名、用户名、文件路径和设备名称脱敏后再分享。远程机器上的完整路径和账户名可能泄露不必要的环境信息。
SECTION 02用最小视图判断是不是当前界面代码
先在项目现有 SwiftUI 文件中建立最小对照，避免把复杂页面、数据层和依赖同时带入实验：
import SwiftUI
struct PreviewProbe: View {
var body: some View {
Text("Preview check")
}
}
#Preview {
PreviewProbe()
}
Apple 的 预览宏文档说明，Xcode 可在 Canvas 中显示 SwiftUI、UIKit 和 AppKit 预览，并使用 #Preview 指定要显示的内容。这里的目的不是重写页面，而是确认当前文件能否被 Xcode 发现、预览宏能否生成一个不依赖业务数据的视图。
- 若最小视图也不显示：优先检查 Canvas 状态、所选文件和预览诊断，再核对所选 Scheme 与运行时。
- 若最小视图能显示，原页面不能：重点检查原视图的初始化参数、环境对象、预览数据，以及预览启动时会触发的文件或网络访问。
- 若单文件通过、特定 Target 失败：比对该文件的 Target Membership、条件编译与依赖归属；不要因为另一个 Target 能构建就假定它们使用相同配置。
场景例子：你刚给一个页面加入必须注入的环境对象。应用主流程有完整容器，预览宏却直接创建页面；这时普通 Build 可能通过，预览仍会因缺少初始化数据而失败。把预览改为提供独立、可重复的样例数据，比清缓存更能验证这个假设。
SECTION 03检查 Scheme、平台和预览目标
预览所用的平台、Scheme、设备目标与项目部署目标需要互相匹配。先在 Xcode 工具栏核对当前 Scheme，再确认 Canvas 选择的是项目实际支持的目标；如果诊断表明某个平台组件或运行时不可用，先处理组件与目标不匹配，不要把它直接归因于远程连接。
可以按以下顺序复核：
- 确认所选 Scheme 包含当前视图所属的 App Target。
- 核对 Canvas 中选定的平台和设备，与该 Target 的受支持平台是否一致。
- 在 Xcode 的组件设置中确认对应平台支持和模拟器运行时可用。
- 用相同 Scheme 与目标执行普通 Build，再观察 Preview 是否给出不同诊断。
- 只有诊断明确指向部署目标或 SDK 不兼容时，才评估是否需要调整项目设置；改动前检查它对其他 Target、测试配置与发布构建的影响。
Apple 的运行模拟器或实体设备指南指出，运行目标取决于所选 Scheme；若目标平台支持未安装，也无法据此完成相应的构建和运行。具体部署目标由项目构建设置控制，可查阅 Apple 的 Xcode Build Settings 参考，不要为了让画布出现而盲目降低最低系统版本。
⚠️ Canvas Preview、Simulator 和实体设备各自回答不同问题。Apple 明确提醒，模拟器不会复现实体设备的全部性能或功能；所以 Simulator 能启动，不等于设备行为已验收。
SECTION 04从依赖、JIT 与目录权限追到首个失败点
当诊断提到缺失模块、无法载入构建产物、代码签名或 JIT 时，按错误指向核对依赖产品、所属 Target、构建路径和当前账户。依赖报错时先确认该预览目标确实能访问依赖；路径访问被拒绝时再检查目录拥有者与当前 Xcode 用户。错误只写“启动失败”时，不要仅凭关键词推断是缓存损坏。
Apple 在 Xcode 27.2 Beta Release Notes中记录了一个范围明确的修复：当另一用户账户拥有 Previews JIT 目录，导致预览失败时，错误提示会给出更清晰的恢复信息。该说明限定于这个具体账户所有权情形；它不能证明 JIT、权限或缓存是所有 Preview 故障的根因。该版本说明还注明，Xcode 27.2 Beta 要求运行在 macOS Tahoe 26.6 或更新版本；这项要求只对应所述 Beta 版本，核对你实际使用的 Xcode 版本及其官方说明。
在多人共用的远程 Mac 上，重点确认四件事：项目文件对当前账户是否可访问；启动 Xcode 的用户是谁；预览构建目录是否由另一个账户创建；远程图形会话和你操作的账户是否一致。Apple Developer Forums 有关于预览 JIT 目录权限错误的个别讨论案例，可用来识别类似日志，但论坛案例不能替代你机器上的诊断证据。切勿未经确认就递归修改共享目录或系统目录的权限。
SECTION 05按故障分支选择下一步
- 若 Canvas 未显示或暂停，且没有构建错误：先打开画布或恢复预览；若仍无预览，再检查当前文件是否含可发现的预览宏。
- 若最小视图失败，普通 Build 也失败：先处理普通编译错误、Scheme 或平台目标，修复后重新观察 Preview。
- 若最小视图失败，但普通 Build 成功：根据诊断核对运行时、预览启动和用户目录；用同一运行目标交叉验证，不要先全量清缓存。
- 若最小视图通过、业务视图失败：检查该视图的依赖注入、初始化参数、样例数据及预览期间触发的代码。
- 若错误明确指向其他账户拥有的 Previews JIT 目录：确认实际账户和该目录所有权，再按当前 Xcode 版本的官方错误提示处理；若证据不符，回到日志中的首个失败组件。
以上分支不是“所有机器都适用同一修复”的清单，而是限制每次操作的影响范围。删除 DerivedData 或重装 Xcode 会影响其他构建产物和工作流；只有诊断与对照测试把故障范围缩小到相应缓存或工具链后，才把它们作为后续手段。
SECTION 06Preview 故障排查 FAQ
Xcode Canvas 里的 Preview Update Error 怎么定位？
先保留诊断记录，再从最早出现的具体失败项向下追踪，而不是从最后的汇总报错猜原因。对照项目 Target、依赖产品与构建路径；若错误属于访问拒绝，再确认当前 Xcode 账户与路径拥有者。错误记录中若包含用户名或文件位置，发到团队频道前先脱敏。
远程 Mac 的 Preview 失败，如何与 Simulator 故障区分？
使用相同 Scheme 和目标分别观察 Canvas Preview 与 Simulator 启动结果。若 Simulator 可运行、Preview 不行，故障更可能在预览代码、预览执行链路或账户目录环境；若两者都失败，再检查平台组件、运行时与项目构建配置。Simulator 通过也不能替代实体设备验证；Apple 的设备运行说明说明了模拟器与实体设备测试的边界。
Preview Diagnostics 没有清楚指向某个文件，下一步做什么？
不要一次改多个设置。先建立不依赖业务数据的最小视图，并保留原 Scheme 与运行目标做对照；再逐项加入目标视图的初始化参数、依赖与环境配置。对照结果能缩小故障范围后，才去检查相应构建目录或账户权限，避免一次清理同时抹掉排查线索。
为什么 Preview 正常，仍要单独做发布验收？
Preview 主要用于界面迭代，不能证明 Release Archive、签名或上传流程已通过。修复后至少分别记录 Preview 更新、同目标普通 Build、Simulator 运行和 Release Archive 的结果；如果还涉及设备专属能力，再安排实体设备测试。Apple 的发布流程说明将创建 Archive 和后续分发列为独立步骤。
SECTION 07修复后的验收记录
别用“画布终于显示了”作为全部验收结论。按层记录可复查的结果：
- Preview：重新打开目标文件，确认画布已恢复，并确认修改视图后能够再次更新。
- 普通 Build：记录使用的 Scheme、配置和目标，确保检查的是实际项目构建，而不是临时探针。
- Simulator：用相同目标尝试运行，记录是运行时不可用、应用启动失败，还是模拟器可正常运行。
- Release Archive：单独执行归档验证；Archive 与 Preview 是不同任务，前者的结果不由后者代替。Apple 的测试版与发布分发文档说明了归档与后续分发流程。
如果故障仍无法复现，保留脱敏后的诊断摘要、Scheme、运行目标、Xcode 版本和修复前后结果。这样下次换用户、更新运行时或迁移项目时，团队能判断问题是回归还是环境差异，而不是重新从删除缓存开始。
如果你当前在本地开发，反复切换账户、依赖本机可用空间或维持一台常驻打包设备，都会带来额外维护；远程 Mac 也不是 Preview 故障的自动修复器，项目代码、依赖和运行时问题仍需按上述流程排查。若问题确认与远程开发环境的账户隔离或运行时配置有关，可先从远程 Mac 开发环境入口了解工作方式；需要完整 Xcode 工作流但不想专门购买 Mac 时，再查看 MACNOX 的租赁方案与周期，并结合项目是否长期持续使用决定租用或本地运行。