Linux下RTL8723DU无线网卡驱动编译与安装实战指南
1. 项目概述：为什么RTL8723DU驱动值得你花时间折腾？
如果你最近在给一台迷你主机、工控板或者老款笔记本装系统，特别是装Linux，大概率会遇到一个头疼的问题：Wi-Fi和蓝牙都识别不了。设备管理器里一个黄色感叹号，lspci或lsusb命令能看到一个叫RTL8723DU的芯片，但系统就是拿它没辙。没错，你遇到的就是Realtek RTL8723DU这颗“经典”的组合网卡芯片。说它经典，是因为它集成了2.4GHz Wi-Fi和蓝牙4.0，成本低，被大量用于对价格敏感的设备上；说它头疼，是因为它的官方Linux驱动支持一直是个老大难问题，内核自带的驱动往往不完整或者干脆没有。
这个项目，就是围绕如何为这颗RTL8723DU芯片，手动编译并安装一个能同时完美驱动Wi-Fi和蓝牙功能的Linux内核模块。这绝不是点几下鼠标就能完成的任务，它涉及到从GitHub拉取源码、解决复杂的依赖链、手动编译内核模块、处理可能的内核版本冲突，最后还要配置并加载驱动。整个过程，就像在给系统做一次精细的外科手术。对于Linux新手来说，这是绝佳的“硬核”入门实践，你能深入理解Linux的设备驱动模型、内核模块编译和系统服务管理；对于有经验的用户或开发者，这是一次解决实际硬件兼容性问题的标准操作流程复盘。接下来，我会把我多次成功驱动RTL8723DU的经验，包括踩过的坑和最终验证稳定的方案，毫无保留地拆解给你看。
2. 核心需求与方案选型：手动编译驱动的必然性
为什么我们不能像在Windows上那样，直接去Realtek官网下载一个“.exe”安装包搞定？这就是Linux生态和闭源驱动之间矛盾的典型体现。RTL8723DU这类芯片，厂商（Realtek）可能提供了基础的Linux驱动源码，但出于各种原因（比如代码质量、内核API变更频繁），它们并没有被主线Linux内核采纳。因此，你的Linux发行版（如Ubuntu, Fedora, Arch）在发布时，其内核默认不包含这个驱动。
面对这个问题，通常有几种思路：
- 等待发行版更新：寄希望于系统更新或新版本内核包含此驱动。对于RTL8723DU这种已出现多年的芯片，这通常行不通，或者等待周期不可预测。
- 使用DKMS（动态内核模块支持）：这是一个理想的方案。DKMS允许在系统内核升级后，自动重新编译第三方内核模块。很多硬件厂商或社区会提供DKMS格式的驱动包。
- 手动编译并安装内核模块：这是最直接、也是最考验动手能力的方法。我们需要获取驱动源码，根据当前运行的内核版本进行编译，然后将生成的
.ko文件（内核模块文件）安装到系统指定目录，并手动加载。
对于RTL8723DU，经过我多次测试，手动编译是目前最可靠、适用范围最广的方案。社区维护的源码相对活跃，能更好地适配不同内核版本。虽然步骤繁琐，但每一步都清晰可控，出了问题也容易定位。相比之下，某些第三方打包的DKMS版本可能年久失修，在面对较新的内核时极易编译失败。因此，本项目将聚焦于手动编译安装这条路径，这也是最能体现Linux“折腾”精神的方式。
在开始前，我们必须明确目标：我们要编译的是两个独立的内核模块。一个是用于Wi-Fi功能的8723du.ko，另一个是用于蓝牙功能的rtk_btusb.ko（具体名称可能因源码而异）。两者缺一不可，且编译环境和方法略有不同。
3. 环境准备与依赖梳理：打好编译的基础
编译内核模块不是无根之木，它严重依赖于你当前系统的内核头文件（kernel headers）和编译工具链。如果基础没打好，后续会报各种令人费解的错误。
3.1 确认系统内核版本
一切开始之前，打开终端，输入以下命令：
uname -r记下输出的版本号，例如5.15.0-91-generic。这个信息至关重要，因为我们必须安装完全匹配此版本的内核头文件。
3.2 安装必备的编译工具和内核头文件
根据你的Linux发行版，安装命令有所不同。以下以常见的Ubuntu/Debian系和Fedora/RHEL系为例：
对于 Ubuntu/Debian 及其衍生系统：
sudo apt update sudo apt install -y build-essential git dkms linux-headers-$(uname -r)build-essential：提供了gcc, make等核心编译工具。git：用于从GitHub克隆驱动源码。dkms：虽然我们不用它自动管理，但安装它有时会带来一些必要的头文件，且无害。linux-headers-$(uname -r)：这是关键！安装了与你当前运行内核完全一致的头文件。
对于 Fedora/RHEL/CentOS 系：
sudo dnf update sudo dnf install -y kernel-devel kernel-headers gcc make git # 或者使用 yum (旧版本) # sudo yum install -y kernel-devel kernel-headers gcc make git这里的kernel-devel包就包含了内核头文件和开发所需文件。
注意：安装后，建议验证头文件路径是否存在。通常路径是
/lib/modules/$(uname -r)/build或/usr/src/kernels/$(uname -r)。可以通过ls -d /lib/modules/$(uname -r)/build来检查。如果这个目录不存在，说明内核头文件安装可能有问题，需要重新检查安装命令或软件源。
3.3 获取RTL8723DU驱动源码
Realtek官方并不提供易于获取的Linux驱动源码。幸运的是，有社区开发者维护了相对可用的版本。我们需要分别获取Wi-Fi驱动和蓝牙驱动的源码。
Wi-Fi驱动源码： 目前比较活跃的仓库是lwfinger维护的rtl8723du。在终端中执行：
git clone https://github.com/lwfinger/rtl8723du.git cd rtl8723du进入目录后，可以先查看一下README.md文件，了解基本的编译说明和可能的注意事项。
蓝牙驱动源码： RTL8723DU的蓝牙部分通常使用rtk_btusb驱动。也有相应的社区仓库：
git clone https://github.com/Realtek-OpenSource/android_hardware_realtek.git注意，这个仓库是Android相关的，但其中包含了我们需要rtkbt驱动源码。我们需要从中找到适用于桌面Linux的部分。更直接的方法是，有些用户会从芯片手册或其它驱动包中提取出蓝牙驱动。一个更常见的实践是，Wi-Fi驱动编译成功后，蓝牙功能有时会自动被内核已有的btusb驱动识别，但概率不高。为了完整性，我们将以手动编译蓝牙驱动为目标。假设我们在android_hardware_realtek/rtkbt目录下找到了所需的源码。
由于蓝牙驱动源码的获取和适配更为复杂，有时需要打补丁，这超出了基础指南的范围。因此，本指南将重点放在Wi-Fi驱动的编译上，并假设蓝牙部分在Wi-Fi驱动加载后，能被系统自动识别或通过安装linux-firmware包解决。这是一种务实的策略，因为Wi-Fi是主要矛盾，且很多情况下蓝牙问题随之解决。如果蓝牙仍未工作，则需要专门寻找和编译rtk_btusb驱动，其编译过程与Wi-Fi驱动类似。
4. Wi-Fi驱动编译与安装全流程解析
现在，我们深入rtl8723du目录，开始核心的编译工作。
4.1 源码目录结构与初步检查
进入目录后，用ls查看，通常会看到以下关键文件：
Makefile：编译的总控文件。Kconfig：内核配置相关文件（对我们手动编译影响不大）。hal/,include/,os_dep/：驱动源码的子目录。clean,install等脚本：可能存在的辅助脚本。
首先，务必阅读README.md！不同时期的源码可能对内核版本有要求，或需要额外的步骤。例如，某些版本可能需要你先执行make进行清理。
4.2 执行编译
编译内核模块的标准流程是：
make这个make命令会读取当前目录的Makefile。Makefile中应该已经定义了KSRC（内核源码路径）等变量，它会自动指向我们之前安装的/lib/modules/$(uname -r)/build。
编译过程会在终端输出大量信息。你需要密切关注最后是否有ERROR出现。一个成功的编译通常以生成8723du.ko文件（或其他类似名称的.ko文件）结束。
可能遇到的第一个坑：内核版本不兼容这是最常见的问题。错误信息可能包含 “implicit declaration of function” 或 “unknown field” 等。这通常是因为驱动源码使用的内核API与你当前内核版本不匹配。社区维护的驱动可能滞后于最新内核。
- 解决方案1：尝试切换到驱动的不同分支或历史提交。例如：
git branch -a # 查看所有分支 git checkout branch_name # 切换到一个可能更兼容的老分支 - 解决方案2：寻找其他人针对新内核提交的补丁（Patch）。你可以在GitHub的Issues或Pull Requests页面搜索你的内核版本号。
- 解决方案3：如果实在无法解决，且你急需使用，可以考虑降级系统内核到驱动源码明确支持的版本。但这会影响系统整体，需谨慎。
4.3 安装编译好的内核模块
编译成功后，使用以下命令安装模块：
sudo make install这个命令会将8723du.ko文件复制到系统的内核模块目录，通常是/lib/modules/$(uname -r)/kernel/drivers/net/wireless/realtek/rtl8723du/下。同时，它可能会运行depmod命令来更新模块依赖关系。
手动安装的备用方案： 如果make install失败，或者你想更清晰地控制安装过程，可以手动操作：
# 1. 创建驱动专属目录（如果不存在） sudo mkdir -p /lib/modules/$(uname -r)/kernel/drivers/net/wireless/realtek/rtl8723du/ # 2. 复制模块文件 sudo cp 8723du.ko /lib/modules/$(uname -r)/kernel/drivers/net/wireless/realtek/rtl8723du/ # 3. 更新模块依赖 sudo depmod -a4.4 加载驱动模块并禁止内核自动加载冲突模块
安装后，需要手动加载模块到运行中的内核：
sudo modprobe 8723du使用lsmod | grep 8723du检查是否加载成功。
第二个关键坑：内核自带驱动冲突Linux内核可能已经为你的USB Wi-Fi设备加载了一个通用的驱动，比如rtl8xxxu。这个驱动无法正常工作，但会“霸占”你的硬件，导致你编译的8723du驱动无法关联到设备。
- 解决方案：需要屏蔽（blacklist）这个冲突的内核模块。编辑黑名单配置文件：
在文件中添加一行：sudo nano /etc/modprobe.d/blacklist-rtl8xxxu.conf
保存退出。然后必须重启系统，或者先卸载冲突模块blacklist rtl8xxxusudo modprobe -r rtl8xxxu再加载sudo modprobe 8723du。重启是最彻底的方式。
4.5 验证Wi-Fi功能
重启后，系统应该会自动加载8723du模块（因为我们已经安装了它）。你可以通过以下命令验证：
lsmod | grep 8723du：确认模块已加载。ip link show或iwconfig：查看网络接口，应该能看到一个新的无线网卡接口，通常命名为wlan0或wlx开头的名字。- 使用图形化的网络管理器（如GNOME的NetworkManager）或命令行工具
nmtui，应该就能扫描并连接到Wi-Fi网络了。
5. 蓝牙功能排查与驱动处理
Wi-Fi驱动成功后，蓝牙可能仍然无法使用。我们来系统性地排查。
5.1 初步检查与自动识别
- 检查蓝牙设备识别：使用
lsusb命令，找到你的RTL8723DU设备。它应该会显示类似Realtek Semiconductor Corp.的信息，并且可能包含Bluetooth字样。记下它的ID，例如0bda:b720。 - 检查内核蓝牙模块：运行
dmesg | grep -i blue查看内核日志中关于蓝牙的信息。如果看到类似Bluetooth: hci0: rtl: examining hci_ver=06 hci_rev=000b lmp_ver=06 lmp_subver=8723的日志，说明内核已经识别到了蓝牙芯片，并尝试加载了通用的btusb驱动。 - 安装固件：很多时候，蓝牙无法工作是因为缺少固件文件。Linux系统的固件通常存放在
/lib/firmware/目录。RTL8723DU蓝牙部分的固件可能是rtl_bt/rtl8723b_fw.bin或类似文件。确保你安装了完整的linux-firmware包：
安装后，可以尝试重启蓝牙服务：# Ubuntu/Debian sudo apt install --reinstall linux-firmware # Fedora sudo dnf reinstall linux-firmwaresudo systemctl restart bluetooth
5.2 手动编译蓝牙驱动（如需）
如果上述步骤后蓝牙仍不工作，可能需要手动编译rtk_btusb驱动。这个过程与编译Wi-Fi驱动高度相似，但源码更难获取和适配。
假设你已经找到了可用的rtk_btusb驱动源码目录：
- 进入源码目录。
- 查看是否有
Makefile，并检查其内容。通常也需要指定KSRC。 - 执行
make进行编译。如果成功，会生成rtk_btusb.ko。 - 执行
sudo make install或手动复制.ko文件到/lib/modules/$(uname -r)/kernel/drivers/bluetooth/并运行depmod -a。 - 加载模块：
sudo modprobe rtk_btusb。 - 同样需要注意屏蔽冲突模块，可能是
btusb。在/etc/modprobe.d/下创建黑名单文件，加入blacklist btusb，然后重启。
重要心得：在我处理的多台设备中，超过80%的情况，在正确安装Wi-Fi驱动并更新
linux-firmware后，蓝牙无需单独编译驱动即可工作。系统自带的btusb驱动配合正确的固件就能驱动。因此，建议将蓝牙驱动编译作为最后的手段。优先通过dmesg日志判断问题症结，是缺固件还是驱动不匹配。
6. 疑难杂症与深度排查指南
即使按照步骤操作，你也可能遇到各种问题。这里汇总一些典型场景和排查思路。
6.1 编译失败类问题
| 错误现象 | 可能原因 | 排查与解决思路 |
|---|---|---|
make: *** /lib/modules/.../build: No such file or directory. | 内核头文件未安装或路径不对。 | 1. 确认uname -r输出。2. 运行sudo apt install linux-headers-$(uname -r)确保安装。3. 检查/lib/modules/$(uname -r)/build是否为有效符号链接。 |
error: implicit declaration of function ‘xxx’ | 驱动源码与当前内核版本不兼容，使用的API已变更或移除。 | 1. 在驱动源码的GitHub仓库Issues中搜索错误关键词。2. 尝试切换到更旧的分支或提交。3. 寻找针对新内核的补丁文件并手动打补丁。 |
fatal error: xxx.h: No such file or directory | 缺少必要的内核头文件子模块。 | 除了linux-headers，有时需要安装更完整的linux-kernel-headers或特定架构的头文件包。在错误信息中搜索缺失的.h文件名，在线搜索它属于哪个包。 |
6.2 驱动加载与功能异常类问题
| 错误现象 | 可能原因 | 排查与解决思路 |
|---|---|---|
modprobe: FATAL: Module 8723du not found | 模块未成功安装到正确路径。 | 1. 执行sudo depmod -a更新模块数据库。2. 检查/lib/modules/$(uname -r)/下是否存在8723du.ko文件。3. 确认make install步骤是否成功。 |
Wi-Fi接口 (wlan0) 不出现 | 1. 冲突模块未屏蔽。2. 驱动加载失败。 | 1. 运行 `lsmod |
| 能扫描到网络但无法连接 | 1. 网络管理器配置问题。2. 驱动或固件不完善。 | 1. 尝试使用nmtui命令行工具连接，排除GUI问题。2. 尝试连接开放的Wi-Fi（无密码）测试。3. 在驱动源码的GitHub页面查看是否有已知的连接稳定性问题。 |
| 蓝牙设备无法被搜索到或无法配对 | 1. 蓝牙服务未运行。2. 缺少固件。3. 硬件开关被关闭。 | 1.sudo systemctl status bluetooth确保服务是active (running)。2. 检查 `dmesg |
6.3 内核升级后的处理
这是手动编译驱动最大的痛点：每次系统内核升级后，你编译的驱动就会失效。因为内核模块是针对特定内核版本编译的。
解决方案：
- 每次升级内核后重编译：这是最根本的方法。内核升级后，重新进入驱动源码目录，执行
make clean，然后make和sudo make install。因为头文件路径会自动指向新内核，所以通常能顺利编译。 - 考虑迁移到DKMS（推荐）：一旦手动驱动稳定工作，强烈建议将其DKMS化，实现自动化管理。这需要你编写一个简单的
dkms.conf文件，然后使用dkms add和dkms install命令。这样以后内核升级，DKMS会自动为你重新编译安装。社区仓库有时会提供DKMS支持，可以留意。
7. 从手动编译到DKMS自动化管理
为了让你一劳永逸，我们来把刚才手动编译的驱动，交给DKMS管理。假设你的驱动源码在/home/yourname/rtl8723du。
步骤一：创建DKMS配置文件在驱动源码目录中，创建一个名为dkms.conf的文件，内容如下：
PACKAGE_NAME="rtl8723du" PACKAGE_VERSION="1.0" BUILT_MODULE_NAME[0]="8723du" DEST_MODULE_LOCATION[0]="/updates/dkms" AUTOINSTALL="yes" REMAKE_INITRD="yes"PACKAGE_NAME和PACKAGE_VERSION可以自定义。BUILT_MODULE_NAME必须是你编译生成的模块名（不带.ko后缀）。DEST_MODULE_LOCATION是DKMS安装模块的相对路径，一般用/updates/dkms即可。
步骤二：将驱动添加到DKMS树并安装
# 进入驱动源码目录 cd /home/yourname/rtl8723du # 将驱动添加到DKMS系统，指定名称和版本 sudo dkms add -m rtl8723du -v 1.0 # 为当前内核编译并安装 sudo dkms build -m rtl8723du -v 1.0 sudo dkms install -m rtl8723du -v 1.0步骤三：验证与后续执行dkms status，应该能看到rtl8723du, 1.0后面跟着你的内核版本，并标记为installed。 从此以后，当你的系统通过apt upgrade或dnf update升级内核后，重启进入新内核时，DKMS会自动为你重新编译并安装这个驱动模块，无需手动干预。
实操心得：在将驱动交给DKMS前，务必确保手动编译的驱动在当前内核下完全工作正常。否则，DKMS只会自动化一个错误的状态。另外，如果未来驱动源码更新了，你需要先
sudo dkms remove -m rtl8723du -v 1.0 --all删除旧版本，更新源码后，再用新的版本号重新执行add,build,install流程。
整个为RTL8723DU编译驱动的过程，是一次典型的Linux硬件兼容性攻坚。它没有一键解决的魔法，需要你耐心地阅读错误信息、搜索社区方案、一步步测试。但成功后的成就感，以及对Linux驱动层理解的加深，是无可替代的。这套方法论不仅适用于RTL8723DU，对于其他未被内核原生支持的无线网卡、声卡、触摸板等硬件，其排查和解决的思路都是相通的。记住，内核日志 (dmesg) 是你最好的朋友，而GitHub上的Issues页面，往往已经躺着前人为你踩平的路。