Flutter iOS App 如何获取可用 WiFi 列表？

Question

在 iOS 平台上，Flutter App 无法直接获取可用 WiFi 列表（SSID 扫描结果），这是由 Apple 严格的隐私与安全策略导致的典型技术限制：自 iOS 14 起，`NEHotspotNetwork` API 仅允许 App 查询**当前已连接的 WiFi 网络信息**（如 SSID、BSSID），且需用户明确授权（`Privacy - Location When In Use Usage Description` + 后台定位权限），但**完全禁止扫描或枚举周边未连接的 WiFi 热点**。即使使用 `wifi_scan`、`flutter_wifi_connect` 等第三方插件，在 iOS 上其扫描功能实际会静默失败或返回空列表。开发者常误以为配置了 Info.plist 权限（如 `NSLocationWhenInUseUsageDescription`）并请求了 `CLLocationManager` 授权即可实现扫描，却忽略该能力在 iOS 系统层面对第三方 App 的彻底禁用——仅限系统设置、企业级 MDM 或拥有特定 entitlement 的受信网络配置工具（如 NEHotspotConfiguration）。因此，“Flutter iOS 获取可用 WiFi 列表”本质上是一个**iOS 系统级不可行任务**，需引导用户转向替代方案（如手动输入 SSID、扫码配置、或通过配套 macOS/iPadOS 设备协同）。

Answer 1

