企业官网建设流程全解析

QMK 固件 Windows 引导加载器驱动安装实战：Zadig 驱动指派、故障恢复与卸载全解

【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware

在 Windows 上为 QMK 键盘刷写固件，最常见的一道坎不是编译，而是驱动：QMK 固件本身以标准 HID 键盘身份工作、无需任何驱动，但按下QK_BOOT或复位键后进入的引导加载器（bootloader）设备往往需要手动指派正确驱动，刷写工具（如 QMK Toolbox /avrdude/dfu-util）才能与它通信。本文以仓库文档docs/driver_installation_zadig.md为主体，完整覆盖驱动安装的实操步骤、已知 bootloader 的 VID/PID 与驱动对照表、误装驱动的恢复流程，以及通过pnputil卸载驱动的进阶操作，并结合 QMK 源码中的 bootloader 实现印证每种引导加载器与对应驱动的关系。

为什么键盘本身不需要驱动，bootloader 却需要

QMK 向主机呈现为一个普通的 HID 键盘设备，因此系统自带驱动即可输入，不需要额外安装任何东西。但在刷写固件时情况不同：当你把板子复位进入 bootloader 后，USB 总线上出现的是一个 DFU（Device Firmware Upgrade）或专用的编程设备，Windows 默认可能为其挂上错误的驱动（或没有合适的驱动），导致刷写工具无法访问该设备。

原文档特别指出两个不需要手动装驱动的例外：

• Caterina（常见于 SparkFun Pro Micro）：进入 bootloader 后表现为一个串口设备，Windows 内置的usbser驱动即可识别；
• HalfKay（PJRC Teensy 系列出厂 bootloader）：表现为一个通用 HID 设备，Windows 内置的HidUsb驱动即可识别。

此外，如果你已经按照 QMK 开发环境文档用 MSYS2 搭建了编译环境，QMK CLI 的安装脚本已经替你装好了这些驱动，可以跳过手动安装。

从源码结构看，QMK 支持的 bootloader 种类在构建系统中明确注册：platforms/avr/bootloader.mk 中列出了 AVR 平台的全部选项（halfkay、caterina、atmel-dfu、lufa-dfu、qmk-dfu、qmk-hid、bootloadhid、usbasploader、custom），各选项通过OPT_DEFS += -DBOOTLOADER_*定义注入固件，并决定BOOTLOADER_TYPE与保留的 bootloader 区大小（如atmel-dfu对 ATmega16U2/32U2 等 MCU 保留 4096 字节，对 at90usb128x 保留 8192 字节）。ARM（Chibios）平台则在 platforms/chibios/bootloader.mk 中注册，其实现文件分布在 platforms/chibios/bootloaders/（如at32_dfu.c、stm32_dfu.c、gd32v_dfu.c、kiibohd.c、stm32duino.c等）。这些源码实现与下文"已知 Bootloader 列表"中的 Bootloader 列一一对应，也解释了为什么不同 bootloader 在 Windows 上要求的驱动各不相同：DFU 类设备走WinUSB，USBaspLoader 走libusbK，Caterina 走usbser，HID 形态（HalfKay、BootloadHID、QMK HID）走HidUsb。

安装前的准备：进入 Bootloader 模式

Zadig 只负责"把驱动指派到正确的设备上"，因此第一步必须是让键盘进入 bootloader 模式。原文档给出了由通用到具体的几种方式：

1. 按QK_BOOT键码：它可能映射在任意键层上，可在 keymap 中搜索QK_BOOT确认位置；
2. 按物理复位开关：通常位于板子背面；
3. Bootmagic：两者都没有时，尝试在插入 USB 的同时按住Escape，或Space+B。Bootmagic 是 QMK 中"上电瞬间检测到特定按键即跳入 bootloader"的功能，默认触发键为矩阵 0 行 0 列（多数键盘即 Esc 键）；也可以在config.h中通过BOOTMAGIC_ROW/BOOTMAGIC_COLUMN指定其他键位。详见 Bootmagic 文档。
4. Command：部分键盘使用 Command（原名 Magic）代替 Bootmagic，这种情况下可以在键盘插入的任意时刻按Left Shift+Right Shift+B或Left Shift+Right Shift+Escape进入 bootloader。从源码看，这两个默认值由quantum/command.c中的MAGIC_KEY_BOOTLOADER（默认B）与MAGIC_KEY_BOOTLOADER_ALT（默认ESC）定义，且IS_COMMAND()默认组合为双 Shift。
5. USBaspLoader 的特例：按住BOOT键的同时轻触RESET键；或按住BOOT键再插入 USB 线。

需要留意的是，部分键盘有专属的进入方式：Bootmagic 键可能不在 Esc 而在其他键（例如左 Ctrl）；Command 的组合键也可能需要额外按键（例如Left Control+Right Control而非双 Shift）。不确定时请查阅对应键盘目录下的 README 与头文件。

使用 Zadig 安装驱动

QMK 官方推荐使用 Zadig 这类工具（文档中的外部链接仅作工具说明，使用时请自行获取最新版）。标准操作流程如下：

