企业官网建设流程全解析

1. 从一次Wi-Fi断流排查说起

前阵子帮一个做工业平板的朋友排查问题，设备用的是Qualcomm平台，Android 13，出厂后偶尔出现Wi-Fi扫描不到AP、连接后频繁掉线、热点开启失败的情况。抓了logcat和dmesg，发现WCNSS（Wireless Connectivity SubSystem，高通无线连接子系统）在初始化阶段报了一堆参数解析失败。顺着日志翻下去，问题最终落在一个文件上：WCNSS_qcom_cfg.ini。

这个文件在高通Android方案里几乎无处不在，从手机、平板到车机、POS机、工业手持终端，只要用到高通Wi-Fi/BT/GPS三合一芯片，基本都会在/vendor/etc/wifi/或者/system/etc/wifi/下看到它。但真正把它讲清楚的中文资料并不多，大部分工程师只是从别的项目里拷贝一份过来，改改SSID、改改信道就完事，遇到深层次问题就抓瞎。

这篇是系列第三篇，前两篇分别讲了基础连接参数和电源管理相关配置，这一篇重点聊射频与扫描行为控制、漫游与切换策略、以及调试诊断类参数。这些参数直接决定了设备在复杂无线环境下的表现，也是工业场景、多AP组网场景下最容易踩坑的地方。如果你正在做高通平台的Wi-Fi定制、认证测试或者现场问题排查，这篇内容应该能帮你省下不少抓包的时间。

需要先说明一点：WCNSS_qcom_cfg.ini的完整参数列表是高通随WLAN驱动（qcacld系列）一起发布的，不同芯片型号（比如WCN3990、WCN6750、WCN6856）和不同驱动版本之间会有差异。我下面讲到的参数，都是基于常见qcacld-3.0及后续版本的实际配置文件整理，具体到你手上的项目，建议以高通release note里的cfg.ini模板为准，不要盲目照搬。

2. 射频与扫描行为控制参数详解

2.1 扫描相关的核心参数组

扫描行为是Wi-Fi体验的第一道门槛。设备搜不到AP、搜得慢、搜到一堆弱信号AP，基本都是扫描参数没调好。WCNSS_qcom_cfg.ini里跟扫描相关的参数主要有这么几个：

gScanBmissThreshold=0 gScanResultAgeCount=1 gScanAgingTime=60 gChannelBondingMode5GHz=1 gEnableScanOffload=1 gScanHomeAwayTime=0

先看gScanResultAgeCount和gScanAgingTime。这两个参数控制的是扫描结果缓存的老化策略。gScanResultAgeCount表示扫描结果在被丢弃前可以经历多少次老化周期，gScanAgingTime则是每个老化周期的时长（单位秒）。默认配置下，一个扫描结果最多存活AgeCount * AgingTime秒。我见过有项目把gScanAgingTime设成300，结果设备在AP已经关机的情况下还显示着这个AP，用户点了连接才发现连不上。工业场景里AP位置固定，可以适当调大；移动场景比如手持终端，建议保持60秒左右，让扫描结果快速刷新。

gScanHomeAwayTime这个参数比较有意思，它控制的是扫描时在home channel和away channel上停留的时间比例。单位是毫秒，0表示使用驱动默认值。在多AP漫游场景下，如果设备频繁在两个AP之间切换，可以适当增大这个值，让设备在非当前信道上有更多时间收集邻居AP信息，为漫游决策提供依据。但调太大又会影响当前连接的吞吐，需要根据实际AP密度来权衡。

gEnableScanOffload是扫描卸载开关。高通芯片支持把扫描任务下放到固件层执行，CPU不用全程参与，省电效果明显。但这个功能在某些老版本固件上有bug，会导致扫描结果上报延迟。如果你的项目对功耗不敏感但对实时性要求高，可以关掉它；如果是电池供电的移动设备，建议保持开启。

2.2 信道与频段控制

信道相关的参数直接关系到设备能用哪些频段、怎么用：

gChannelBondingMode5GHz=1 gChannelBondingMode24GHz=0 gEnableDfsChannel=1 gEnableForceDfs=0 gCountryCodePriority=1

