企业官网建设流程全解析

• 驱动开发
• 嵌入式
• 网络

本文围绕 rtl8188eu 独立驱动仓库的 README 文档展开，系统讲解该 RTL8188EU USB 无线网卡独立驱动从获取源码、内核模块编译到安装部署的完整流程，并结合仓库源码说明固件加载、WEXT 依赖等底层机制；同时覆盖两个高频故障场景（Network Manager 提示 "Device is not ready"、NetworkManager 扫描不到 SSID）的根因分析与可复制的解决方案。读完后，你可以独立完成该驱动的构建、安装，并能自主定位驱动无法联网的常见原因。

1. 项目定位与适用前提

rtl8188eu 仓库是 Realtek RTL8188EU USB Wi-Fi 芯片的独立（stand-alone）Linux 内核驱动，源码版本标识见 include/rtw_version.h 中的DRIVERVERSION "v4.1.4_6773.20130222"，DKMS 打包版本为 4.1.4（见 dkms.conf）。它与 Linux 内核树中内置的 r8188eu 驱动并存，用户安装本驱动后，Makefile 的安装目标会自动将内核自带驱动加入黑名单（blacklist r8188eu），确保系统加载本仓库编译出的 8188eu 模块。

使用本驱动前必须满足以下前提，这也是 README "IMPORTANT - PLEASE READ" 部分的核心要求：

1. 必须以 git 方式获取源码：自 2019 年 11 月起，作者不再支持以 zip 压缩包形式下载源码的用户。这一约束直接体现在 Makefile 的all: test modules规则中——test目标会在编译前检查./.git是否存在，若不存在则输出提示并直接exit 1，阻止构建：

   MSG="Directory .git does not exist indicating that you downloaded the source as a zip file. Only the 'git clone' method is now supported." all: test modules test: @if [ ! -e ./.git ] ; then echo $(MSG); exit 1; fi;

   这样设计的原因是 git 只需拉取增量变更，构建失败时git pull重试即可获取修复；zip 用户则需要重新下载整份源码。

2. 必须安装与当前运行内核匹配的内核头文件：编译时 KBuild 会在/lib/modules/$(KVER)/build下寻找内核构建系统，其中KVER默认为uname -r。若该目录不存在，说明内核头文件未安装、安装不正确，或所装头文件与当前运行的内核版本不一致。具体安装步骤因发行版而异（Debian/Ubuntu 一般为linux-headers-$(uname -r)，Debian 打包的rtl8188eu-dkms包在 debian/control 的 Description 中也明确提示需手动安装linux-headers-<your architecture>包）。

3. 内核配置必须启用CONFIG_WIRELESS_EXT：这是硬性要求。从源码结构看，该驱动的扫描等 ioctl 功能走的是 Wireless Extensions（WEXT）私有无线路径，例如 os_dep/ioctl_linux.c 中定义了WEXT_CSCAN_HEADER "CSCAN S\x01\x00\x00S\x00"等私有扫描命令的解析逻辑，并通过wireless_send_command通道处理。若内核未开启 WEXT，驱动的关键无线功能将无法正常工作，因此 README 将其列为必须项。

4. 需要 make 与编译器：作为 out-of-tree 内核模块，编译依赖宿主机上的 make、C 编译器工具链。

1.1 支持的设备

驱动通过 USB 设备 ID 表匹配硬件，定义在 os_dep/usb_intf.c 的rtw_usb_id_tbl[]中。除 Realtek 官方 VID0x0bda下的 8188EUS（0x8179）、8188ETV（0x0179）、8188FU（0xf179）外，还包含 Abocom、Sitecom N150 v2、D-Link DWA-125/DWA-123/DWA-121、Elecom、TP-Link TL-WN722N v2 / TL-WN727N v5.21、MERCUSYS MW150US v2、ASUS USB-N10 Nano B1、Edimax EW-7811Un V2 等厂商客户 ID。若你的网卡是 RTL8188EU 芯片但 ID 不在此表中，可以推断它不会被自动 probe（表中留有空位以便扩展，仓库为只读，修改需在自己的源码副本中进行）。

2. 编译：make all

README 给出的编译命令是：

make all

结合 Makefile 的实际规则，all展开为test（git 检查）+modules，后者将构建工作委托给内核 KBuild 系统：

