wpa_supplicant扫描流程全解析：从触发到BSS管理

搞WiFi开发的人应该都有这种感觉：wpa_supplicant这名字天天挂在嘴边，wpa_cli的命令也敲得滚瓜烂熟，可一旦问到“扫描结果到底是怎么从空口跑到BSS列表里的”，很多人就开始含糊了。尤其是到了2.10这个版本，扫描相关的代码路径已经相当完整且复杂，不少人在调试连接慢、漫游不灵敏、扫描结果不全这类问题时，都是靠加日志瞎猜，效率非常低。

这篇内容我就把wpa_supplicant-2.10的扫描流程完整拆一遍，从触发方式、参数组装、内核交互，到结果回收和BSS管理，最后再补上实战排查的思路。不管你是做嵌入式驱动、做系统集成，还是平时需要排查网络问题的运维，把这条链路吃透，调试WiFi会顺手很多。

1. 为什么要啃扫描流程：它的位置比你想象的重要

1.1 扫描是连接的地基

很多人觉得扫描不就是发几个Probe Request、收几个Probe Response吗，有什么好研究的？真不是这样。

在一个完整的WiFi连接流程里，扫描承担的是“信息采集”的角色。终端要想连上某个AP，至少得知道：这个AP在哪个信道、叫什么名字、支持什么加密方式、信号强度多少。这些信息全部靠扫描拿回来，然后经过筛选、排序、匹配，才能进入后面的认证和关联阶段。扫描一旦出错，后面全是白搭。

我曾经调试过一个很隐蔽的问题：设备在特定位置连不上公司网络，最后定位到是扫描阶段拿到的BSS信息里，某个AP的信号强度被错误缓存了，导致每次选网都选到一个远的AP上，连接频繁失败。这种问题如果不理解扫描和BSS维护的机制，根本无从下手。

1.2 谁会被这片代码吸引

如果你属于下面几类人，这篇文章值得你花十几分钟看完：

• 做嵌入式WiFi模组或者路由器开发，需要裁剪或优化wpa_supplicant扫描行为；
• 做Android或Linux系统集成，经常遇到“WiFi连接慢”“自动重连不工作”这类问题；
• 做无线网络运维，希望理解终端侧扫描行为对网络性能的影响。

不管哪一类，核心目标是一致的：弄懂扫描这条链路里的每个环节，出了问题能快速定位，优化时有明确方向。

2. 扫描的触发机制：谁喊醒了扫描模块

扫描不是无缘无故发生的。wpa_supplicant里有好几条触发路径，理解这些路径的区别，是你学会控制扫描的第一步。

2.1 显式触发：wpa_cli scan和你

最直接的方式就是你拿wpa_cli手动敲一条scan命令。这条命令会走ctrl接口进入wpa_supplicant_ctrl_iface_scan()，最终落到wpa_supplicant_scan()这个核心函数里。

这条路径的特点是：触发源明确、用户意图明确，wpa_supplicant基本不做额外的“要不要扫”的判断，直接进入扫描流程。所以调试时如果你想复现问题，手动触发是最干净的手段：

wpa_cli -i wlan0 scan wpa_cli -i wlan0 scan_results

第二条命令用来确认扫描结果有没有正确更新。这两条命令组合，基本能覆盖“扫描触发”和“结果获取”两端。

2.2 隐式触发：定时、信号和漫游

除了手动命令，wpa_supplicant还有几种自动触发扫描的机制：

第一种是定时扫描。通过配置文件里的scan_interval参数控制间隔，单位为秒。默认值我记得是5秒，也就是终端在没有连接、处于空闲扫描状态时，大概每5秒会主动扫一次。这个值如果设得太小，会频繁唤醒射频模块，功耗明显增加；设得太大，又会延迟发现新网络，适合的取值是个权衡题。

第二种是信号变差触发漫游扫描。关联状态下，如果当前AP的信号降到某个阈值以下，wpa_supplicant会执行后台扫描，寻找有没有信号更好、更合适的AP。这个逻辑在wpa_supplicant_need_roaming()这类函数里判断，具体行为还和bgscan模块的配置相关。

第三种是连接失败之后的自动重扫。当连接失败或认证失败后，wpa_supplicant会进入WPA_DISCONNECTED或WPA_SCANNING状态，并重新扫描可用网络。这种机制保证了断线之后设备能尽快找到其他可用AP，但同时也意味着，如果扫描本身有延迟或者结果缺失，重连速度会肉眼可见地变慢。