gChannelBondingMode5GHz控制5GHz频段是否启用信道绑定（也就是40MHz、80MHz带宽）。设为1表示允许绑定，设为0表示只用20MHz。这里有个常见的误区：很多人以为带宽越大越好，实际上在AP密集的办公环境里，80MHz绑定反而会因为信道重叠导致干扰加剧，吞吐不升反降。我的经验是，如果周围5GHz AP超过5个，建议先用20MHz跑一段时间，用iw命令看看实际重传率再决定要不要开绑定。

gEnableDfsChannel控制是否使用DFS信道（动态频率选择信道，也就是5GHz里需要雷达检测的那部分信道）。DFS信道的好处是干扰少，坏处是设备需要做雷达检测，检测期间不能发射，会导致连接建立变慢，而且如果检测到雷达信号还得主动避让。家用场景可以开，工业场景如果周围有雷达设备（比如某些测距仪），建议关掉，避免频繁信道切换。

gCountryCodePriority这个参数容易被忽略。它决定国家码的优先级来源：设为1表示优先使用AP广播的国家码，设为0表示优先使用系统设置里的国家码。这个参数在认证测试时特别重要，因为不同国家对可用信道和发射功率的限制不同。如果设备要出口到多个地区，建议设为1，让设备跟随AP的国家码自动调整，减少手动配置的工作量。

2.3 发射功率与速率控制

发射功率和速率控制参数直接影响连接稳定性和吞吐：

gTxPowerCap=30 gTxPowerCap5G=30 gMaxTxPower=30 gRateCtlEnable=1 gEnableTxBF=1

gTxPowerCap和gTxPowerCap5G分别控制2.4GHz和5GHz的最大发射功率，单位是dBm。这里要注意，这个值不能超过当地法规限制，也不能超过芯片和前端模块的物理上限。我见过有项目为了追求覆盖，把这个值设成30dBm，结果认证测试时EIRP超标，整机返工。一般来说，2.4GHz设20dBm左右，5GHz设23dBm左右是比较稳妥的起点，具体要看你的天线增益和前端PA的能力。

gRateCtlEnable是速率控制开关。开启后，驱动会根据信道质量和重传情况动态调整MCS速率。这个功能在移动场景下非常有用，但如果在固定场景下发现速率波动太大，可以尝试关掉，让速率固定在某个档位，换取更稳定的延迟表现。工业控制场景对延迟抖动敏感，我通常会建议先关掉速率自适应，手动锁定一个中等速率（比如MCS4），实测延迟抖动能从几十毫秒降到个位数。

gEnableTxBF是发射波束成形开关。这个功能需要AP和STA同时支持才能生效，开启后能提升信号质量，但会增加功耗。如果设备是电池供电且对吞吐要求不高，可以关掉省电。

3. 漫游与切换策略参数拆解

3.1 漫游触发条件配置

漫游是Wi-Fi体验里最玄学的部分。设备什么时候该切、切到哪个AP，全靠参数控制：

gRoamIntraBand=0 gRoamScanHiRssiThreshold=-70 gRoamScanLoRssiThreshold=-80 gRoamRssiDiff=5 gRoamScanControl=1 gNeighborLookupThreshold=-72

gRoamIntraBand控制是否允许同一频段内漫游。设为0表示允许，设为1表示禁止。这个参数在双频合一SSID的场景下要特别注意：如果禁止同频漫游，设备在2.4GHz信号变差时会尝试切到5GHz，但如果5GHz信号也不好，就会来回跳。我的建议是保持允许同频漫游，同时配合RSSI阈值来控制切换时机。

gRoamScanHiRssiThreshold和gRoamScanLoRssiThreshold是一对阈值。当当前AP的RSSI低于Hi阈值时，设备开始扫描邻居AP；低于Lo阈值时，强制触发漫游。这两个值设得太近会导致频繁扫描，设得太远又会导致切换不及时。经验值：Hi设-70dBm，Lo设-80dBm，中间留10dBm的缓冲，既能及时触发扫描，又不会太激进。

gRoamRssiDiff是漫游判决的RSSI差值门限。只有当候选AP的RSSI比当前AP高出这个值时，才会触发切换。这个参数是防止乒乓效应的关键。设得太小（比如2dBm），设备会在两个信号相近的AP之间反复横跳；设得太大（比如10dBm），又会导致该切的时候不切。5dBm是个比较平衡的值，实测在办公环境里表现稳定。

