QMK固件开发指南：构建您的第一个固件

一、构建您的第一个固件

既然您已经成功搭建了构建环境，现在就可以开始创建属于自己的自定义固件了！在本指南中，我们将在三个核心工具之间协同工作：文件管理器、文本编辑器以及终端窗口。建议您同时保持这三个程序处于打开状态，直到完成整个固件开发流程并对成果感到满意为止。

二、配置构建环境默认值（可选但推荐）

通过合理配置构建环境默认值，可以显著简化QMK开发流程，让整个体验更加流畅高效。让我们立即开始这一优化步骤！

大多数QMK新手通常只拥有一把机械键盘。您可以使用以下命令将其设置为默认键盘，从而避免每次都需要指定键盘型号。例如，要将默认键盘设置为clueboard/66/rev4：

qmk config user.keyboard=clueboard/66/rev4

专业提示：

keyboard参数的值是相对于keyboards目录的路径。上面的示例对应的是qmk_firmware/keyboards/clueboard/66/rev4目录。如果您不确定自己键盘的路径，可以运行qmk list-keyboards查看所有支持的键盘列表。

您还可以设置默认键盘映射名称，大多数开发者会使用自己的GitHub用户名作为键盘映射名称：

qmk config user.keymap=<github_username>

三、创建专属键盘映射

要创建个性化键盘映射，您需要基于默认映射创建一个副本。如果您已按上述步骤配置了构建环境，可以通过QMK CLI轻松完成这一操作：

qmk new-keymap

如果尚未配置环境默认值，或者您拥有多把键盘，可以指定具体的键盘名称：

qmk new-keymap -kb <keyboard_name>

执行上述命令后，您将看到类似下面的输出：

Ψ Created a new keymap called <github_username> in: /home/me/qmk_firmware/keyboards/clueboard/66/rev3/keymaps/<github_username>.

这就是您新创建的键盘映射文件位置。一般来说，键盘的默认映射文件可能是.json格式或.c格式。如果您的键盘映射是JSON文件，可以使用QMK提供的json2c工具将其转换为C文件。

四、编辑键盘映射文件

在您喜欢的文本编辑器中打开keymap.c文件。在这个文件中，您将找到控制键盘行为的核心结构。一般而言，文件顶部会有一些宏定义（defines）和枚举类型（enums），它们使键盘映射更易于理解和维护。

继续向下查看，您会找到一行关键代码：

const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {

这一行标志着图层（Layers）列表的起始位置。在此之下，您将看到包含LAYOUT的行，它们代表各个图层的开始。每个图层下方则是构成该特定图层的按键列表。

警告：

编辑键盘映射文件时，务必注意不要错误地添加或删除任何逗号。如果出现逗号错误，固件将无法编译，并且排查这类语法错误可能相当困难。

五、按需定制键盘布局

这一步的实现方式完全取决于您的个人需求和喜好。您可以进行一些小的改动来解决使用中的痛点，也可以彻底重新设计整个键盘布局。QMK支持最多32个图层，您可以根据需要添加或删除图层。

QMK提供了丰富的功能选项，以下是一些适合初学者上手的核心功能：

基本键码：常规按键功能
Quantum键码：QMK特有的高级功能
Mod-Tap/Layer-Tap：按住触发一个功能，轻触触发另一个功能
鼠标控制键：直接从键盘控制光标移动

专业提示：

在熟悉键盘映射工作原理的过程中，建议保持每次修改的规模较小。较大的更改会使问题调试变得更加复杂。采用渐进式改进策略通常是最佳实践。

六、构建您的自定义固件

当您完成键盘映射的修改后，需要构建固件文件。返回到终端窗口，运行编译命令：

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)