```html

一、现象层：Flutter iOS 应用“WiFi 扫描为空”是普遍且可复现的失效行为

在真实设备（iOS 14.5+）上运行 wifi_scan: ^0.6.3 或 flutter_wifi_connect: ^4.2.0 插件时，scanForWifi() 调用后返回空列表 []，无错误抛出、无日志警告——这是典型的“静默降级”。Xcode 控制台亦不输出 CoreWLAN 或 NEHotspotNetwork 相关扫描日志。该现象与 Android 行为形成尖锐对比：同一套 Dart 代码在 Android 上可稳定获取 20+ SSID，而在 iOS 上恒为零。

二、权限层：Location 权限 ≠ WiFi 扫描能力，Apple 已明确解耦二者语义

权限声明项	iOS 系统作用	是否支持 WiFi 扫描
NSLocationWhenInUseUsageDescription	启用 CLLocationManager 定位服务	❌ 否（仅用于已连接网络的 BSSID 地理推断）
NSLocationAlwaysAndWhenInUseUsageDescription	允许后台定位（需额外用户授权）	❌ 否（Apple 明确禁止通过定位 API 推导 WiFi 列表）
com.apple.developer.networking.wifi-info entitlement	仅允许读取当前连接网络的 SSID/BSSID（需 Apple Developer Program 手动配置）	✅ 是（但仅限已连接网络）

三、API 层：NEHotspotNetwork 是唯一合规入口，但能力被严格限定

自 iOS 14 起，Apple 彻底废弃 CWInterface（CoreWLAN）对第三方 App 的开放接口。当前唯一受支持路径为：

// Swift 示例：仅能获取当前连接网络
NEHotspotNetwork.fetchCurrentNetwork { network in
  print("Connected SSID: \(network.ssid)") // ✅ 可行
  print("BSSID: \(network.bssid)")           // ✅ 可行
}
// ❌ 以下调用在 iOS 上直接编译失败或运行时返回 nil：
// CWInterface().scanForNetworks() → 不可用
// NEHotspotNetwork.scanForNetworks() → 不存在该 API

四、系统层：技术禁令源于隐私设计哲学——“Scanning is not a feature, it’s a fingerprinting vector”

Apple 在 NEHotspotNetwork 官方文档 中明确指出：“This API does not provide access to nearby networks — only the currently connected network.” 更深层机制在于：iOS 内核（XNU）在 WiFi 驱动层拦截了所有非系统进程发起的主动 Beacon Probe Request；即使越狱设备，绕过沙盒调用 ioctl(SIOCGIWRANGE) 也会因 apple80211 驱动策略返回 ENOTSUP 错误码。该限制与 App Tracking Transparency（ATT）同属“Privacy by Design”架构支柱。

五、生态层：可行替代路径矩阵（面向企业级与消费级场景）

• 扫码配置协议：采用 Wi-Fi Easy Connect（DPP）标准，通过 QR Code 传递加密凭证（config-method=qr-code），Flutter 调用 camera + qr_code_scanner 解析后交由 flutter_wifi_connect 自动连接
• 跨设备协同：利用 Continuity Framework，在 macOS/iPadOS 配套应用中完成扫描（macOS 允许 CWInterface.scanForNetworks()），再通过 multipeer_connectivity 实时同步 SSID 列表至 iOS 端
• MDM 集成方案：企业客户部署 Apple Business Manager + Jamf Pro，通过 MDM 命令下发预置 WiFi 配置（com.apple.wifi.managed payload），Flutter App 仅需触发 NEHotspotConfigurationManager.apply()

六、验证流程图：如何科学确认“非代码缺陷，而是系统封锁”

graph TD
  A[启动 Flutter App] --> B{调用 wifi_scan.scanForWifi()}
  B --> C[iOS 设备？]
  C -->|Yes| D[检查 Info.plist 是否含 Location 权限]
  D --> E[运行时请求 CLLocationManager 授权]
  E --> F[调用 NEHotspotNetwork.fetchCurrentNetwork]
  F --> G{是否成功获取当前 SSID？}
  G -->|Yes| H[→ 确认环境正常，但 scanForWifi 仍为空 → 系统级封锁]
  G -->|No| I[→ 检查 entitlement 与描述文件]
  C -->|No| J[Android 行为正常 → 进一步佐证 iOS 特异性]

七、历史演进视角：从 iOS 12 到 iOS 17 的能力退化轨迹

2018 年（iOS 12）：第三方 App 可通过私有 API Apple80211GetInfoCopy 获取扫描结果（越狱/企业签名）；
2020 年（iOS 14）：CoreWLAN 私有符号被彻底移除，NEHotspotNetwork 成为唯一公开接口，文档首次标注“no scanning capability”；
2022 年（iOS 16）：NEHotspotConfiguration 新增 isAutoJoinEnabled，强化“连接即授权”模型；
2023 年（iOS 17）：NetworkExtension 框架新增运行时校验，若检测到非系统进程尝试反射调用扫描方法，立即终止进程并上报 ASL 日志 NEHotspotNetwork: Scan attempt blocked by policy。

八、工程实践建议：面向交付的渐进式降级策略

1. 在 pubspec.yaml 中分离平台实现：wifi_scanner_platform_interface 抽象层 + wifi_scanner_ios（空实现）/ wifi_scanner_android（完整实现）
2. UI 层动态判断：if (Platform.isIOS) showManualSSIDInput() else showScanButton()
3. 埋点监控：对 iOS 端所有 scanForWifi() 调用记录 duration_ms=0 与 result_count=0，用于构建“不可用率”看板

九、法律与合规警示：规避 App Store 审核风险的关键红线

若在 iOS 构建中保留扫描逻辑（如条件编译未清除、插件未做平台裁剪），即使未实际调用，App Store 审核机器人可能通过静态分析识别 CoreWLAN.framework 引用或 scan 字符串而拒审。Apple 审核指南 5.1.1 Privacy - Data Collection and Storage 明确要求：“Apps must not collect information about nearby networks unless required for core functionality and with explicit user consent.” 而“扫描周边 WiFi”不被视为核心功能。

十、前沿探索：WebAuthn 与 Passkey 的潜在延伸价值

尽管无法扫描 WiFi，但 iOS 16+ 支持 WebAuthn 的 mediation 模式：当用户在 Safari 中访问设备管理网页（如 http://mydevice.local）并点击“配置网络”按钮时，可触发系统原生 WiFi 选择器（NEHotspotConfiguration UI），Flutter WebView 可通过 javascriptChannel 接收用户选定的 SSID。该路径绕过扫描限制，将决策权交还用户，符合 Apple “user intent first” 原则。

```