gNeighborLookupThreshold控制邻居AP查找的触发门限。当RSSI低于这个值时，驱动会主动查询邻居报告。这个值通常比gRoamScanHiRssiThreshold略低一点，形成两级触发机制。

3.2 802.11k/v/r相关支持

快速漫游离不开802.11k/v/r这三个协议的支持：

gEnable11k=1 gEnable11v=1 gEnable11r=1 gEnableFT=1 gFTReassocTimeout=1000

gEnable11k开启邻居报告功能，让AP告诉设备周围有哪些邻居AP，省去设备自己扫描的时间。gEnable11v开启BSS过渡管理，让AP可以主动建议设备切换到某个更好的AP。gEnable11r和gEnableFT开启快速BSS切换，通过预认证减少切换时的断流时间。

这三个功能要生效，需要AP侧也支持。如果AP不支持，开了也没用，但一般不会有副作用。不过在认证测试时要注意，有些测试用例会检查设备是否正确处理了不支持这些功能的AP。

gFTReassocTimeout是快速切换的重关联超时时间，单位毫秒。默认1000ms，如果网络环境复杂可以适当调大，但不要超过3000ms，否则切换失败后回退太慢。

3.3 漫游相关的注意事项

这里分享几个实际踩过的坑：

注意：漫游参数在不同驱动版本里的命名可能不同。比如qcacld-2.0里叫gRoamRssiDiff，qcacld-3.0里可能叫gRoamRssiDiff但单位从dB变成了dBm的绝对值。改之前一定要看对应版本的参数说明文档。

注意：如果设备同时开启了热点和STA连接，漫游行为会变得复杂。热点模式下，设备不能随意切换信道，否则热点会断。这种情况下建议把漫游阈值调保守一些，避免频繁触发。

还有一个经验：在Mesh组网或者多AP同SSID的场景下，把gRoamScanControl设为1可以让驱动更积极地扫描，但会增加功耗。如果是固定安装的设备，可以设为0，减少不必要的扫描。

4. 调试诊断与日志控制参数

4.1 日志级别与调试开关

排查Wi-Fi问题时，日志是第一手资料。WCNSS_qcom_cfg.ini里控制日志的参数：

gDebugLevel=0 gEnableFWLog=0 gEnableSmeDebug=0 gEnableCfg80211Debug=0 gEnableWlanDebug=0

gDebugLevel是主调试级别，0表示关闭，数值越大日志越详细。量产版本建议设为0，减少日志输出对性能的影响。调试版本可以设成2或3，但要注意日志量会非常大，可能几秒钟就刷出几百MB。

gEnableFWLog控制固件日志。这个功能在排查底层射频问题时非常有用，但需要配合专门的工具解析。开启后固件会把内部状态写到共享内存，驱动再读出来。如果只是排查连接问题，一般不需要开。

gEnableSmeDebug、gEnableCfg80211Debug、gEnableWlanDebug分别控制SME（Station Management Entity）、cfg80211和WLAN驱动的调试日志。这几个开关建议按需开启，全开的话logcat会被刷爆。

4.2 统计信息与性能监控

gEnableStats=1 gEnableRssiMon=1 gRssiMonInterval=1000 gEnableLinkStats=1

gEnableStats开启统计信息收集，包括收发帧数、重传次数、丢包率等。这些数据可以通过iw或者厂商提供的工具读取，是判断链路质量的重要依据。

gEnableRssiMon和gRssiMonInterval控制RSSI监控。开启后驱动会定期上报RSSI值，间隔由gRssiMonInterval控制，单位毫秒。1000ms是个比较合适的值，既能跟踪信号变化，又不会太频繁地上报。

gEnableLinkStats开启链路统计，包括每个速率档位的收发计数。这个功能在调试速率自适应问题时特别有用，可以看到设备实际用了哪些速率、各速率的成功率如何。

4.3 调试参数的使用建议

提示：调试参数只在排查问题时开启，问题解决后务必关掉。我见过有项目忘了关gEnableFWLog，结果设备跑了一周后存储被日志写满，系统直接卡死。

