iOS QLPreviewController 无法正常展示及崩溃问题求助

我之前踩过QLPreviewController的这个坑，这个错误本质是QL预览依赖的XPC跨进程通信出了问题，再加上UI过渡的调用时机不规范导致的，咱们一步步来解决：

可能的原因 #

• QLPreviewController的UI操作没在主线程执行，跨进程通信对线程要求很严格
• 在视图控制器生命周期的不安全时机（比如viewWillAppear）触发展示，导致过渡动画冲突
• 数据源实现不正确，返回的预览项无效（比如网络URL没下载到本地）
• 复用了已经被dismiss/pop的QLPreviewController实例

解决方案 #

1. 强制在主线程处理QLPreviewController的展示 #

UIKit所有UI操作都必须在主线程，QL涉及跨进程通信更是如此，一定要把push/present代码包在主线程异步调用里：

// 比如在按钮点击事件里
@IBAction func previewFile(_ sender: UIButton) {
    DispatchQueue.main.async {
        let previewVC = QLPreviewController()
        previewVC.dataSource = self
        previewVC.delegate = self
        self.navigationController?.pushViewController(previewVC, animated: true)
    }
}

2. 选择安全的时机触发展示 #

不要在viewWillAppear、viewWillLayoutSubviews这类会频繁触发的生命周期方法里直接展示，最好在用户交互事件（比如按钮点击）或者viewDidAppear中执行。

3. 确保数据源实现完全正确 #

QLPreviewController对数据源的返回值要求很严格，必须返回有效的本地文件URL（网络URL需要先下载到本地沙盒）：

extension YourViewController: QLPreviewControllerDataSource {
    func numberOfPreviewItems(in controller: QLPreviewController) -> Int {
        // 返回实际的预览项数量，这里以单个文件为例
        return 1
    }
    
    func previewController(_ controller: QLPreviewController, previewItemAt index: Int) -> QLPreviewItem {
        // 确保这个URL是本地沙盒里的有效文件路径，比如Documents目录下的文件
        guard let localFileURL = Bundle.main.url(forResource: "sample", withExtension: "pdf") else {
            fatalError("本地预览文件不存在")
        }
        return localFileURL as QLPreviewItem
    }
}

4. 不要复用QLPreviewController实例 #

每次需要展示预览时，都创建新的QLPreviewController实例，不要复用已经被弹出或返回的旧实例——旧实例的XPC连接可能已经失效，复用会导致通信错误。

5. 通过代理监听异常，避免崩溃 #

实现QLPreviewControllerDelegate的方法，及时处理预览结束的情况，确保资源正确释放：

extension YourViewController: QLPreviewControllerDelegate {
    func previewControllerDidDismiss(_ controller: QLPreviewController) {
        // 可以在这里做一些清理工作，比如释放相关资源
        controller.dataSource = nil
        controller.delegate = nil
    }
}

额外注意点 #

如果是用present方式展示QLPreviewController，同样要遵守以上规则，并且确保当前视图控制器没有正在执行其他动画（比如模态弹出、转场动画）。

内容的提问来源于stack exchange，提问作者user979331