Mac Catalyst下使用NETunnelProviderManager建立VPN连接异常问题

问题现象 #

• 基于Mac Catalyst开发VPN应用，采用NETunnelProviderManager实现VPN核心逻辑
• 同一份代码在iOS端、原生macOS项目中运行正常，可正常建立VPN连接
• Mac Catalyst环境运行时，VPN状态先切换为Connecting...，随后无提示直接变为Disconnected...，连接建立失败

核心业务实现代码如下：

public func establishConnection(extensionBundleID: String) {
        tunnelBundleId = extensionBundleID
        initVPNTunnelProviderManager()
    }
    private func initVPNTunnelProviderManager(completionHandler: VoidHandler? = nil) {
        NETunnelProviderManager.loadAllFromPreferences { (savedManagers: [NETunnelProviderManager]?, error: Error?) in
            if let error = error {
                print(error)
            }
            if let savedManagers = savedManagers {
                if savedManagers.count > 0 {
                    self.vpnManager = savedManagers[0]
                }
            }
            self.vpnManager.loadFromPreferences(completionHandler: { (error:Error?) in
                if let error = error {
                    print(error)
                }
                let providerProtocol = NETunnelProviderProtocol()
                providerProtocol.providerBundleIdentifier = self.tunnelBundleId

                providerProtocol.providerConfiguration = [
                                                          "server": self.serverAddress,
                                                          "dns": self.dns
                ]
                providerProtocol.serverAddress = self.serverAddress
                self.vpnManager.protocolConfiguration = providerProtocol
                self.vpnManager.localizedDescription = "Family Protection"
                self.vpnManager.isEnabled = true
                self.vpnManager.saveToPreferences(completionHandler: { (error:Error?) in
                    if let error = error {
                        print(error)
                    } else {
                        print("Save successfully")
                        completionHandler?()
                    }
                })
                self.VPNStatusDidChange(nil)

            })
        }
        NotificationCenter.default.addObserver(self, selector: #selector(VPNStatusDidChange(_:)), name: NSNotification.Name.NEVPNStatusDidChange, object: nil)
    }
public func enableProtection() {
        self.vpnManager.loadFromPreferences { [weak self] error in
            if let error = error {
                print(error)
            }
            do {
                try self?.vpnManager.connection.startVPNTunnel()
            } catch {
                self?.initVPNTunnelProviderManager(completionHandler: {
                    self?.enableProtection()
                })
                print(error)
            }
        }
    }

修复方案 #

1. 修正跨平台能力与签名配置（90%同类问题根因） #

Mac Catalyst的权限体系和iOS、原生macOS不完全通用，需要单独配置：

• 为主App Target、Network Extension Target单独勾选Mac Catalyst平台下的Network Extensions、Personal VPN能力；如果使用App Group做进程间通信，需确保App Group ID在开发者后台已勾选macOS平台权限，且两个Target的Catalyst编译配置中均正确引入该权限
• 确认Network Extension Target已勾选支持Mac Catalyst平台，且Catalyst环境下生成的Extension Bundle ID，和代码中传入providerProtocol.providerBundleIdentifier的值完全一致。Catalyst不会自动匹配iOS侧的Extension Bundle ID，参数不匹配时系统找不到隧道插件，会直接断开连接且不抛出前端异常。
• 检查两个Target的.entitlements文件，确认Catalyst编译模式下所有权限Key均正确生成，不存在仅iOS平台生效的权限配置。

2. 修复配置操作时序问题 #

Catalyst对NetworkExtension配置的持久化时序要求比iOS严格，现有代码缺少保存后重载配置的步骤：

• 现有逻辑在saveToPreferences成功回调中直接触发连接，此时内存中vpnManager的配置未和系统持久化层同步，启动隧道时会因参数无效秒断。需要在配置保存成功后，再次调用loadFromPreferences拉取最新的系统配置，再执行后续操作，修改后的保存逻辑如下：

self.vpnManager.saveToPreferences(completionHandler: { (error:Error?) in
    if let error = error {
        print("Save config error: \(error)")
        return
    }
    // Catalyst 环境下必须在保存后重新加载配置，否则配置不生效
    self.vpnManager.loadFromPreferences(completionHandler: { loadError in
        if let loadError = loadError {
            print("Reload config error: \(loadError)")
            return
        }
        print("Config ready")
        completionHandler?()
    })
})

• 现有代码中NEVPNStatusDidChange通知的注册位置有误，每次调用initVPNTunnelProviderManager都会重复注册通知，导致状态回调多次触发，建议将通知注册逻辑移到类初始化阶段，仅执行一次。

3. 清理无效跨平台缓存配置 #

Mac Catalyst和iOS的VPN偏好配置独立存储，若设备上之前运行过iOS版本应用，loadAllFromPreferences拉取到的旧配置为iOS平台生成的无效配置，无法在Catalyst环境下使用：

• 调试阶段可先调用vpnManager.removeFromPreferences(completionHandler:)删除所有已存储的VPN配置，重新创建配置项后再尝试连接
• 正式代码中可增加配置校验逻辑，判断拉取到的配置对应的providerBundleIdentifier是否匹配当前Catalyst环境的Extension ID，不匹配则删除重建。

4. 精准定位错误日志 #

如果以上调整后仍无法连接，打开系统自带的Console应用，选择当前Mac设备，筛选进程关键词neagent，触发VPN连接操作后即可看到系统打印的具体失败原因，常见错误包括签名无效、Extension未找到、权限缺失，根据日志对应修复即可。

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