NEHotspotHelper连接带captive portal WiFi时presentUI未调用求助

我之前在对接带 captive portal 的WiFi时，也碰到过一模一样的坑，咱们从几个关键环节挨个排查：

1. 先确认Helper注册真的成功了 #

你现在的注册代码只打了日志，但没检查NEHotspotHelper.register的返回值！这个方法会返回一个布尔值，只有返回true才代表注册成功，否则后续所有回调全白搭。另外，注册用的队列必须是串行队列（不能用并发队列），苹果要求必须用专门的串行队列处理Helper的回调，给你补个完整的注册示例：

// 创建专门的串行队列
let helperQueue = DispatchQueue(label: "com.your.app.wifi-helper", qos: .utility)
// 配置Helper的基础参数，加上支持的网络类型
let options: [String: NSObject] = [
    kNEHotspotHelperOptionDisplayName: NSLocalizedString("linq verified", comment: "") as NSObject,
    kNEHotspotHelperOptionSupportedNetworkTypes: NEHotspotHelperSupportedNetworkType.wifi.rawValue as NSObject
]

// 注册并接收所有命令回调
let isRegistered = NEHotspotHelper.register(options: options, queue: helperQueue) { command in
    // 先打印所有收到的命令，方便排查
    print("Received helper command: \(command.type.rawValue)")
    
    switch command.type {
    case .filterScanList:
        self.handleFilterScanList(command)
    case .presentUI:
        // 终于等到你！这里处理Portal UI的展示
        print("Got presentUI command, show custom portal page!")
        self.showCaptivePortalUI(command)
    case .authenticate, .evaluate, .maintain:
        // 这些命令也要处理，不然系统会认为你的Helper不工作
        command.createResponse(NEHotspotHelperResult.success).submit()
    default:
        command.createResponse(NEHotspotHelperResult.success).submit()
    }
}

// 一定要检查注册结果！
print("Hotspot Helper registered status: \(isRegistered)")

如果这里打印的是false，直接跳到第3点检查权限——十有八九是权限没搞定。

2. 正确处理filterScanList命令，标记你的目标WiFi #

系统会先给你发filterScanList命令，让你筛选要处理的WiFi。对于带 captive portal 的WiFi，你必须把它保留在返回列表里，而且开放型的captive WiFi要确保isSecure是false（别误设成true）：

private func handleFilterScanList(_ command: NEHotspotHelperCommand) {
    guard let scanNetworks = command.networkList else {
        command.createResponse(NEHotspotHelperResult.success).submit()
        return
    }
    
    // 筛选出你要处理的目标WiFi，比如指定SSID
    let targetNetworks = scanNetworks.filter { $0.ssid == "YourCaptiveWiFiSSID" }
    
    // 创建响应并提交，把筛选后的列表返回给系统
    let response = command.createResponse(NEHotspotHelperResult.success)
    response.setNetworkList(targetNetworks)
    response.submit()
}

只有系统识别到你标记的WiFi需要Portal验证时，才会给你发presentUI命令。

3. 权限配置是重中之重，别漏了！ #

这是最容易踩的大坑，两个关键权限必须搞定：

• Hotspot Helper Entitlement：这个不是Xcode里直接能开的，得去苹果开发者后台申请com.apple.developer.networking.HotspotHelper这个权限，只有苹果批准后，你才能在Entitlements文件里添加它，否则注册永远失败。
• Hotspot Configuration 能力：在Xcode项目的Capabilities里，找到Hotspot Configuration并打开开关。
• 要是需要后台处理，还要开启Background Modes里的Network Extensions选项。

4. 别直接用NEHotspotConfigurationManager连！ #

如果你直接调用NEHotspotConfigurationManager.shared.apply(configuration:)去连captive WiFi，系统会跳过你的Helper，直接用自带的Portal页面，你的presentUI自然不会触发。正确的做法是：让系统通过你的Helper走流程——用户选完WiFi后，你只需要在filterScanList里标记它，系统会自动处理连接，检测到Portal后就会给你发presentUI命令。

5. 测试要注意这些细节 #

• 必须用真实设备测试，模拟器完全不支持NEHotspotHelper API。
• 确保APP是用正确签名的Xcode安装到设备上的，Entitlements要正确嵌入。
• 可以在回调里打印所有命令类型，看看系统有没有发presentUI，如果连其他命令都没收到，那肯定是注册或者权限问题。

我当时就是因为没申请到Hotspot Helper的权限，折腾了好几天才发现问题😭 按上面的步骤排查，应该能解决你的问题。

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