这里有个容易忽略的点：2.10里面，扫描请求还会带一个type字段，区分这次扫描是普通前台扫描、后台扫描还是PNO（Preferred Network Offload）扫描。驱动和应用层可以根据这个字段决定不同优先级，但这也带来一个隐患——有些驱动实现得不够好，几种扫描复用同一套逻辑，互相干扰，这是后话。

2.3 一个容易被忽略的触发者：网络请求

还有一种触发路径是“主动连接请求”。也就是说，当你调用wpa_cli connect或者上层应用发起连接时，如果wpa_supplicant手里没有足够的BSS信息（比如指定SSID从来没扫到过），它会在真正发起连接之前先补一次扫描。

这个逻辑藏在连接流程的前置检查里。好处是能保证连接时使用最新的信道和带宽信息，坏处是增加了连接时延。实测中，如果扫描阶段卡住，连接请求就会一直等在那里，表现为“点了连接但很久没反应”。

3. 扫描请求的完整生命周期：从参数组装到驱动下发

3.1 参数是怎么一步步被填满的

扫描不是把网卡扔出去随便抓一把。wpa_supplicant在真正下发扫描前，会先组装一个struct wpa_driver_scan_params结构体，里面包含几个关键字段：

• ssids和num_ssids：要扫描的目标SSID列表。最多能填16个SSID。
• freqs和num_freqs：要扫描的信道列表。如果不填，默认就是扫全信道。
• filter_ssids：是否过滤掉非目标SSID的扫描结果。
• passive_scan：是否使用纯被动扫描。

为什么要有这么多参数？直接原因是空口资源是有限的，盲扫代价太高。如果你的终端只想找到一个指定的SSID，完全没必要把2.4G和5G所有信道挨个扫一遍。指定SSID和信道，可以大幅缩短扫描时间、降低功耗，同时减少对同频段其他设备的干扰。

在这里我需要特别提一下passive_scan。默认情况下wpa_supplicant做的是主动扫描，也就是在每个信道上发Probe Request。但某些场景下（比如合规要求、雷达检测信道、或者驱动限制），不能发主动探测帧，只能监听Beacon，这就是被动扫描。2.10里对被动扫描的支持已经比较完善，但被动扫描有个天然劣势：如果AP的Beacon间隔设置得比较长（常见的是100ms），监听时间不够就可能漏掉这个AP。

3.2 驱动调用链和nl80211的关系

参数组装好之后，真正的下发路径是通过wpa_driver_nl80211来完成的。核心流程是：

1. wpa_supplicant_scan()检查当前状态是否允许扫描（比如是不是正在连接中）。
2. 调用wpa_supplicant_scan_trigger()，把参数传给驱动接口的scan2()回调。
3. 在nl80211驱动里，scan2()最终走向nl80211_trigger_scan()，通过Netlink消息向内核发送NL80211_CMD_TRIGGER_SCAN请求。
4. 内核的cfg80211模块接收到请求后，和具体芯片驱动配合，真正控制射频硬件完成空口扫描。

这条链路里，wpa_supplicant只是“提出要求的应用”，最终执行者其实是内核和底层驱动。所以你在排查扫描问题时，如果确认wpa_supplicant已经发出了请求，但空口一直没有实际扫描动作，那问题大概率出在内核cfg80211或者芯片驱动这一层，而不是wpa_supplicant本身。

这个判断逻辑非常重要。我见过不少人拿着tcpdump抓wpa_supplicant日志，发现“驱动返回失败”就觉得是wpa_supplicant的bug，实际上人家只是传声筒，背锅的是驱动。

3.3 扫描类型与信道选择的取舍

在组装扫描参数时，有一个环节叫“扫描信道排序”。wpa_supplicant会把要扫的信道按频段、当前信道状态重新排列，优先扫描那些更可能出结果的信道。

2.10里对5GHz和6GHz频段有额外的处理逻辑。比如6GHz频段只能在支持6GHz的网卡上扫描，而且涉及到一些额外的合规判断。如果你的设备明明支持6GHz却总是扫不到6GHz的AP，先别急着怀疑天线，去查一下wpa_supplicant编译时有没有开启对应的频段支持。

另外一个取舍是“全信道扫描 vs 单信道扫描”。手动触发通常扫全信道，但漫游触发的后台扫描通常集中心跳信道附近，这个策略也直接反映了扫描请求参数里freqs字段的差异。

这里顺便提一个我踩过的坑：在某些驱动上，如果同时下发多个频段（2.4G+5G）的扫描请求，驱动处理不当会导致扫描结果丢失其中一个频段。当时排查的结果是，驱动在处理多频段扫描时并发逻辑有bug，需要对驱动打补丁。这个问题的表象是“5GHz信号扫不到”，但根因不在扫描命令本身，而在驱动的命令处理流程。