modules: $(MAKE) ARCH=$(ARCH) CROSS_COMPILE=$(CROSS_COMPILE) -C $(KSRC) M=$(shell pwd) modules

其中几个关键变量的默认取值与覆盖方式值得注意：

编译宏方面，Makefile 统一追加了-O1与一组-Wno-unused-*、-Wno-uninitialized抑制警告，并注入-D__CHECK_ENDIAN__与 include 目录。最终产物为8188eu.ko，如需瘦身可执行make strip（对 ko 执行strip --strip-unneeded）。

模块的源码组成在 Makefile 中一目了然，分为三层：

• core/（协议栈与功能层）：rtw_ap.o、rtw_mlme.o、rtw_mlme_ext.o、rtw_xmit.o、rtw_recv.o、rtw_security.o、rtw_p2p.o、rtw_pwrctrl.o等 20 个目标文件；
• hal/（硬件抽象层）：寄存器/固件图像（HalHWImg8188E_MAC.o、HalHWImg8188E_RF.o）、PHY 与 RF（HalPhyRf_8188e.o、rtl8188e_rf6052.o）、动态调度（rtl8188e_dm.o）、ODM 硬件配置（odm_*.o）以及 USB 传输（usb_halinit.o、usb_ops_linux.o）；
• os_dep/（Linux 适配层）：ioctl_linux.o、mlme_linux.o、recv_linux.o、xmit_linux.o、usb_intf.o、osdep_service.o等。

三者按8188eu-y +=顺序链接进8188eu.o，对应 out-of-tree 模块的典型分层结构。

3. 安装：sudo make install

README 的安装命令：

sudo make install

Makefile 的install目标实际执行了五个动作，逐条理解有助于排查安装后"驱动没生效"的问题：

install: @mkdir -p $(MODDESTDIR) install -p -m 644 8188eu.ko $(MODDESTDIR) @if [ -a /lib/modules/$(KVER)/kernel/drivers/staging/rtl8188eu/r8188eu.ko ] ; then modprobe -r r8188eu; fi; @echo "blacklist r8188eu" > /etc/modprobe.d/50-8188eu.conf /sbin/depmod -a ${KVER} @mkdir -p /lib/firmware/rtlwifi cp rtl8188eufw.bin /lib/firmware/rtlwifi/.

1. 将8188eu.ko安装到/lib/modules/$(KVER)/kernel/drivers/staging/r8188eu/；
2. 若发现内核自带r8188eu模块已加载，则先modprobe -r r8188eu卸载；
3. 写入/etc/modprobe.d/50-8188eu.conf黑名单，防止内核自带驱动抢占设备；
4. 执行depmod -a刷新模块依赖；
5. 将固件rtl8188eufw.bin复制到/lib/firmware/rtlwifi/——这一步直接对应 FAQ 中 "Device is not ready" 的解决方案（见第 4.1 节）。

对应的卸载目标是make uninstall（删除 ko、重建 depmod、移除黑名单文件）。此外仓库还提供 DKMS 集成方式：dkms.conf 声明了PACKAGE_NAME="rtl8188eu"、PACKAGE_VERSION="4.1.4"、BUILT_MODULE_NAME[0]="8188eu"、DEST_MODULE_LOCATION[0]="/updates/dkms"与AUTOINSTALL="YES"，debian/rules 通过dh --with dkms构建rtl8188eu-dkms包，将源码（含.git目录——正是 Makefile 的 git 检查所要求的）安装到/usr/src/8188eu-<version>。使用 DKMS 后，内核升级时可自动重新编译该驱动，适合需要长期维护多内核环境的用户。

4. 常见故障排查（README FAQ 详解）

4.1 Network Manager 提示 "Device is not ready"

README 给出的诊断：确认固件rtl8188eufw.bin已复制到/lib/firmware/rtlwifi/。

这一判断有明确的源码依据。驱动在硬件初始化阶段通过标准 Linux 固件机制加载固件文件，见 hal/rtl8188e_hal_init.c 的load_firmware()：

static int load_firmware(struct rt_firmware *pFirmware, struct device *device) { const char *fw_name = "rtlwifi/rtl8188eufw.bin"; int err = request_firmware(&fw, fw_name, device); if (err) { pr_err("Request firmware failed with error 0x%x\n", err); rtStatus = _FAIL; goto Exit; } ... }

