简介一份基于Qt与wpa_supplicant的WiFi管理示例工程适合Linux平台下开发无线网络应用的开发者尤其是嵌入式或触屏场景。工程通过Qt代码调用系统wpa_supplicant服务实现附近WiFi的刷新搜索、列表显示最多20个并支持WEP/WPA2等加密方式的连接连接时密码输入框可弹出软键盘解决无物理键盘设备的输入痛点。压缩包共21个文件约2.94MB以5个cpp和4个h源码为核心搭配3个ui界面布局、2个qrc资源、1个pro工程配置并内置syszuxpinyin软键盘组件和png/bmp背景图结构清晰、便于二次开发。目前已有1010人学习下载。读者可获得完整可编译的Qt工程源码既能学习Linux下通过wpa_supplicant管理无线网络的具体调用流程也能直接复用其WiFi列表界面、加密连接逻辑与软键盘组件适合作为课程设计、毕业设计或工业触屏项目的起点。Qt 无线连接实战搜索、显示、连接与软键盘弹出的完整方案做嵌入式 Qt 开发的朋友大概率都遇到过这类需求一块触摸屏设备要在界面上实现 WiFi 搜索、显示、连接还要在输入密码的时候自动弹出软键盘。之前在做车载后排娱乐终端时正好全程趟了一遍这个坑从底层无线管理到上层 UI 交互都踩过不少雷。这篇文章就把这套“Qt 无线连接 WiFi 搜索显示连接 可弹出软键盘”的完整方案拆开讲清楚包括方案选型、扫描结果解析、连接流程、软键盘集成和问题排查希望能帮到正在做类似功能的朋友。这套方案更适合 Linux 环境下带触摸屏的嵌入式设备比如工控面板、一体机、车载设备等如果你只是做桌面 PC 上的 WiFi 管理界面也能参考核心逻辑。文中用到的底层工具是 wpa_supplicant 配套的 wpa_cli这是 Linux 无线网卡最常用的管理方式接口稳定且依赖少比直接调 DBus 或 NetworkManager 更直观也更适合在定制系统里落地。1. 功能拆解与整体设计思路1.1 先把需求拆成四个层拿到“WiFi 搜索显示连接 软键盘”这个需求先别急着写界面。我习惯把任务拆成四层每层各司其职后续出问题也好定位无线网卡操作层负责启用网卡、扫描、连接、断开、查询状态。这是最底层的部分和具体无线协议打交道。数据解析层把底层命令输出的文本或返回码转换成 Qt 能用的数据结构比如 WiFi 列表、信号强度、加密方式、连接状态。UI 展示层负责把 WiFi 列表、信号格数、连接状态、当前连接名等信息画到界面上。交互处理层处理用户的点击、输入密码、点击连接、弹出软键盘、刷新列表等交互事件。这四个层之间尽量解耦。我在实际开发中把底层操作封装成一个 WifiManager 类UI 层只调用这个类的接口不直接执行命令或解析输出。这样后续如果要把底层从 wpa_cli 换成 NetworkManager只需要改 WifiManager 内部实现UI 层完全不用动。1.2 无线管理方案选型为什么用 wpa_cliLinux 下管 WiFi 常见有几种方案直接操作 wpa_supplicant 的 DBus 接口、通过 NetworkManager 的 DBus 接口、调用 nmcli 命令行、调用 wpa_cli 命令行。我也见过有人直接写 socket 和 wpa_supplicant 通信但那是少数偏底层驱动的玩法。我的建议是嵌入式定制系统优先用 wpa_cli理由有三个。第一wpa_cli 是 wpa_supplicant 自带的命令行工具几乎所有带 WiFi 功能的 Linux 系统都会有它不依赖额外的服务。很多精简版嵌入式系统根本不会装 NetworkManager但 wpa_supplicant 基本是标配。第二wpa_cli 支持交互模式和非交互模式用 Qt 的 QProcess 调用非常顺手一条命令一个结果不用处理复杂的 DBus 类型。第三它输出格式简单扫描结果和状态信息都是纯文本解析难度低很容易转成 Qt 的数据结构。NetworkManager 的方案更适合桌面发行版或者需要同时管理有线、无线、移动网络等多种连接的场景。如果你的设备系统已经跑着 NetworkManager那直接用 nmcli 也完全可以核心思路一样只是命令参数和输出格式不同。别两种方案混着用容易把网络配置搞乱。1.3 UI 架构设计列表 弹窗 软键盘UI 层我建议用这样的结构界面主区域是 WiFi 列表平常用 QListWidget 或 QListView Model 都行。列表项要展示的信息包括 WiFi 名称、信号格数、加密锁图标、已连接标记。点击某一项后如果这个网络是加密的弹出密码输入框如果之前连接过可以直接尝试连接。密码输入框不要单独做一页用一个 QDialog 或 QWidget 弹窗承载就好。弹窗里有密码输入框、连接/取消按钮。关键点是软键盘的集成密码输入框获得焦点时自动弹出软键盘失去焦点时自动隐藏。这个交互看起来简单实际处理不好会有很多细节问题比如键盘遮挡输入框、无物理键盘环境下无法输入等后面我会单独讲。列表刷新策略也很重要扫描操作本身有耗时不能让 UI 卡住。我会把扫描命令放到一个后台线程或者用 QProcess 的异步方式执行扫描完成后用信号把结果发回主线程。2. WiFi 扫描、解析与列表显示2.1 用 QProcess 执行扫描命令WiFi 扫描的第一步是先确认无线网卡处于启用状态。这边用wlan0举例实际网卡名以设备为准有的板子叫wlan1或者mlan0可以用iw dev查看。启用网卡并触发扫描的命令是ip link set wlan0 up wpa_cli -i wlan0 scan注意scan命令只是触发一次扫描扫描过程是异步的命令执行完立刻返回但此时扫描可能还没结束。因此需要一个延时再调用scan_results获取结果。在 Qt 里我会这样封装void WifiManager::startScan() { QProcess *ipLinkProcess new QProcess(this); ipLinkProcess-start(ip, {link, set, m_iface, up}); connect(ipLinkProcess, QOverloadint, QProcess::ExitStatus::of(QProcess::finished), this, [this](int exitCode, QProcess::ExitStatus status) { Q_UNUSED(status); if (exitCode ! 0) { emit scanError(tr(网卡启用失败请检查驱动)); return; } QProcess *scanProcess new QProcess(this); scanProcess-start(wpa_cli, {-i, m_iface, scan}); connect(scanProcess, QProcess::finished, this, [this] { QTimer::singleShot(1200, this, [this] { fetchScanResults(); }); }); }); }这里的 1200ms 延时不是固定的实测下来不同网卡差异较大有些 USB 网卡需要 3 秒才能扫到比较全的结果板载网卡会快一些。如果想做得健壮可以用轮询的方式连续调几次scan_results直到结果列表稳定或者直接扫描三次取最后一次。这个经验很重要。2.2 scan_results 输出格式解析wpa_cli -i wlan0 scan_results的输出格式是这样的bssid / frequency / signal level / flags / ssid 00:11:22:33:44:55 2412 -45 [WPA2-PSK-CCMP] MyWifi aa:bb:cc:dd:ee:ff 2437 -60 [ESS] OpenWifi第一行是表头需要注意。信号强度是负数单位是 dBm数值越大代表信号越强比如 -40 比 -70 好。flags 字段表示加密方式[ESS]一般是开放网络包含WPA、WPA2、WEP这些关键词的都是加密网络。解析时我会先把整段输出按行拆分跳过头行再按空格切分。但这里有个坑SSID 里如果有空格按空格切就会出错。我给出的建议是先取前四列剩下的部分是 SSID。用 QString 的 section 函数很好处理示例代码如下struct WifiInfo { QString ssid; QString bssid; int signalLevel; bool isEncrypted; bool isConnected; }; QListWifiInfo WifiManager::parseScanResults(const QString raw) { QListWifiInfo result; QStringList lines raw.split(\n, Qt::SkipEmptyParts); for (const QString line : lines) { if (line.startsWith(bssid) || line.trimmed().isEmpty()) { continue; } QStringList parts line.split( ); if (parts.size() 5) { continue; } WifiInfo info; info.bssid parts.at(0); info.signalLevel parts.at(2).toInt(); QString flags parts.at(3); info.isEncrypted flags.contains(WPA) || flags.contains(WEP); QStringList ssidParts parts.mid(4); info.ssid ssidParts.join( ); result.append(info); } return result; }SSID 为空的情况也遇到过这类是隐藏网络或设备不支持广播 SSID 的路由器扫描结果里 ssid 是空字符串。这类条目在展示时建议显示“未知网络”或“隐藏网络”并且连接逻辑要特殊处理后面再聊。2.3 信号强度转格数与列表刷新信号强度是 dBm 值如果要显示成格数需要做一个映射。工程上常见的映射关系是dBm 范围格数 -504 格 -603 格 -702 格 -801 格 -800 格这个映射可以在代码里用一个函数封装但每个设备的无线网卡灵敏度不同我实际调过一批设备后发现 -72 时有些网卡已经很弱有些还能稳定连接。建议先在目标硬件上实测一轮再根据实际效果微调阈值。列表展示我用的是 QListWidget每个列表项用 setItemWidget 塞进一个自定义 widget这样布局更灵活可以放 QLabel 显示 WiFi 图标和名称再用 QLabel 显示信号格或加密锁图标。刷新列表时注意不要直接 clear() 再重建那样界面会闪烁也会打断用户正在进行的操作。更优雅的做法是比较新旧列表保留未变化的项只更新有变化的部分。当然如果项目时间紧直接重建也不是不能用我就这么干过。另外要注意扫描结果可能会重复同一个 BSSID 可能在结果里出现多次但不同 SSID 就算同名也可能是不同的 AP我一般以 SSID 去重取信号最强的那条。企业级网络如果允许多个物理 AP 同一 SSID这种去重方式是合理的。3. 连接流程、密码输入与软键盘集成3.1 连接加密网络与开放网络的流程拿到用户输入的信息之后Qt 侧要做的就是通过 wpa_cli 把网络配置发给 wpa_supplicant。开放网络和加密网络流程略有不同先看开放网络wpa_cli -i wlan0 add_network wpa_cli -i wlan0 set_network 0 ssid MyWifi wpa_cli -i wlan0 set_network 0 key_mgmt NONE wpa_cli -i wlan0 enable_network 0 wpa_cli -i wlan0 select_network 0这里add_network返回的是新网络的编号以后所有操作都要用这个编号。我用 QProcess 执行命令时会把返回的编号保存起来后续 disable、remove 都会用到。注意add_network返回的编号可能不是从 0 开始如果之前有残留配置编号会递增。加密网络多一个设置密码的环节wpa_cli -i wlan0 add_network wpa_cli -i wlan0 set_network 0 ssid MyWifi wpa_cli -i wlan0 set_network 0 psk mypassword wpa_cli -i wlan0 enable_network 0 wpa_cli -i wlan0 select_network 0PSK 模式最常见的坑是密码长度WPA/WPA2-PSK 的密码必须是 8 到 63 个 ASCII 字符。如果用户输入少于 8 位那就没法建立 WPA 连接。我在 UI 层会直接对密码长度做校验少于 8 位就提示用户密码过短而不是让用户等到连接失败了才懵圈。此外SSID 或密码里如果包含空格、中文等特殊字符直接用引号也不是绝对安全。最稳妥的办法是把 SSID 和 PSK 转成十六进制字符串再传wpa_supplicant 同样支持十六进制输入。Qt 里可以用QByteArray::toHex()实现设置命令写成这样wpa_cli -i wlan0 set_network 0 ssid 4d7957696669 wpa_cli -i wlan0 set_network 0 psk 6d7970617373776f7264四字节十六进制其实就是字符串的 ASCII 码不用加引号。这个方法能避免大部分转义问题强烈建议用。3.2 连接状态反馈与超时处理连接命令执行完不代表 WiFi 已经连上wpa_supplicant 还需要跟 AP 做四次握手一般需要几秒到十几秒。因此需要轮询wpa_cli -i wlan0 statusbssid00:11:22:33:44:55 ssidMyWifi wpa_stateCOMPLETED ip_address192.168.1.100关注wpa_state字段状态含义基本可以对应如下wpa_state 值含义后续处理SCANNING正在扫描继续等待ASSOCIATING关联 AP 中继续等待ASSOCIATED已关联但未认证继续等待4WAY_HANDSHAKE四次握手阶段等待结果COMPLETED连接成功通知 UI 更新DISCONNECTED断开或连接失败提示用户检查密码我封装了一个 WifiManager::connectToNetwork 方法内部用 QTimer 每 800ms 查一次状态最多查 15 次超过时间就判定超时并取消连接。轮询到 COMPLETED 后还要继续查询 IP 地址因为有时候认证通过了但 DHCP 还没拿到 IP此时也不能算完全可用。等ip_address非空后再向用户显示“已连接”体验会好很多。3.3 软键盘的几种实现方式软键盘是触摸屏场景的核心痛点桌面开发时可以完全忽略这个问题但在触摸屏设备上没有物理键盘软键盘直接决定功能是否可用。我梳理过三种方案。第一种是 Qt 自带的 Qt Virtual Keyboardqmake 项目里加上QT virtualkeyboard运行前设置环境变量QT_IM_MODULEqtvirtualkeyboard然后普通 QLineEdit 得到焦点时就会自动弹出虚拟键盘。优点是无缝集成界面风格统一缺点是嵌入式编译时需要额外编译 qtvirtualkeyboard 模块而且中英文切换的配置也有一点门槛。第二种是外部软键盘程序嵌入式 Linux 常见的有 matchbox-keyboard通过 QProcess 在密码输入框获得焦点时启动失去焦点时杀掉进程。优点是实现简单不依赖 Qt 模块系统里有就能用缺点是键盘样式无法和 Qt 风格完全统一弹出和隐藏的动画效果也比较生硬。第三种是自绘软键盘用 QWidget 手动画一个键盘面板每按一个按钮就往当前聚焦的输入框里插入字符就像做一个自定义输入组件。优点是可控性最强可以做到和界面风格完全一致还可以定制按键布局缺点是工作量大除了字母数字键还要处理大小写、退格、回车等逻辑。我最终用的是第一种加第三种结合常规密码输入用 Qt Virtual Keyboard特殊功能按键比如调试输入端口号、IP 地址用自绘的小键盘。不过这篇文章重点是讲清楚主流做法所以下面以最常见的 Qt Virtual Keyboard 为主。3.4 软键盘弹出与遮挡问题的处理Qt Virtual Keyboard 默认会检测输入框焦点自动弹出和隐藏但有几个细节必须处理。第一是确保输入框支持输入法。在 Qt5 里要对 QLineEdit 调用setAttribute(Qt::WA_InputMethodEnabled, true)或者在代码里通过输入法相关属性设置。有时候键盘不弹就是这个细节没注意。第二是设置环境变量启动程序时需要包含export QT_IM_MODULEqtvirtualkeyboard这里的执行顺序有讲究必须在 QApplication 实例创建前设置否则不会生效。第三是布局的时候要给键盘留出空间或者监听键盘的高度变化动态调整密码框的位置。这招很实用因为屏幕就那么点大键盘弹出来必然遮挡 UI。Qt Virtual Keyboard 本身有位置控制接口但最简单的办法是弹窗里的密码输入框放在上半部分软键盘从底部顶上来后刚好在输入框下方就不会被挡住。如果软键盘弹窗和输入框重叠了务必要处理滚动或上移逻辑。对触摸屏设备来说用户看不见自己输入的密码体验会很糟糕也容易被抱怨“这个板子是不是坏了”。3.5 软键盘上的“连接”动作还有个容易被忽略的点软键盘上有回车键用户在输入密码后很可能直接按回车而不是去点屏幕上的“连接”按钮。所以在密码输入框上要对 returnPressed 信号做处理按下回车就直接触发连接逻辑这样可以少一次手指点击交互效率提升很大。ui-passwordEdit-setFocus(); m_wifiManager-setCurrentSsid(selectedSsid); // 连接动作 connect(ui-passwordEdit, QLineEdit::returnPressed, this, MainWindow::onConnectButtonClicked);这里注意 setFocus 要在窗口显示出来后调用否则焦点设置会失效键盘也就弹不出来。4. 常见问题与排查技巧实录4.1 扫描不到 WiFi 或者列表一直为空这个问题我调试时碰到过很多次原因大概率是网卡没启用。很多定制系统启动后无线网卡默认是 down 状态。解决方法是先执行ip link set wlan0 up然后查看iw dev确认无线网卡有没有注册成功。还有一种情况是 wpa_supplicant 服务没起来此时执行wpa_cli -i wlan0 scan会提示Failed to connect to non-global ctrl_ifname需要在启动脚本里加上wpa_supplicant -B -i wlan0 -c /etc/wpa_supplicant.conf。扫描结果为空还有一个原因扫描触发后就立刻去读结果。wpa_cli 的 scan 命令只是告诉驱动开始扫描实际扫描过程可能持续数百毫秒到数秒不等。我的做法是扫描之后间隔 1 到 3 秒再读结果最好连续读两次如果第二次能拿到数据就用第二次稳定性最好。4.2 连接不上密码是对的如果密码明明正确但连不上先检查wpa_cli -i wlan0 status卡在哪个状态。如果一直停在4WAY_HANDSHAKE大概率是网卡驱动对 WPA2 某些加密算法的兼容问题可以尝试在 wpa_supplicant.conf 里指定pairwiseCCMP或groupCCMP强制使用 CCMP 算法。如果卡在ASSOCIATED之后又跳回DISCONNECTED最可能是信道或频段不匹配可以确认 AP 是 2.4G 还是 5G对应调整网卡工作频段。另外一些老旧的 USB WiFi 网卡只支持 2.4G你扫描时能看到 5G 信号但连接时可能失败。这个属于硬件限制只能提示用户切换到 2.4G 频段。4.3 软键盘弹不出来或输入不了中文先检查环境变量有没有生效echo $QT_IM_MODULE确认一下Qt5 下如果没设置默认加载不到虚拟键盘。其次检查输入框的焦点策略setFocusPolicy(Qt::StrongFocus)会好一些。如果使用的是 Qt Virtual Keyboard在编译时还会有插件路径问题运行时提示找不到插件可以通过QT_PLUGIN_PATH把插件目录指到实际安装位置。中文输入需要启用 hunspell 和语言包嵌入式裁剪过的 Qt 库可能没有这些所以很多设备软键盘只能输英文数字。如果产品必须支持中文 WiFi 名输入建议自绘软键盘直接处理中文字符集这条路最省心。4.4 连接状态刷新不及时连接成功后界面上要立刻显示勾选标记或“已连接”这个状态我建议单独加一个轮询定时器比如每 3 秒查一次 wpa_cli status更新界面上的连接状态标签。不需要每次都重新扫描重新扫描很耗时间而且会让网络短暂中断。有些网卡在扫描时会暂时断开当前连接这点特别坑所以连接成功后我只查状态不主动触发 scan。4.5 常用问题速查现象可能原因排查建议scan 提示 Failed to connectwpa_supplicant 未启动或控制接口不对检查进程和 ctrl_interface 配置扫描结果为空网卡未启用、扫描后读太快先 ip link set up再延时读取卡在 4WAY_HANDSHAKE密码错误或算法兼容问题确认密码强制指定 CCMP一直 DHCP 中DHCP 客户端未安装或服务异常改用 udhcpc 调试软键盘不弹QT_IM_MODULE 没设置检查环境变量和插件路径连接后立刻断5G/2.4G 频段不匹配确认 AP 频段与网卡能力5. 从方案落地到产品化的一些经验总结这套基于 Qt wpa_cli 的方案我已经在好几款设备上跑过包括车机、工控一体机和评估板整体稳定性还是比较靠谱的。它的核心价值在于把“底层无线管理”和“上层 UI 交互”拆开底层用成熟的 wpa_supplicant 处理协议细节上层 Qt 只负责展示和交互出问题时有非常清晰的排查路径。整个项目做下来我最大的体会是遇到网络功能一定要先从命令行把流程调通再动 Qt 代码。用 wpa_cli 手动执行一遍扫描、连接、查询状态确认当前硬件和系统环境本来就是好的再开始封装代码会省掉大量无意义的调试时间。尤其是换了一台新设备或者新网卡先看看命令行能不能扫到信号这比反复看 Qt 代码高效得多。再分享一个在实际操作中很有用的细节所有网络操作都要做成异步的因为 wpa_cli 的命令有时会阻塞尤其 scan 和 connect如果直接同步执行界面会卡住。Qt 里我统一用 QProcess 异步方式配合信号槽或 lambda 处理结果界面始终保持流畅。另外别忘了在应用退出时把 connect 状态的定时器和正在进行中的 QProcess 清理干净否则设备断电前可能留下残留进程下次启动会出现控制接口被占用的怪问题。如果你接下来还要做更高级的功能比如让设备自己开热点、支持 WPS 一键连接、或者做 WiFi 信号质量监测这套 WifiManager 的结构同样可以扩展。核心就是把命令封装和业务状态机做好后面的路就顺了。本文还有配套的精品资源点击获取