4. 扫描结果的回收与加工：BSS列表里的门道

扫描请求发出去只是上半场，下半场是“结果回收和加工”。这一块很多人不熟悉，但恰恰是问题最多的地方。

4.1 结果事件怎么冒上来

内核的cfg80211扫描完成后，会通过Netlink向用户空间发送NL80211_CMD_NEW_SCAN_RESULTS事件。nl80211驱动收到这个事件后，会调用wpa_supplicant_event()，传递的事件类型是EVENT_SCAN_RESULTS。

wpa_supplicant收到这个事件后，进入wpa_supplicant_scan_results()，这里会调用驱动接口的scan_results()回调，把内核缓存的完整扫描结果拿回来。拿到的结果是一个struct wpa_scan_results结构体，里面是一个BSS（Basic Service Set）的数组。

整个结果回收过程要注意一个关键点：wpa_supplicant不会主动去轮询扫描是否完成，它完全依赖事件驱动。也就是说，如果内核因为某些原因没有正确上报扫描完成事件，应用层就会一直傻等，表现出来就是扫描卡住、wpa_cli scan之后没有反应。

这种“事件丢失”的问题不算罕见。不少4G路由器上，内核驱动和wpa_supplicant的版本匹配不佳，容易出现扫描完成事件偶尔丢失的情况。遇到这种，优先查看驱动和内核的版本兼容性。

4.2 BSS的增删改查与老化

拿到扫描结果后，wpa_supplicant要做的不只是“记下来”，它维护了一个BSS列表，每个BSS都包含MAC地址、SSID、信号强度、加密方式、支持的信道速率等信息。新结果进来之后，逐个和现有列表比对：

• 如果这个BSS已经存在，就更新各项参数（比如信号强度、时间戳）；
• 如果是不存在的BSS，就插入新条目；
• 如果某个BSS长期没有更新，就等它老化并最终删除。

BSS列表不是无限增长的，它有严格的淘汰机制。2.10里和BSS老化相关的参数主要有几个：

• bss_max_count：默认200，BSS列表最大条目数。
• bss_expiration_age：默认30秒，BSS条目超过这个时间没有被更新就列为过期候选。
• bss_expiration_scan_count：默认2，表示连续两次扫描都未再出现的BSS才会被真正删除。

这几个参数直接影响“扫到但连不上”这类现象的严重程度。比如你把bss_max_count设得太小，可能把某些信号弱但可用的AP提前挤掉；而如果bss_expiration_age设得太大，终端又可能拿过期信息去尝试连接，白白增加失败次数。

如果你发现家里某个AP多次开关之后，终端总是连不上或者连到旧地址，可以考虑适当调小bss_expiration_age，让旧信息更快失效。

4.3 结果排序和SSID过滤

扫描完成后，wpa_supplicant还会对BSS列表做“加工”。它会把结果按照信号强度排序，并针对配置文件里定义的网络（也就是你保存的WiFi账号）做匹配。

这个匹配逻辑值得多说一句：wpa_supplicant不会“看到啥就连啥”，它只会选择那些和自己配置文件网络匹配的BSS来尝试连接。也就是说，如果一个AP的加密方式和配置不匹配，就算信号再强，也不会被选中。

这里的“SSID过滤”和扫描请求参数里的filter_ssids也有关系。如果你配置了某个网络，扫描时wpa_supplicant会优先扫这个网络对应的SSID，同时在处理结果时更关注这些BSS，其他SSID的结果基本不会进入连接决策。

所以，常见的“我能扫到隔壁家的WiFi，但是连接列表里不出现”这种问题，根本原因就是配置文件的网络匹配条件没满足。它不代表扫描出了问题。

5. 扫描状态机与连接的协同

扫描不是孤立的，它和连接状态机紧密交织。理解它们之间的协同关系，是排查复杂连接问题的关键。

5.1 扫描时连接状态怎么转换

wpa_supplicant有一个核心状态机，状态包括WPA_DISCONNECTED、WPA_SCANNING、WPA_AUTHENTICATING、WPA_ASSOCIATING、WPA_ASSOCIATED、WPA_COMPLETED等。

当一次扫描触发时，如果当前没有连接，wpa_supplicant通常会进入WPA_SCANNING状态。扫描完成后，根据结果决定是继续扫描、发起连接，还是回到空闲。

但要注意，如果当前已经关联在一个AP上，触发的后台扫描不会立即改变主状态机。它更像是一个“并行任务”——连接保持，扫描结果只用于判断是否需要漫游。这种设计是为了保证连接不中断。