提示：不同芯片的调试参数支持程度不同。比如WCN3990对gEnableStats的支持就比较有限，很多统计项读出来是0。遇到这种情况不要死磕，换个思路用抓包分析。

还有一个实用技巧：如果怀疑是参数配置问题，可以先把WCNSS_qcom_cfg.ini备份，然后替换成高通提供的默认模板，看问题是否复现。如果默认模板没问题，再逐项对比找出差异参数。这个方法比逐行读配置文件快得多。

5. 参数调优的实操流程与避坑指南

5.1 从默认配置到定制配置的完整流程

拿到一个高通项目，我通常按这个流程来调Wi-Fi参数：

第一步，确认基线。从高通release包里找到对应芯片和驱动版本的WCNSS_qcom_cfg.ini模板，不要用其他项目拷贝过来的文件。不同版本的参数默认值差异很大，混用容易出玄学问题。

第二步，明确场景需求。是固定安装还是移动使用？是电池供电还是市电？周围AP密度如何？有没有雷达设备？这些问题的答案直接决定了参数调整方向。

第三步，逐项调整并记录。每次只改一个参数，改完做一轮测试（扫描、连接、吞吐、漫游、功耗），记录结果。不要一次改一堆参数，出了问题根本不知道是哪个引起的。

第四步，回归测试。参数调好后，要在目标场景下跑至少24小时稳定性测试，同时用iw dev wlan0 station dump定期抓取链路状态，确认没有异常波动。

5.2 常见问题速查表

5.3 几个容易踩的坑

第一个坑：参数名大小写敏感。WCNSS_qcom_cfg.ini里的参数名是大小写敏感的，gEnableScanOffload和genablescanoffload是两个不同的东西，后者会被忽略。我见过有工程师从网页上复制参数，大小写变了，排查了半天。

第二个坑：参数值格式。有些参数是布尔值（0/1），有些是整数，有些是字符串。比如gCountryCodePriority=1和gCountryCodePriority=US是完全不同的含义。改之前一定要确认参数类型。

第三个坑：配置文件位置。不同Android版本和不同厂商的定制，WCNSS_qcom_cfg.ini的位置可能不同。常见位置有/vendor/etc/wifi/、/system/etc/wifi/、/etc/wifi/。如果改了没生效，先确认文件路径对不对，再看权限是否正确。

第四个坑：参数冲突。有些参数之间存在互斥关系，比如gEnable11r和某些老版本AP的兼容性问题。如果开了11r后连接不稳定，可以先关掉试试。

5.4 验证参数是否生效的方法

改完参数后，怎么确认真的生效了？我常用的方法有这几个：

方法一：看驱动日志。在dmesg里搜索参数名，驱动加载时会打印实际使用的配置值。比如gRoamRssiDiff生效的话，日志里会有类似Roam RSSI diff: 5的输出。

方法二：用iw命令读运行时状态。比如iw dev wlan0 get power_save可以看省电模式，iw dev wlan0 station dump可以看链路统计。虽然不能直接读配置文件，但可以通过行为反推参数是否生效。

方法三：对比测试。改参数前后各跑一轮相同的测试用例，对比结果差异。这个方法最可靠，但需要设计好测试用例，控制变量。

方法四：用厂商工具。高通有一些内部工具可以读取WCNSS的配置状态，但一般不对普通开发者开放。如果有渠道拿到，是最直接的验证方式。

6. 写在最后的几句实在话

WCNSS_qcom_cfg.ini这个文件，说复杂也复杂，几百个参数；说简单也简单，大部分项目只需要改其中十几个。关键是要理解每个参数背后的逻辑，知道改了之后会影响什么。

我个人的经验是，不要迷信所谓的“最优配置”。同一个参数，在办公场景下表现很好，换到工业场景可能就是一坨。一定要结合自己的实际使用环境来调，调完要实测，实测要跑够时间。

另外，高通每个季度都会更新WLAN驱动和配置文件模板，建议定期关注release note，看看有没有新增参数或者默认值变更。有些问题可能在新版本里已经修了，没必要自己死磕。

最后分享一个小技巧：如果你不确定某个参数的作用，可以把它设成两个极端值（比如0和最大值），各跑一轮测试，观察行为差异。这比读文档快得多，也直观得多。当然，测试环境要隔离，别在量产设备上瞎搞。