搞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字段区分这次扫描是普通前台扫描、后台扫描还是PNOPreferred 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来完成的。核心流程是wpa_supplicant_scan()检查当前状态是否允许扫描比如是不是正在连接中。调用wpa_supplicant_scan_trigger()把参数传给驱动接口的scan2()回调。在nl80211驱动里scan2()最终走向nl80211_trigger_scan()通过Netlink消息向内核发送NL80211_CMD_TRIGGER_SCAN请求。内核的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.4G5G的扫描请求驱动处理不当会导致扫描结果丢失其中一个频段。当时排查的结果是驱动在处理多频段扫描时并发逻辑有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结构体里面是一个BSSBasic 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默认200BSS列表最大条目数。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信号好很多的目标就触发漫游。典型配置是bgscansimple: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是否收到。排查的顺序一般是从上到下先看wpa_supplicant日志确认扫描是否触发、参数是什么。再用iw dev看驱动层面是否收到了扫描请求。接着用iw event确认内核是否完成了扫描并上报事件。最后用抓包工具看空口层面有没有实际交互。这个顺序能帮你快速把问题定位到“应用层”“驱动层”还是“空口环境”。6.2 高频问题对照我把这些年遇到的高频扫描问题整理成一张速查表方便你直接对着排查现象可能原因排查方向wpa_cli scan没反应连接/认证流程占用扫描锁查看当前状态机是否处于WPA_ASSOCIATING扫描结果为空被动扫描模式、信道被限制、驱动不返回结果用iw dev wlan0 scan对比确认是否内核侧也没有结果扫不到5GHz AP频段未使能、国家码限制、DFS信道检查iw reg get确认驱动支持5G扫描结果总是旧的BSS老化时间太长、扫描被抑制调小bss_expiration_age查看been_scanning逻辑漫游不灵敏bgscan阈值过高调整bgscan参数降低信号阈值扫描后连接卡顿扫描结果和配置网络不匹配检查配置文件SSID与加密是否一致这个表格只是个起点实际问题的组合方式千奇百怪但排查思路是共通的先把问题从整条链路里切出来别再全局瞎找。最后分享一点个人经验我调试扫描问题踩过最大的坑就是拿到日志后立刻钻进细节里一会儿看信道列表一会儿看信号强度结果转了半小时还在原地。如果你也遇到类似的困境我的建议是先明确“我要解释什么现象”然后严格沿着这条链路去走触发、参数、下发、驱动、内核、结果回收。每一步都先用最简单的工具确认“这一步有没有执行、结果对不对”再决定是否深入。wpa_supplicant的扫描流程虽然代码量不小但它的主线逻辑其实很清晰。把这套逻辑装进脑子里以后再遇到WiFi连接慢、漫游不灵敏、扫描结果异常这类问题你会比别人更快找出真正的原因。这也是写这篇东西的初衷。