修复iOS 17中导致SwiftUI导航崩溃的UINavigationController扩展

问题背景 #

在iOS 15、16中，通过全局扩展UINavigationController实现自定义返回按钮时保留侧滑返回手势，运行正常；但升级到iOS 17后，当使用.toolbar(.hidden)或.navigationBarBackButtonHidden()隐藏导航栏/系统返回按钮，同时通过dismiss()实现视图返回时，从子视图侧滑返回根视图会导致根视图冻结崩溃，设备和模拟器均会复现该问题。

原使用代码如下：

extension UINavigationController: UIGestureRecognizerDelegate {
    override open func viewDidLoad() {
        super.viewDidLoad()
        interactivePopGestureRecognizer?.delegate = self
    }

    public func gestureRecognizerShouldBegin(_ gestureRecognizer: UIGestureRecognizer) -> Bool {
        return viewControllers.count > 1
    }
}

struct CustomBackButton: View {
    @Environment(\.dismiss) var dismiss
    var body: some View {
        Button(action: {
            dismiss()
        }) {
            // 自定义返回按钮UI
        }
    }
}

解决方案 #

方案1：移除全局扩展，改用局部手势代理设置 #

全局扩展会覆盖系统所有导航控制器的手势代理逻辑，iOS 17的导航栈内部实现变更后，这种全局修改会引发状态冲突。可以通过UIViewControllerRepresentable为需要的导航视图单独设置手势代理：

struct NavigationGestureFix: UIViewControllerRepresentable {
    func makeUIViewController(context: Context) -> some UIViewController {
        UIViewController()
    }
    
    func updateUIViewController(_ uiViewController: UIViewControllerType, context: Context) {
        guard let navController = uiViewController.navigationController else { return }
        navController.interactivePopGestureRecognizer?.delegate = context.coordinator
    }
    
    func makeCoordinator() -> Coordinator {
        Coordinator()
    }
    
    class Coordinator: NSObject, UIGestureRecognizerDelegate {
        func gestureRecognizerShouldBegin(_ gestureRecognizer: UIGestureRecognizer) -> Bool {
            guard let navController = gestureRecognizer.view?.navigationController else { return false }
            return navController.viewControllers.count > 1
        }
    }
}

使用方式：在需要保留侧滑手势的子视图中添加修饰符：

ChildView()
    .background(NavigationGestureFix())

方案2：自定义系统导航栏返回按钮样式，避免完全隐藏导航栏 #

如果可以接受保留系统导航栏的布局框架，仅自定义返回按钮外观，可通过以下方式实现，同时避免崩溃问题：

1. 保留系统导航栏，替换默认返回按钮为自定义样式
2. 可选设置导航栏背景透明，模拟隐藏效果，并调整内容边距避免遮挡

示例代码：

struct ParentView: View {
    var body: some View {
        NavigationStack {
            ChildView()
                .navigationTitle("")
                .navigationBarTitleDisplayMode(.inline)
                // 替换系统返回按钮为自定义按钮
                .toolbar {
                    ToolbarItem(placement: .navigationBarLeading) {
                        CustomBackButton()
                    }
                }
                // 可选：隐藏导航栏背景，模拟完全隐藏的视觉效果
                .toolbarBackground(.hidden, for: .navigationBar)
                // 可选：调整内容顶部边距，避免被导航栏区域遮挡
                .padding(.top, -UINavigationController().navigationBar.frame.height)
        }
    }
}

// 自定义返回按钮可复用原有实现
struct CustomBackButton: View {
    @Environment(\.dismiss) var dismiss
    var body: some View {
        Button(action: dismiss) {
            // 自定义返回按钮UI，例如：
            Image(systemName: "arrow.left")
                .foregroundColor(.black)
        }
    }
}

方案3：多版本兼容适配 #

如果需要同时兼容iOS 17及以下版本，可通过版本判断区分处理逻辑：

// iOS 16及以下保留原全局扩展逻辑
@available(iOS, obsoleted: 17.0)
extension UINavigationController: UIGestureRecognizerDelegate {
    override open func viewDidLoad() {
        super.viewDidLoad()
        interactivePopGestureRecognizer?.delegate = self
    }

    public func gestureRecognizerShouldBegin(_ gestureRecognizer: UIGestureRecognizer) -> Bool {
        return viewControllers.count > 1
    }
}

// iOS 17及以上使用方案1的NavigationGestureFix进行局部处理

问题原因 #

iOS 17中，SwiftUI的导航栈（包括旧版NavigationView和新版NavigationStack）内部对导航控制器的手势状态管理逻辑有更新，全局设置UINavigationController的手势代理会干扰系统内部的状态同步，导致侧滑返回根视图时出现内存或状态异常，最终引发冻结崩溃。

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