request_firmware()会在固件搜索路径（含/lib/firmware/rtlwifi/）中查找rtl8188eufw.bin；找不到时初始化失败并打印 "Request firmware failed"，设备自然处于不可用状态，Network Manager 便显示 "Device is not ready"。由于make install已自动执行固件复制，该问题主要出现在：手动编译后未执行完整 install、固件被误删、或自定义了固件搜索路径的场景。处理办法就是执行：

sudo cp rtl8188eufw.bin /lib/firmware/rtlwifi/

然后重新插拔网卡或重载模块（modprobe -r 8188eu && modprobe 8188eu）。

4.2 NetworkManager 扫描不到 SSID

README 给出的诊断是：NetworkManager 默认启用wifi.scan-rand-mac-address，即每次扫描时随机更改 Wi-Fi MAC 地址以提升隐私；而 RTL8188EU 驱动不支持该特性，导致扫描结果异常或 SSID 列表为空。

解决方案（README 原文）：创建/etc/NetworkManager/conf.d/80-wifi.conf，内容为：

[device] wifi.scan-rand-mac-address=no

然后执行：

systemctl restart NetworkManager

关闭随机 MAC 后，NetworkManager 将使用网卡真实 MAC 发起扫描，SS 列表即可正常显示。该配置对使用本驱动的其它网络管理器场景同样适用——凡依赖"扫描换 MAC"特性的功能（随机 MAC 隐私）在本驱动上均应关闭。

4.3 构建回归故障的排查顺序

README 还给出了一条重要的问题处理准则：如果之前能构建成功的驱动现在构建失败，先执行git pull重试，再考虑报告问题。作者同时声明：向 GitHub 报告/lib/modules/.../build不存在一类问题的 issue 通常无果，因为这是用户侧内核头文件安装问题（见第 1 节前提条件）。这一流程建议本质上是要求用户在报告构建问题前，先排除"本地源码过旧"与"头文件环境错误"两类最常见原因。

5. 延伸能力：AP 模式（Soft AP）

在正确完成编译安装之外，本仓库附带了把 RTL8188EU 用作软 AP 的完整能力，可作为验证驱动是否工作正常的进阶手段：

• hostapd-2.9/ 目录内置了 hostapd 2.9 用户态程序及其驱动适配层（hostapd-2.9/src/drivers/driver_rtw.c，即 Makefile 中引用的rtl871xdrv驱动接口）；
• control_ap 是一个 start/stop 管理脚本，用法为control_ap start <AP_iface> <NET_iface>与control_ap stop。它会自动完成：iptables MASQUERADE 与 FORWARD 规则配置、AP 接口 IP 设置（默认192.168.0.1）、生成dhcpd.conf并拉起 DHCP 服务（地址池192.168.0.200-229）、生成 hostapd 配置文件（SSID 默认rtwap、通道 11、WPA-PSK），最后后台启动 hostapd；
• 根目录的 rtl_hostapd.conf 则是一份带详细注释的独立 hostapd 配置示例，展示了接口名（interface=）、SSID、wpa=2（WPA2）、wpa_passphrase、driver=rtl871xdrv、hw_mode=g，以及完整的 WPS 参数（wps_state=2、uuid、manufacturer、device_type等）与 HT 能力设置（ieee80211n=1、ht_capab=[SHORT-GI-20][SHORT-GI-40]）。

修改 SSID、密码或通道时，直接编辑脚本中的AP_SSID、WPA_SECRET、AP_CHANNEL变量或rtl_hostapd.conf中对应字段即可（在本地环境中修改，不影响本仓库）。

6. 操作速查表

适用前提与限制小结

• 内核必须配置CONFIG_WIRELESS_EXT=y，且必须安装与运行内核匹配的头文件；
• 源码必须是 git 仓库，make all会硬校验.git目录；
• 固件必须位于固件搜索路径（安装目标为/lib/firmware/rtlwifi/）；
• 设备 ID 需匹配 os_dep/usb_intf.c 中rtw_usb_id_tbl[]所列型号；
• 使用 DKMS 方式（rtl8188eu-dkms包）可获得内核升级自动重建能力，其源码同样以 git 仓库形式安装到/usr/src/8188eu-<version>。

按照以上流程完成编译、安装与固件部署后，配合第 4 节的故障排查路径，即可覆盖该驱动在桌面 Linux 环境下绝大多数"装不上、连不上"的典型问题。

• 驱动开发
• 嵌入式
• 网络