1. 先让键盘进入 bootloader 模式（见上节）；
2. 打开 Zadig，它通常会自动识别 bootloader 设备；如果下拉列表中没有，勾选Options → List All Devices后手动从下拉框中选择目标设备；
3. 检查驱动状态的颜色箭头，这是整个操作中最关键的安全检查：
   • 橙色箭头：Zadig 列出了一个或多个使用HidUsb驱动的设备，并且提示"修改系统驱动"需要确认——这说明你的键盘很可能并没有处于 bootloader 模式，Zadig 识别到的是正常的 HID 键盘本体。此时千万不要继续，否则会把键盘本体的输入驱动替换掉，导致键盘完全无法打字（修复方法见误装恢复一节）；
   • 绿色箭头：识别到的是 bootloader 设备，可以从下拉框中选择正确驱动，点击Install Driver。对照下文已知 Bootloader 列表确认应该安装哪个驱动（绝大多数 DFU 设备选WinUSB）。
4. 拔掉 USB 再重新插入，确保新驱动被加载。如果使用 QMK Toolbox 刷写，建议将其退出并重新启动，因为它有时无法感知驱动变更。

一个来自仓库变更日志的实战提示：在更新 QMK Toolbox 或 QMK MSYS 后，Atmel DFU 键盘的刷写可能失效，此时需要用 Zadig 将 bootloader 的libusb 驱动替换为 WinUSB。操作前务必确认键盘处于 bootloader 模式、且当前驱动显示为 libusb；如果显示的是HidUsb，说明还没进 bootloader，不要继续替换。详见 docs/ChangeLog/20240225.md。

已知 Bootloader 列表

下表完整继承自原文档，列出了已知 bootloader 设备、在 Zadig 中显示的设备名、USB VID/PID，以及刷写 QMK 时应指派的驱动。注意两点说明：

• usbser和HidUsb是 Windows 内置驱动，Zadig 无法直接指派它们——如果设备挂错了驱动，必须通过设备管理器卸载（见后文）；
• "Device Name" 一列是 Zadig 中显示的名称，与设备管理器或 QMK Toolbox 显示的命名可能不同。

对照 platforms/avr/bootloader.mk 可以验证第一列命名与构建系统的一致性：AVR 侧的atmel-dfu/qmk-dfu/qmk-hid/halfkay/caterina/bootloadhid/usbasploader各有独立编译开关，实际固件中bootloader_jump()的行为由对应的BOOTLOADER_TYPE决定；AVR 侧 bootloader 的入口实现位于 platforms/avr/bootloaders/dfu.c、platforms/avr/bootloaders/caterina.c、platforms/avr/bootloaders/halfkay.c 等文件。

从误装驱动中恢复

如果你发现键盘完全无法输入了，多半是键盘没有处于 bootloader 模式时执行了安装，Zadig 把键盘本体（而非 bootloader）的驱动替换掉了。判断依据很简单：一台健康的键盘在 Zadig 中，所有接口都应安装着HidUsb驱动。

恢复步骤（全部在 Windows 设备管理器中完成）：

1. 打开设备管理器，选择View → Devices by container（按容器查看设备），找到以你键盘名称命名的条目；
2. 对该条目下的每一个子项右键 →Uninstall device（卸载设备）。如果弹出对话框中出现"Delete the driver software for this device"复选框，务必先勾上再确认；
3. 点击Action → Scan for hardware changes（扫描硬件改动），此时键盘应该恢复输入能力；
4. 回到 Zadig 复核：键盘设备的驱动应显示为HidUsb。如果是，问题已解决；否则重复以上过程，直到 Zadig 报告正确驱动。

原文档补充了一个经验性提示：某些情况下这一步之后需要完整重启电脑，Windows 才会重新加载新驱动。

卸载 Bootloader 驱动（进阶）

卸载比安装更麻烦，因为同一个设备可能匹配多个驱动，且 Windows 不允许简单地"卸载驱动"了事。完整流程：

1. 打开设备管理器，View → Devices by container，定位到 bootloader 设备；将 Zadig 中显示的 USB VID/PID 与上文已知 Bootloader 列表核对，确认目标设备无误；
2. 打开该设备的属性 → 详细信息标签页，在属性下拉框中选择"Inf name"，记下形如oemXX.inf的值；
3. 以管理员身份打开命令提示符（开始菜单输入cmd后按Ctrl+Shift+Enter）；
4. 运行pnputil /enum-drivers，在输出中找到Published Name与刚才Inf name匹配的条目，再次核对确认；
5. 运行pnputil /delete-driver oemXX.inf /uninstall（把oemXX.inf替换为实际值）。该命令会删除驱动并将其从所有使用它的设备上移除，但不会卸载设备本身。

两个重要注意事项：

• 同一设备可能命中多个驱动，整个流程可能需要重复多次，直到 Zadig 中看不到残留的错误驱动；
• 操作时要格外小心——/delete-driver可能误删其他关键设备的驱动。拿不准时，先用pnputil /enum-drivers仔细核对，并在/delete-driver时省略/uninstall标志做干跑（dry-run）确认影响范围。

小结

在 Windows 上刷写 QMK 固件的驱动问题可以归纳为三条原则：

1. 装驱动前确认设备形态：Zadig 箭头为橙色（列出HidUsb系统驱动）说明键盘还停留在正常 HID 模式，此时安装必然装错；
2. 驱动指派对照 VID/PID：DFU 类（atmel-dfu/qmk-dfu/stm32-dfu等）一律WinUSB，usbasploader用libusbK，caterina/halfkay/bootloadhid/qmk-hid这类串口或 HID 形态设备由 Windows 内置驱动（usbser/HidUsb）处理；
3. 出错时按容器卸载 + 扫描硬件恢复，疑难场景用pnputil精确删除驱动桩。

如果编译侧也有问题，可结合 FAQ（其中同样指向本文档处理 Zadig 相关故障）与键盘目录下的 README 交叉核对，确认自己的 bootloader 类型后再执行驱动操作。

【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware