企业官网建设流程全解析

QMK Firmware 烧录实战指南：从 DFU 模式进入到 QMK Toolbox 与 qmk flash 命令行

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

本文基于 QMK Firmware 官方入门文档 docs/newbs_flashing.md 编写，系统讲解固件烧录（flashing）的完整流程：如何让键盘进入 DFU/Bootloader 模式、如何使用 QMK Toolbox 图形界面烧录、以及 Linux/macOS 下如何用qmk flash命令行一键完成编译加烧录。读完后，你将能够独立完成从编译产物（.hex/.bin）到键盘实机的烧录，并掌握烧录失败时的定位思路。

前置条件：你已经有了一个固件文件

烧录的前提是你已经按照 构建固件流程 编译出了自定义固件。固件文件有两种格式：.hex和.bin，QMK 构建系统会尝试将适合你键盘的格式拷贝到qmk_firmware仓库根目录。

固件文件的命名规则是固定的：

<keyboard>_<keymap>.{bin,hex}

例如planck/rev5键盘的default键位，对应文件名为planck_rev5_default.hex。

在 Windows 或 macOS 上，你可以用以下命令在构建目录中直接打开资源管理器/访达来定位文件：

# Windows start . # macOS open .

让键盘进入 DFU（Bootloader）模式

烧录前必须先把键盘切换到专门的烧录模式。进入该模式后键盘无法输入，这是正常现象。务必注意：在固件写入过程中不要拔掉键盘或做任何可能中断烧录的操作。

不同键盘的进入方式不同。如果当前 PCB 运行的是 QMK、TMK 或 PS2AVRGB（Bootmapper Client）固件且你没有拿到专门的说明，按以下顺序逐一尝试：

1. 同时按住两个 Shift 键，然后按Pause；
2. 同时按住两个 Shift 键，然后按B；
3. 拔掉键盘，同时按住 Spacebar 和B，再插上键盘，等待一秒后松开按键；
4. 拔掉键盘，按住左上角或左下角的按键（通常是 Escape 或左 Control），再插上键盘；
5. 按 PCB 上的物理RESET按键，通常位于板子背面；
6. 找到 PCB 上标注为RESET和GND的焊盘，在插入电源的瞬间将两者短接。

如果以上方法都无效，且主控芯片上印着STM32或RP2-B1，情况会更复杂一些（这类芯片的进入方式通常与具体电路板设计有关）。此时最好的办法是准备好板子的照片，去 QMK 官方 Discord 社区求助。

确认已成功进入 bootloader

进入成功后，QMK Toolbox 会显示一条黄色的消息，例如：

*** DFU device connected: Atmel Corp. ATmega32U4 (03EB:2FF4:0000)

此时该 bootloader 设备也会出现在 Windows 设备管理器、macOS 的"系统信息.app"，或者 Linux 的lsusb输出中。以 ATmega32U4 为例，你会看到 VID/PID 为03EB:2FF4的 DFU 设备——这是判断"进入烧录模式成功"的最直接证据。

方式一：使用 QMK Toolbox 烧录（Windows/macOS）

最简单的方式是使用 QMK Toolbox 图形界面工具。需要注意的是：Toolbox 目前仅提供 Windows 和 macOS 版本；如果你使用 Linux，或者习惯命令行操作，请直接跳到下一节的qmk flash方案。

另外一个特例：烧录 RP2040 芯片设备 时不需要 QMK Toolbox（它走 UF2 拖拽流程，见docs/flashing.md中的 Raspberry Pi RP2040 UF2 小节）。

在 QMK Toolbox 中加载固件

1. 打开 QMK Toolbox 应用；
2. 在 Finder 或资源管理器中找到固件文件（.hex或.bin）；
3. 将文件拖入 Toolbox 的 "Local file" 区域，或点击 "Open" 手动选择文件路径。

点击 Flash 开始烧录

点击Flash按钮后，你会看到类似如下的输出（这段日志本身也是排查问题的第一手资料，建议保存）：

*** DFU device connected: Atmel Corp. ATmega32U4 (03EB:2FF4:0000) *** Attempting to flash, please don't remove device >>> dfu-programmer.exe atmega32u4 erase --force Erasing flash... Success Checking memory from 0x0 to 0x6FFF... Empty. >>> dfu-programmer.exe atmega32u4 flash "D:\Git\qmk_firmware\gh60_satan_default.hex" Checking memory from 0x0 to 0x3F7F... Empty. 0% 100% Programming 0x3F80 bytes... [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success 0% 100% Reading 0x7000 bytes... [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success Validating... Success 0x3F80 bytes written into 0x7000 bytes memory (56.70%). >>> dfu-programmer.exe atmega32u4 reset *** DFU device disconnected: Atmel Corp: ATmega32U4 (03EB:2FF4:0000)