这里有个微妙的地方：wpa_supplicant会检查“当前是否有关联请求或者正在认证”，如果是，会暂时忽略非紧要的扫描请求。这个保护机制能避免扫描干扰正在进行的连接流程，但也会导致一种现象：你手动发了一个扫描命令，结果被“吞”了，日志里看不到扫描动作。遇到这种情况不妨先确认一下是不是正处于连接或认证过程中。

5.2 后台扫描与漫游

上面提到，关联状态下触发的扫描是后台扫描，专门服务于漫游决策。2.10支持的bgscan模块包含几种策略，最常用的是bgscan_simple。

bgscan_simple的逻辑大致是：信号强度在一个阈值区间内波动时，周期性地扫描周围AP。如果发现有比当前AP信号好很多的目标，就触发漫游。典型配置是：

bgscan="simple:30:-65:300"

含义是每30秒做一次后台扫描，信号低于-65dBm时开始考虑漫游，扫描结果在300秒内有效。这个参数组合需要根据实际环境调整，室内室外、2.4G还是5G，最优值差别很大。

实际测试中我发现一个规律：漫游不灵敏，十有八九是bgscan参数里的信号阈值设得太低，导致终端觉得“当前还能用”就一直不扫，直到信号已经差到影响吞吐才想起来漫游。反过来，阈值设太高又会导致频繁扫描，甚至乒乓漫游。这个阈值没有万能解，只能逐场景调。

5.3 一个不起眼但关键的坑：扫描期间的请求抑制

前面提到了“请求会被吞”的现象，这里展开说一下。

在wpa_supplicant_scan()函数里，有一系列前置条件检查。比如：

• 如果当前正处于连接中（wpa_s->connection_in_progress），多数非强制扫描会被拒绝；
• 如果上次扫描结束时间距离现在太近（been_scanning时长控制），会延迟处理；
• 如果驱动反馈“正在忙”，wpa_supplicant会把这个扫描请求挂起或直接丢弃。

这些设计的本意是好的，防止扫描请求过密导致系统不稳定。但也带来了一个调试陷阱：你在短时间内连续多次触发扫描，后面的请求很可能被静默忽略，日志里没有任何明显的报错，只是没有扫描动作。

我排查过一个问题：某设备在进入某个区域后反复尝试连接，但每次都失败。日志显示每次连接前都发起了扫描，但扫描结果始终是旧的。后来才发现，这是连接失败后的快速触发扫描被been_scanning抑制了，终端拿的是上次扫描的旧结果去尝试连接，自然一直失败。这个问题的解法是调整扫描抑制参数，或者确保连接失败后能强制刷新扫描结果。

6. 实战排查：扫描流程出问题时怎么查

代码看得再多，真到了现场，还是要靠日志和工具。这一节我分享一些实际排查中高效实用的手段。

6.1 常用工具与日志

先列几个必备工具：

• wpa_cli -i wlan0 scan：手动触发扫描。
• wpa_cli -i wpa_debug_level：调整wpa_supplicant的日志级别，wpa_cli log_level debug可以打开调试日志。
• iw dev wlan0 scan dump：直接看内核缓存的最新扫描结果。
• iw event：监听内核Netlink无线事件，确认扫描完成事件是否到达。
• tcpdump -i wlan0 -e -n：抓空口包，确认Probe Request是否发出去、Probe Response是否收到。

排查的顺序一般是从上到下：

1. 先看wpa_supplicant日志，确认扫描是否触发、参数是什么。
2. 再用iw dev看驱动层面是否收到了扫描请求。
3. 接着用iw event确认内核是否完成了扫描并上报事件。
4. 最后用抓包工具看空口层面有没有实际交互。

这个顺序能帮你快速把问题定位到“应用层”“驱动层”还是“空口环境”。

6.2 高频问题对照

我把这些年遇到的高频扫描问题整理成一张速查表，方便你直接对着排查：

这个表格只是个起点，实际问题的组合方式千奇百怪，但排查思路是共通的：先把问题从整条链路里切出来，别再全局瞎找。

最后分享一点个人经验

我调试扫描问题踩过最大的坑，就是拿到日志后立刻钻进细节里，一会儿看信道列表，一会儿看信号强度，结果转了半小时还在原地。

如果你也遇到类似的困境，我的建议是先明确“我要解释什么现象”，然后严格沿着这条链路去走：触发、参数、下发、驱动、内核、结果回收。每一步都先用最简单的工具确认“这一步有没有执行、结果对不对”，再决定是否深入。

wpa_supplicant的扫描流程虽然代码量不小，但它的主线逻辑其实很清晰。把这套逻辑装进脑子里，以后再遇到WiFi连接慢、漫游不灵敏、扫描结果异常这类问题，你会比别人更快找出真正的原因。这也是写这篇东西的初衷。