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 总线上出现的是一个 DFUDevice Firmware Upgrade或专用的编程设备Windows 默认可能为其挂上错误的驱动或没有合适的驱动导致刷写工具无法访问该设备。原文档特别指出两个不需要手动装驱动的例外Caterina常见于 SparkFun Pro Micro进入 bootloader 后表现为一个串口设备Windows 内置的usbser驱动即可识别HalfKayPJRC 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 字节。ARMChibios平台则在 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 类设备走WinUSBUSBaspLoader 走libusbKCaterina 走usbserHID 形态HalfKay、BootloadHID、QMK HID走HidUsb。安装前的准备进入 Bootloader 模式Zadig 只负责把驱动指派到正确的设备上因此第一步必须是让键盘进入 bootloader 模式。原文档给出了由通用到具体的几种方式按QK_BOOT键码它可能映射在任意键层上可在 keymap 中搜索QK_BOOT确认位置按物理复位开关通常位于板子背面Bootmagic两者都没有时尝试在插入 USB 的同时按住Escape或SpaceB。Bootmagic 是 QMK 中上电瞬间检测到特定按键即跳入 bootloader的功能默认触发键为矩阵 0 行 0 列多数键盘即 Esc 键也可以在config.h中通过BOOTMAGIC_ROW/BOOTMAGIC_COLUMN指定其他键位。详见 Bootmagic 文档。Command部分键盘使用 Command原名 Magic代替 Bootmagic这种情况下可以在键盘插入的任意时刻按Left ShiftRight ShiftB或Left ShiftRight ShiftEscape进入 bootloader。从源码看这两个默认值由quantum/command.c中的MAGIC_KEY_BOOTLOADER默认B与MAGIC_KEY_BOOTLOADER_ALT默认ESC定义且IS_COMMAND()默认组合为双 Shift。USBaspLoader 的特例按住BOOT键的同时轻触RESET键或按住BOOT键再插入 USB 线。需要留意的是部分键盘有专属的进入方式Bootmagic 键可能不在 Esc 而在其他键例如左 CtrlCommand 的组合键也可能需要额外按键例如Left ControlRight Control而非双 Shift。不确定时请查阅对应键盘目录下的 README 与头文件。使用 Zadig 安装驱动QMK 官方推荐使用 Zadig 这类工具文档中的外部链接仅作工具说明使用时请自行获取最新版。标准操作流程如下先让键盘进入 bootloader 模式见上节打开 Zadig它通常会自动识别 bootloader 设备如果下拉列表中没有勾选Options → List All Devices后手动从下拉框中选择目标设备检查驱动状态的颜色箭头这是整个操作中最关键的安全检查橙色箭头Zadig 列出了一个或多个使用HidUsb驱动的设备并且提示修改系统驱动需要确认——这说明你的键盘很可能并没有处于 bootloader 模式Zadig 识别到的是正常的 HID 键盘本体。此时千万不要继续否则会把键盘本体的输入驱动替换掉导致键盘完全无法打字修复方法见误装恢复一节绿色箭头识别到的是 bootloader 设备可以从下拉框中选择正确驱动点击Install Driver。对照下文已知 Bootloader 列表确认应该安装哪个驱动绝大多数 DFU 设备选WinUSB。拔掉 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 显示的命名可能不同。BootloaderDevice NameVID/PID应安装驱动atmel-dfuATmega16u2 DFU03EB:2FEFWinUSBatmel-dfuATmega32U2 DFU03EB:2FF0WinUSBatmel-dfuATm16U4 DFU V1.0.203EB:2FF3WinUSBatmel-dfuATm32U4DFU03EB:2FF4WinUSBatmel-dfunone(AT90USB64)03EB:2FF9WinUSBatmel-dfuAT90USB128 DFU03EB:2FFBWinUSBqmk-dfu(keyboard name) Bootloader同atmel-dfuWinUSBhalfkaynone16C0:0478HidUsbcaterinaPro Micro 3.3V1B4F:9203usbsercaterinaPro Micro 5V1B4F:9205usbsercaterinaLilyPadUSB1B4F:9207usbsercaterinaPololu A-Star 32U4 Bootloader1FFB:0101usbsercaterinaArduino Leonardo2341:0036usbsercaterinaArduino Micro2341:0037usbsercaterinaAdafruit Feather 32u4239A:000CusbsercaterinaAdafruit ItsyBitsy 32u4 3V239A:000DusbsercaterinaAdafruit ItsyBitsy 32u4 5V239A:000EusbsercaterinaArduino Leonardo2A03:0036usbsercaterinaArduino Micro2A03:0037usbserbootloadhidHIDBoot16C0:05DFHidUsbusbasploaderUSBasp16C0:05DClibusbKapm32-dfuAPM32 DFU ISP Mode314B:0106WinUSBat32-dfuAT32 Bootloader DFU2E3C:DF11WinUSBstm32-dfuSTM32 BOOTLOADER0483:DF11WinUSBgd32v-dfuGD32V BOOTLOADER28E9:0189WinUSBkiibohdKiibohd DFU Bootloader1C11:B007WinUSBstm32duinoMaple 0031EAF:0003WinUSBqmk-hid(keyboard name) Bootloader03EB:2067HidUsb对照 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 设备管理器中完成打开设备管理器选择View → Devices by container按容器查看设备找到以你键盘名称命名的条目对该条目下的每一个子项右键 →Uninstall device卸载设备。如果弹出对话框中出现Delete the driver software for this device复选框务必先勾上再确认点击Action → Scan for hardware changes扫描硬件改动此时键盘应该恢复输入能力回到 Zadig 复核键盘设备的驱动应显示为HidUsb。如果是问题已解决否则重复以上过程直到 Zadig 报告正确驱动。原文档补充了一个经验性提示某些情况下这一步之后需要完整重启电脑Windows 才会重新加载新驱动。卸载 Bootloader 驱动进阶卸载比安装更麻烦因为同一个设备可能匹配多个驱动且 Windows 不允许简单地卸载驱动了事。完整流程打开设备管理器View → Devices by container定位到 bootloader 设备将 Zadig 中显示的 USB VID/PID 与上文已知 Bootloader 列表核对确认目标设备无误打开该设备的属性 → 详细信息标签页在属性下拉框中选择Inf name记下形如oemXX.inf的值以管理员身份打开命令提示符开始菜单输入cmd后按CtrlShiftEnter运行pnputil /enum-drivers在输出中找到Published Name与刚才Inf name匹配的条目再次核对确认运行pnputil /delete-driver oemXX.inf /uninstall把oemXX.inf替换为实际值。该命令会删除驱动并将其从所有使用它的设备上移除但不会卸载设备本身。两个重要注意事项同一设备可能命中多个驱动整个流程可能需要重复多次直到 Zadig 中看不到残留的错误驱动操作时要格外小心——/delete-driver可能误删其他关键设备的驱动。拿不准时先用pnputil /enum-drivers仔细核对并在/delete-driver时省略/uninstall标志做干跑dry-run确认影响范围。小结在 Windows 上刷写 QMK 固件的驱动问题可以归纳为三条原则装驱动前确认设备形态Zadig 箭头为橙色列出HidUsb系统驱动说明键盘还停留在正常 HID 模式此时安装必然装错驱动指派对照 VID/PIDDFU 类atmel-dfu/qmk-dfu/stm32-dfu等一律WinUSBusbasploader用libusbKcaterina/halfkay/bootloadhid/qmk-hid这类串口或 HID 形态设备由 Windows 内置驱动usbser/HidUsb处理出错时按容器卸载 扫描硬件恢复疑难场景用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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
QMK 固件 Windows 引导加载器驱动安装实战：Zadig 驱动指派、故障恢复与卸载全解
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 总线上出现的是一个 DFUDevice Firmware Upgrade或专用的编程设备Windows 默认可能为其挂上错误的驱动或没有合适的驱动导致刷写工具无法访问该设备。原文档特别指出两个不需要手动装驱动的例外Caterina常见于 SparkFun Pro Micro进入 bootloader 后表现为一个串口设备Windows 内置的usbser驱动即可识别HalfKayPJRC 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 字节。ARMChibios平台则在 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 类设备走WinUSBUSBaspLoader 走libusbKCaterina 走usbserHID 形态HalfKay、BootloadHID、QMK HID走HidUsb。安装前的准备进入 Bootloader 模式Zadig 只负责把驱动指派到正确的设备上因此第一步必须是让键盘进入 bootloader 模式。原文档给出了由通用到具体的几种方式按QK_BOOT键码它可能映射在任意键层上可在 keymap 中搜索QK_BOOT确认位置按物理复位开关通常位于板子背面Bootmagic两者都没有时尝试在插入 USB 的同时按住Escape或SpaceB。Bootmagic 是 QMK 中上电瞬间检测到特定按键即跳入 bootloader的功能默认触发键为矩阵 0 行 0 列多数键盘即 Esc 键也可以在config.h中通过BOOTMAGIC_ROW/BOOTMAGIC_COLUMN指定其他键位。详见 Bootmagic 文档。Command部分键盘使用 Command原名 Magic代替 Bootmagic这种情况下可以在键盘插入的任意时刻按Left ShiftRight ShiftB或Left ShiftRight ShiftEscape进入 bootloader。从源码看这两个默认值由quantum/command.c中的MAGIC_KEY_BOOTLOADER默认B与MAGIC_KEY_BOOTLOADER_ALT默认ESC定义且IS_COMMAND()默认组合为双 Shift。USBaspLoader 的特例按住BOOT键的同时轻触RESET键或按住BOOT键再插入 USB 线。需要留意的是部分键盘有专属的进入方式Bootmagic 键可能不在 Esc 而在其他键例如左 CtrlCommand 的组合键也可能需要额外按键例如Left ControlRight Control而非双 Shift。不确定时请查阅对应键盘目录下的 README 与头文件。使用 Zadig 安装驱动QMK 官方推荐使用 Zadig 这类工具文档中的外部链接仅作工具说明使用时请自行获取最新版。标准操作流程如下先让键盘进入 bootloader 模式见上节打开 Zadig它通常会自动识别 bootloader 设备如果下拉列表中没有勾选Options → List All Devices后手动从下拉框中选择目标设备检查驱动状态的颜色箭头这是整个操作中最关键的安全检查橙色箭头Zadig 列出了一个或多个使用HidUsb驱动的设备并且提示修改系统驱动需要确认——这说明你的键盘很可能并没有处于 bootloader 模式Zadig 识别到的是正常的 HID 键盘本体。此时千万不要继续否则会把键盘本体的输入驱动替换掉导致键盘完全无法打字修复方法见误装恢复一节绿色箭头识别到的是 bootloader 设备可以从下拉框中选择正确驱动点击Install Driver。对照下文已知 Bootloader 列表确认应该安装哪个驱动绝大多数 DFU 设备选WinUSB。拔掉 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 显示的命名可能不同。BootloaderDevice NameVID/PID应安装驱动atmel-dfuATmega16u2 DFU03EB:2FEFWinUSBatmel-dfuATmega32U2 DFU03EB:2FF0WinUSBatmel-dfuATm16U4 DFU V1.0.203EB:2FF3WinUSBatmel-dfuATm32U4DFU03EB:2FF4WinUSBatmel-dfunone(AT90USB64)03EB:2FF9WinUSBatmel-dfuAT90USB128 DFU03EB:2FFBWinUSBqmk-dfu(keyboard name) Bootloader同atmel-dfuWinUSBhalfkaynone16C0:0478HidUsbcaterinaPro Micro 3.3V1B4F:9203usbsercaterinaPro Micro 5V1B4F:9205usbsercaterinaLilyPadUSB1B4F:9207usbsercaterinaPololu A-Star 32U4 Bootloader1FFB:0101usbsercaterinaArduino Leonardo2341:0036usbsercaterinaArduino Micro2341:0037usbsercaterinaAdafruit Feather 32u4239A:000CusbsercaterinaAdafruit ItsyBitsy 32u4 3V239A:000DusbsercaterinaAdafruit ItsyBitsy 32u4 5V239A:000EusbsercaterinaArduino Leonardo2A03:0036usbsercaterinaArduino Micro2A03:0037usbserbootloadhidHIDBoot16C0:05DFHidUsbusbasploaderUSBasp16C0:05DClibusbKapm32-dfuAPM32 DFU ISP Mode314B:0106WinUSBat32-dfuAT32 Bootloader DFU2E3C:DF11WinUSBstm32-dfuSTM32 BOOTLOADER0483:DF11WinUSBgd32v-dfuGD32V BOOTLOADER28E9:0189WinUSBkiibohdKiibohd DFU Bootloader1C11:B007WinUSBstm32duinoMaple 0031EAF:0003WinUSBqmk-hid(keyboard name) Bootloader03EB:2067HidUsb对照 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 设备管理器中完成打开设备管理器选择View → Devices by container按容器查看设备找到以你键盘名称命名的条目对该条目下的每一个子项右键 →Uninstall device卸载设备。如果弹出对话框中出现Delete the driver software for this device复选框务必先勾上再确认点击Action → Scan for hardware changes扫描硬件改动此时键盘应该恢复输入能力回到 Zadig 复核键盘设备的驱动应显示为HidUsb。如果是问题已解决否则重复以上过程直到 Zadig 报告正确驱动。原文档补充了一个经验性提示某些情况下这一步之后需要完整重启电脑Windows 才会重新加载新驱动。卸载 Bootloader 驱动进阶卸载比安装更麻烦因为同一个设备可能匹配多个驱动且 Windows 不允许简单地卸载驱动了事。完整流程打开设备管理器View → Devices by container定位到 bootloader 设备将 Zadig 中显示的 USB VID/PID 与上文已知 Bootloader 列表核对确认目标设备无误打开该设备的属性 → 详细信息标签页在属性下拉框中选择Inf name记下形如oemXX.inf的值以管理员身份打开命令提示符开始菜单输入cmd后按CtrlShiftEnter运行pnputil /enum-drivers在输出中找到Published Name与刚才Inf name匹配的条目再次核对确认运行pnputil /delete-driver oemXX.inf /uninstall把oemXX.inf替换为实际值。该命令会删除驱动并将其从所有使用它的设备上移除但不会卸载设备本身。两个重要注意事项同一设备可能命中多个驱动整个流程可能需要重复多次直到 Zadig 中看不到残留的错误驱动操作时要格外小心——/delete-driver可能误删其他关键设备的驱动。拿不准时先用pnputil /enum-drivers仔细核对并在/delete-driver时省略/uninstall标志做干跑dry-run确认影响范围。小结在 Windows 上刷写 QMK 固件的驱动问题可以归纳为三条原则装驱动前确认设备形态Zadig 箭头为橙色列出HidUsb系统驱动说明键盘还停留在正常 HID 模式此时安装必然装错驱动指派对照 VID/PIDDFU 类atmel-dfu/qmk-dfu/stm32-dfu等一律WinUSBusbasploader用libusbKcaterina/halfkay/bootloadhid/qmk-hid这类串口或 HID 形态设备由 Windows 内置驱动usbser/HidUsb处理出错时按容器卸载 扫描硬件恢复疑难场景用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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考