从日志可以看出烧录的完整链条：erase（擦除）→flash（写入并回读校验）→Validating（验证）→reset（复位，键盘自动重启回到正常模式）。最后0x3F80 bytes written into 0x7000 bytes memory (56.70%)说明本次固件占用了 32U4 可用内存的一半多一点——如果你的日志在这里显示超内存，说明固件超过了 bootloader 前预留的空间，需要关闭一些功能。

方式二：命令行烧录 qmk flash

对于 Linux 用户（或偏爱命令行的人），qmk flash是官方推荐的烧录方式。它比早期版本简单得多，当你准备好编译并烧录固件时，打开终端执行：

qmk flash

如果你没有在 构建环境配置阶段 中通过qmk config设置默认的键盘/键位名，或者你机器上有多把键盘，可以显式指定：

qmk flash -kb <my_keyboard> -km <my_keymap>

为什么 qmk flash 不需要你了解 bootloader？

qmk flash会先检查键盘配置，然后根据该键盘rules.mk中声明的BOOTLOADER值自动选择对应的烧录工具与参数。也就是说，你不需要事先知道键盘用的是哪种 bootloader，运行命令即可。

从源码结构看，这个自动选择的前提是键盘配置里显式声明了BOOTLOADER宏。docs/flashing.md 列出了当前 QMK 支持的主要 bootloader 及其rules.mk配置，例如：

• BOOTLOADER = atmel-dfu——Atmel DFU bootloader，出厂预置在所有 USB AVR 芯片上（16/32U4RC 除外），大量 OLKB 老板与 Clueboard 使用，QMK 也维护了它的 LUFA/QMK 分支；
• BOOTLOADER = caterina——Arduino/Pro Micro 克隆板使用的 AVR109 串口协议 bootloader；
• BOOTLOADER = halfkay——Teensy 2.0 预烧录的超精简 HID bootloader（闭源，一旦被覆盖无法恢复）；
• BOOTLOADER = usbasploader——面向 ATmega328P + V-USB 的 ISP 模拟 bootloader；
• BOOTLOADER = bootloadhid——以 HID 设备呈现、Windows 免驱动的 USB bootloader。

此外，docs/cli_commands.md 中还补充了命令行烧录的其他用法：

# 指定 bootloader（覆盖自动检测） qmk flash -kb <keyboard> -km <keymap_name> -bl <bootloader> # 直接烧录预编译的固件文件（如 Configurator 导出的 hex/bin） qmk flash [-m <microcontroller>] <compiledFirmware.[bin|hex]> # 列出当前支持的 bootloader qmk flash -b

值得注意：对于 HalfKay、QMK HID、USBaspLoader 这三类 bootloader，以及 USBasp / USBtinyISP 两种 ISP 烧录器，必须通过-m <microcontroller>显式指定微控制器型号。

常见报错与排查

如果键盘没有配置 bootloader（或使用了当前不支持的烧录目标），qmk flash会报出：

WARNING: This board's bootloader is not specified or is not supported by the ":flash" target at this time.

出现该错误时，你有两条路：

1. 手动指定 bootloader 重试，参考 Flashing Firmware 指南 中各 bootloader 的进入方式和专用工具；
2. 运行qmk doctor。该命令会检查你的构建与烧录环境，并给出修复常见问题的建议（详见 docs/cli_commands.md 中qmk doctor小节）。

另外，Linux 用户如果连不上 DFU 设备，权限问题是最常见原因之一，可以用仓库自带的 util/install_udev.sh 安装 udev 规则来解决。

烧录后的验证：Test It Out

烧录成功、键盘重启后就可以测试了。基本做法很直接：按下每一个键，确认其发出的键码与预期一致。

如果键盘工作不正常，可以用 QMK Configurator 的测试模式（test mode）逐键检查——该模式即使键盘当前跑的不是 QMK 固件也能用，它能实时显示实际发出来的键码，是定位"按键矩阵映射写错"这类问题的利器。

仍然无法解决？建议依次：

• 回到本文的 bootloader 进入方法一节，确认你观察到的确实是 DFU 设备而非普通 HID 键盘；
• 查看 FAQ 主题 中的相关条目；
• 带着固件文件命名、lsusb输出和烧录日志去 QMK Discord 社区求助。

小结

QMK 的烧录流程可以归纳为三步：进入 bootloader 模式 → 确认 DFU 设备被系统识别 → 用 QMK Toolbox 或qmk flash写入固件并自动复位。其中qmk flash依靠键盘rules.mk中的BOOTLOADER声明自动完成工具选择，是跨平台、可脚本化的首选方式；遇到报错时，qmk doctor和 docs/flashing.md 中按 bootloader 分类的详细说明是两条主要的排查线索。

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