QMK Firmware 新手指南从环境搭建到编译、烧录你的第一个键盘固件【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware本文基于 QMK 官方教程 The QMK Tutorial 展开带你完整走通用源码构建自定义键盘固件的全流程准备构建环境qmk setup、创建并修改自己的 keymapqmk new-keymap、编译出固件qmk compile以及把固件写入键盘qmk flash或 QMK Toolbox。读完本文你将能够独立完成一个可运行的定制键盘固件并理解 keymap 文件结构、层Layer数量上限等底层限制是如何由 QMK 源码决定的。1. 概述你在写的其实是一段可执行程序你的键盘内部有一枚微控制器MCU和电脑里的处理器角色类似。它上面运行的固件负责检测按键按下、并把键值上报给主机电脑。QMK Firmware 扮演的正是这个角色——检测按键并将信息传递给主机。当你构建自定义 keymap键位映射时你实际上是在为你的键盘编写一个可执行程序。QMK 的设计目标是让简单的事更简单让困难的事成为可能你不需要懂编程也能做出功能强大的 keymap只需要遵守几条简单的语法规则。不确定自己的键盘能否跑 QMK如果你自装的是机械键盘大概率可以。QMK 支持大量爱好者键盘可用qmk list-keyboards查看完整列表如果对编程感到畏惧可以先试试在线图形化工具 QMK Configurator官方教程见 configurator 入门 与 configurator 架构。这份教程面向从未编译过软件的人所有建议都以零基础读者为出发点。教程共分三个主要部分设置你的环境构建你的第一个固件烧录固件。很多步骤存在替代方案QMK 支持其中大多数对任何操作拿不准时可查阅 支持文档 寻求指引。2. 准备构建环境无论你要为多少块键盘编译固件环境只需准备一次。2.1 前置软件文本编辑器必需需要能编辑并保存纯文本文件的编辑器很多操作系统的默认编辑器不会保存纯文本。面向代码的编辑器如 VS Code、Sublime Text 均可编辑器选择参考见 文本编辑器资源。QMK Toolbox可选Windows/macOS 上的图形化程序可同时烧录和调试键盘。命令行基础Linux/Unix 用户若你没用过命令行先花几分钟学习基础概念和命令命令行资源 足够支撑你在 QMK 中工作。2.2 安装 QMK CLIQMK 的搭建思路是你只需准备好操作系统层面剩下的依赖交给 QMK 自己安装。WindowsQMK 维护了一个打包好的 MSYS2 发行版QMK MSYS包含 CLI 和全部依赖并提供QMK MSYS终端快捷方式。高版本 Windows 也可用 Windows Terminal WSL推荐 Ubuntu 22.04/24.04。手动安装 MSYS2进阶用户不推荐给新手安装 MSYS2 后关闭所有已打开的 MSYS 终端紫色图标从开始菜单打开MinGW 64-bit 终端蓝色图标。注意MinGW 64-bit 终端与安装完成时弹出的 MSYS 终端不是一回事提示符应显示紫色 MINGW64 而非 MSYS。在该终端中执行curl -fsSL https://install.qmk.fm | shmacOS先安装 Homebrew然后执行curl -fsSL https://install.qmk.fm | shLinux / WSL主流发行版均可支持推荐 Debian 系Ubuntu、Mint、CentOS 系Fedora、Rocky或 Arch 系Manjaro、CachyOS。标准 QMK 构建环境不支持基于musl的发行版如 Alpine。执行curl -fsSL https://install.qmk.fm | sh两个注意点WSL 用户默认安装会把 QMK 仓库克隆到 WSL 主目录若是手动克隆务必放在 WSL 文件系统内例如~/qmk_firmware不要放在/mnt/c/...之类的 Windows 盘挂载点否则跨文件系统访问会导致编译极慢。发行版自带包你发行版软件源里的 QMK 相关包几乎肯定已过时强烈建议用上面的安装脚本而不是apt/yum安装。FreeBSD社区尽力支持非官方维护pkg install -g py*-qmk安装完成后按屏幕提示操作可用pkg info -Dg py*-qmk再次查看提示。2.3 运行qmk setup打开终端Windows 用户打开 QMK MSYS 终端执行qmk setup绝大多数提示直接回答y即可。该命令会安装/更新 QMK CLI如果通过安装脚本安装此时可能已有克隆qmk_firmware仓库到~/qmk_firmware可用qmk setup -H path指定 QMK 主目录之后可通过 CLI 配置 中的user.qmk_home变量修改在~/.profile中写入环境变量并设置qmk命令默认在~/qmk_firmware目录内运行安装构建所需的全部工具链avr-gcc / arm-none-eabi-gcc / chibios 等在~/qmk_firmware/.qmk_cli.yml中生成默认 CLI 配置。所有可选项可用qmk setup --help查看。Debian/Ubuntu 上qmk: command not found这是 Debian Bash 4.4 移除$HOME/.local/bin出 PATH 引入的历史问题Ubuntu 曾重新引入。修复方法以当前用户执行echo PATH$HOME/.local/bin:$PATH $HOME/.bashrc source $HOME/.bashrc已有 GitHub 账号的进阶用法建议先 fork 官方仓库然后qmk setup github_username/qmk_firmware克隆你的个人 fork方便后续提交自己的 keymap 和修改。详见 GitHub 工作流 与 Git 最佳实践。2.4 验证构建环境环境就绪后先编译一块键盘的默认 keymap 来验证qmk compile -kb keyboard -km default例如为 Clueboard 66%rev3构建qmk compile -kb clueboard/66/rev3 -km default-kb选项是相对于键盘目录的路径即上例对应源码中的 keyboards/clueboard/66/rev3。不确定支持的键盘清单时运行qmk list-keyboards。编译成功时的输出结尾类似Linking: .build/clueboard_66_rev3_default.elf [OK] Creating load file for flashing: .build/clueboard_66_rev3_default.hex [OK] Copying clueboard_66_rev3_default.hex to qmk_firmware folder [OK] Checking file size of clueboard_66_rev3_default.hex [OK] * The firmware size is fine - 26356/28672 (2316 bytes free)也就是说编译产物.elf/.hex/.bin会先落到.build/目录随后自动拷贝到qmk_firmware仓库根目录并做 flash 容量检查。这一拷贝到根目录的行为正是后面用 QMK Toolbox 找固件文件时的依据。编译过程本身由 Make 系统驱动CLI 的qmk compile最终调用顶层 Makefile它包含 builddefs/build_keyboard.mk、builddefs/common_features.mk 等规则文件完成特性开关判定、平台AVR/Chibios选择与链接。3. 创建并修改你的 Keymap构建环境就绪后就可以创建个人 keymap 了。建议保持文件管理器、文本编辑器、终端三个窗口同时打开直到你满意为止。3.1 设置默认键盘与默认 keymap可选qmk config user.keyboardclueboard/66/rev4 qmk config user.keymapgithub_username设置后之后的qmk new-keymap、qmk compile、qmk flash等命令都可以省略-kb/-km参数。多键盘用户可跳过此步、每次显式指定。3.2 创建新 keymap创建新 keymap 的本质是复制defaultkeymapqmk new-keymap未配置默认键盘时qmk new-keymap -kb keyboard输出示例Ψ Created a new keymap called github_username in: /home/me/qmk_firmware/keyboards/clueboard/66/rev3/keymaps/github_username.新 keymap 位于键盘目录/keymaps/你的名字/下。注意不同键盘的默认 keymap 文件可能是.json也可能是.c.json格式可用 QMK 的json2c工具转换为.c用法见 qmk json2c。3.3 读懂keymap.c用文本编辑器打开keymap.c。文件顶部通常有一些#define和enum让代码更易读往下找你会看到这一行const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] {这标志着Layers层列表的开始。其后的若干行是LAYOUT_*宏调用每一组代表一层的完整键位宏参数就是这一层每个位置上的键码keycode。警告编辑 keymap 文件时千万不要多加或少加逗号——一个逗号的差异就会让编译失败而且定位起来可能很费劲。关于层数上限的源码依据教程提到你可以增删层最多 32 层。从源码结构看这个上限来自 quantum/action_layer.h 中对layer_state_t的定义未显式指定时默认LAYER_STATE_16BITMAX_LAYER 16定义LAYER_STATE_32BIT后layer_state_t为uint32_t、MAX_LAYER 32。也就是说要实际使用超过 16 层需要在 keymap 的rules.mk中配置LAYER_STATE 32bit该配置项说明见 config_options.md。3.4 开始自定义改法是自由发挥改一个一直碍事的功能键或者彻底重构。可删除不需要的层也可增加层。起步阶段建议从小处入手参考这些易上手的功能文档基础键码Quantum 键码Grave/Escape鼠标键提示在熟悉 keymap 机制前每次只做小改动大改动会让调试困难。4. 编译固件修改完成后回到终端qmk compile多键盘/未配置默认时qmk compile -kb keyboard -km keymap编译过程会持续打印正在编译的文件成功结尾类似Linking: .build/planck_rev5_default.elf [OK] Creating load file for flashing: .build/planck_rev5_default.hex [OK] Copying planck_rev5_default.hex to qmk_firmware folder [OK] Checking file size of planck_rev5_default.hex [OK] * The firmware size is fine - 27312/28672 (95%, 1360 bytes free)最后一行同时给出了 flash 占用百分比与剩余字节数——如果剩余空间为负说明功能开太多需要关闭rules.mk中的某些特性。产物keyboard_keymap.hex或.bin会出现在仓库根目录可直接用于烧录。5. 烧录固件5.1 让键盘进入 DFUBootloader模式烧录前必须让键盘进入专门的烧录模式。此模式下键盘无法输入且烧写过程中切勿拔线或中断。不同键盘进入方式不同若你的板子当前跑的是 QMK/TMK/PS2AVRGB 且没有特殊说明按顺序尝试按住两侧 Shift 键按Pause按住两侧 Shift 键按B拔掉键盘同时按住空格键和B插上等 1 秒再松开拔掉键盘按住最上/最左下角通常是 Esc 或左 Ctrl插上按 PCB 上的物理RESET按钮通常在背面找到标有RESET和GND的针脚插线时短接它们。若都无效且主控芯片上印着STM32或RP2-B1情况会复杂一些STM32 无 DFU 时需要 ISP 等其他方式RP2040 走 UF2 拖拽流程建议携带板子照片到社区Discord求助流程详见 ISP 烧录指南 与 Flashing 参考。成功进入 DFU 后QMK Toolbox 中会看到黄色提示例如*** DFU device connected: Atmel Corp. ATmega32U4 (03EB:2FF4:0000)该 DFU 设备同时会出现在设备管理器、系统信息.app 或lsusb输出中。5.2 用 QMK Toolbox 烧录Windows/macOS最简方式是 QMK Toolbox 图形界面。步骤打开 Toolbox找到固件文件.hex或.bin。它在qmk_firmware仓库根目录命名固定为keyboard_keymap.{bin,hex}例如planck/rev5defaultkeymap 对应planck_rev5_default.hex。在终端里可用start .Windows或open .macOS直接打开当前目录。把文件拖入 Local file 框或点 Open 选择。点Flash按钮成功时输出类似*** DFU device connected: Atmel Corp. ATmega32U4 (03EB:2FF4:0000) *** Attempting to flash, please dont 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写入→reset复位之后键盘从 DFU 退出、以新固件重新上线。注意RP2040 设备不需要 QMK Toolbox见 flashing 文档的 UF2 章节。5.3 命令行烧录全平台Linux 用户或偏好命令行的用户直接用 CLI它会根据键盘配置自动选择烧录方式qmk flash或显式指定qmk flash -kb my_keyboard -km my_keymapqmk flash会检查键盘的bootloader配置然后按对应 bootloaderatmel-dfu、stm32-dfu、rp2040 等执行烧写——你不需要知道键盘用的是哪种 bootloader。若板子未配置 bootloader 或没有受支持的烧录目标会看到WARNING: This boards bootloader is not specified or is not supported by the :flash target at this time.此时需要手动指定 bootloader详见 Flashing Firmware 参考文档。bootloader 无法被检测时可先运行qmk doctor获取常见问题的修复建议。6. 测试与后续恭喜固件已写入键盘。测试通常很直接逐个按键确认输出符合预期QMK Configurator 的 test 模式可以可视化验证每个键的响应即使键盘当前没跑 QMK 也能用于对比。仍有问题时可浏览 FAQ构建 FAQ、键位 FAQ、调试 FAQ或到社区交流并参考 测试与调试指南。7. 进阶学习资源教程之外官方把学习材料汇总在 Syllabus 与 Learning Resources 两页分类包括命令行入门教程、必知 Linux 命令、基础 Unix 命令文本编辑器编辑器选择入门、代码编辑器VS Code、Sublime TextGit通用教程、Git 飞行规则、交互式分支练习——配合 Git 工作流文档 使用可维护自己的qmk_firmwarefork 与 keymap 分支QMK 本体理解 QMK 架构understanding_qmk.md、键位系统keymap.md、层系统feature_layers.md、宏feature_macros.md等主题文档。流程速查表阶段命令说明安装 CLIcurl -fsSL https://install.qmk.fm \| shWindows/macOS/Linux 通用FreeBSD 用 pkg初始化环境qmk setup克隆仓库、安装工具链提示基本答y设置默认qmk config user.keyboardkb/user.keymapkm可选简化后续命令创建 keymapqmk new-keymap [-kb kb]复制 default 到keymaps/名字/编译qmk compile [-kb kb -km km]产物.hex/.bin拷贝到仓库根目录烧录qmk flash [-kb kb -km km]自动识别 bootloader失败看 flashing 参考 或qmk doctor【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考