【QMK键盘】零基础搭建QMK固件环境完全攻略

【QMK键盘】零基础搭建QMK固件环境完全攻略

前言

Hello键盘发烧友们！今天给大家带来一篇零基础QMK固件环境搭建教程。作为键圈老玩家，我深知掌握QMK对于客制化键盘爱好者的重要性。无论你是想实现独特按键功能、炫酷RGB灯效，还是打造完全符合个人工作习惯的键盘布局，QMK固件都是你必备的"魔法工具"。

QMK（Quantum Mechanical Keyboard）是一款强大的开源键盘固件，它允许用户深度自定义键盘的各种功能，包括按键映射、宏定义、RGB灯效、OLED显示屏内容等。通过QMK的魔力，一把普通键盘可以变身为你的专属生产力工具，大幅提升工作效率和使用体验。

一、QMK固件支持的芯片概览

在开始环境搭建前，我们先了解QMK兼容哪些主控芯片。目前市面上常见的QMK兼容芯片包括：

1. STM32F10x系列：性能强劲，资源丰富，常见于高端客制化键盘
2. Atmega32u4：客制化键盘界的"常青树"，绝大多数入门到中端键盘的首选芯片
3. Atmega32u2：功能略少于32u4，但仍满足大多数键盘项目需求

拓展知识：选择键盘芯片时，需要综合考虑键盘的IO需求量、内存大小和处理能力。大型键盘或需要复杂功能（如RGB矩阵、OLED屏幕等）的键盘往往需要STM32等高性能芯片，而60%或更小配列的简单键盘使用APM32就完全够用。近两年，越来越多的键盘开始采用RP2040（树莓派Pico的芯片），它提供双核处理能力和更高性价比，值得关注。还有一些基于RISC-V架构的芯片也开始进入键盘领域，未来可期。

如需查看更全面的兼容芯片列表，可以访问QMK官方文档的MCU选择页面。

二、QMK环境搭建详解

QMK环境搭建是制作自定义键盘固件的"入门仪式"。为了让新手朋友也能轻松上手，我们直接使用QMK官方维护的MSYS集成环境，这比手动配置工具链简单得多。

1. 获取QMK MSYS

首先，从QMK官网下载MSYS集成环境：

1. 访问QMK官方网站
   

2. 页面可以右键点击翻译，方便阅读

3. 下载QMK MSYS最新版安装包

4. 点击后缀为.exe的安装文件开始下载
   

实用技巧：如果官网下载速度太慢（国内访问GitHub资源确实有点困难），我已经将安装包上传到百度网盘，文章最后有分享链接，大家可以直接获取。这个安装包会定期更新，但基本功能都是一样的。

2. 安装QMK MSYS

下载完安装包后，按照以下步骤进行安装：

1. 双击运行下载好的安装包，启动安装向导
   

2. 选择安装路径（推荐安装到非系统盘，如D盘，避免C盘空间不足）

3. 安装过程中记得勾选"创建桌面快捷方式"选项，方便日后使用
   

4. 安装完成后，桌面上会出现QMK MSYS的快捷图标
   

拓展知识：MSYS实际上是Windows系统上模拟POSIX环境的工具集，QMK MSYS特别定制版整合了编译QMK固件所需的全部工具链，包括gcc编译器、make构建工具和git版本控制等，极大简化了环境配置过程。相比于使用WSL或虚拟机安装Linux系统，这种方式对Windows用户特别友好，无需了解Linux命令即可完成基本操作。

3. 获取QMK固件源码

接下来，我们需要获取QMK固件源码。这里介绍三种获取方法，你可以根据自己的情况选择最适合的：

方法一：通过MSYS命令行获取（新手推荐）

1. 双击打开桌面上的QMK MSYS终端

2. 输入命令：qmk setup -H D:/QMK（这将把QMK固件放在D盘的QMK文件夹中，你可以根据需要修改路径）
   

3. 当询问是否克隆QMK固件仓库时，输入y确认

4. 当询问是否将该目录设为QMK_HOME时，输入y确认

5. 耐心等待克隆完成（根据网络状况，这个过程可能需要几分钟到几十分钟不等）

重要提示：指定的目录必须是不存在的，系统会自动创建。如果该文件夹已存在，即使是空文件夹也需要先删除再操作。

克隆完成后，可以输入qmk doctor命令检查QMK环境状态，确认是否已准备就绪。如果终端显示"QMK is ready to go"，说明环境设置成功，可以开始你的QMK之旅了！

进阶技巧：如果你后续需要使用其他QMK衍生固件（比如VIAL或VIA），可以使用cd命令切换到相应目录。例如cd D:/VIAL-QMK会切换到VIAL固件目录。关于VIAL/VIA的区别与选择，我会在后续教程中详细介绍。

方法二：通过Git手动克隆（适合Git用户）

如果你熟悉Git操作，也可以选择手动克隆方式：

1. 首先确保已安装Git Bash（若未安装，可从git-scm.com下载）
2. 打开你想要存放QMK固件的目录（如D:\）
3. 在空白处右击，选择"Git Bash Here"打开Git终端
4. 输入克隆命令：git clone https://github.com/qmk/qmk_firmware
5. 进入qmk_firmware/lib目录，依次克隆所有子模块：

   git clone https://github.com/qmk/ChibiOS
   git clone https://github.com/qmk/ChibiOS-Contrib
   git clone https://github.com/qmk/googletest
   git clone https://github.com/qmk/lufa
   git clone https://github.com/qmk/printf
   git clone https://github.com/qmk/uGFX
   git clone https://github.com/qmk/v-usb
   

网络问题解决方案：在国内网络环境下，直接克隆GitHub仓库可能会遇到超时或速度极慢的问题。建议使用以下几种方法提高连接效率：

1. 使用FastGithub、Dev-Sidecar等加速工具
2. 启用Steam++的GitHub加速功能
3. 使用科学上网工具（如果有条件）
4. 使用国内Git镜像站（如Gitee）先fork后再克隆

这几种方法效果因人而异，建议都尝试一下找到最适合自己网络环境的方法。

方法三：使用预下载的压缩包（最简单快捷）

如果上述两种方法都遇到困难，可以使用我在文末提供的网盘链接，直接下载打包好的QMK固件源码，解压到你指定的目录即可。

4. 编译测试

环境搭建完成后，我们进行一个简单的编译测试，确保整个工具链正常运作：

1. 打开桌面上的QMK MSYS快捷方式，启动终端
2. 如果使用方法一设置了QMK_HOME，系统会自动进入QMK目录；如果使用方法二或三，需要手动切换到QMK固件目录：cd D:/QMK/QMKexe（替换为你的实际路径）
3. 选择一个内置键盘进行测试编译，例如：make planck/rev6:default或make cx60:default
4. 等待编译过程完成
5. 编译成功后，可以在.build文件夹中找到生成的hex/bin固件文件

如果编译过程顺利完成，并且终端显示类似以下信息，就说明环境搭建成功了：

Copying cx60_default.bin to qmk_firmware folder                          [OK]
Checking file size of cx60_default.bin                                   [OK]
 * The firmware size is fine - 25800/65536 (39736 bytes free)

所有状态显示为[OK]表示编译正常，编译出的固件大小也在芯片容量范围内。

三、QMK环境配置优化

成功安装QMK MSYS后，我们还可以进行一些额外配置，让固件开发过程更加顺畅：

1. 选择合适的代码编辑工具

开发QMK固件需要一个好用的代码编辑器。以下是几款推荐的编辑器：

• Visual Studio Code（强烈推荐）：轻量级但功能强大，支持QMK专用插件，可以安装"QMK Tools"插件获得语法高亮和编译快捷功能
• Sublime Text：响应速度快，适合快速编辑
• Notepad++：轻量级，对中文支持良好，适合简单修改

注意：无论选择哪款编辑器，一定要确保它能保存为纯文本格式。Windows自带的记事本可能会添加额外格式信息，不推荐使用。选择编辑器的关键是看自己的习惯，VSCode虽然功能最全面，但如果你只需要做简单修改，Notepad++的上手速度可能更快。

2. 配置QMK构建环境变量

如果你在前面使用了qmk setup命令，QMK环境变量已经自动配置好了。如果没有，或者想手动设置，可以按照以下步骤操作：

1. 打开QMK MSYS终端
2. 运行命令：qmk setup
3. 按照提示操作，大多数情况下对所有提问回答y即可
4. 系统会自动下载依赖项并配置必要的环境变量

拓展知识：QMK环境变量主要包括QMK_HOME（指向QMK固件源码目录）和QMK_FIRMWARE_DIR（与QMK_HOME相同，用于兼容旧脚本）。正确设置这些环境变量后，你可以在任何目录下运行qmk命令，而不必每次都切换到固件目录。

3. 测试构建系统

环境配置完成后，我们再做一次测试，确认构建系统工作正常：

1. 在QMK MSYS终端中输入以下命令格式编译一个默认键盘映射：

   qmk compile -kb <keyboard> -km default
   

2. 例如，编译Clueboard 66%键盘的固件：

   qmk compile -kb clueboard/66/rev3 -km default
   

3. 编译成功后会看到类似以下输出：

   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)
   

实用技巧：除了qmk compile命令外，你也可以使用传统的make命令编译固件，例如make planck/rev6:default。两种方式效果相同，但qmk compile是较新的命令格式，更加直观易用。

如果你想查看QMK支持的所有键盘列表，可以使用qmk list-keyboards命令。这对于找到自己键盘的正确名称非常有用。

在编译自己的键盘映射前，建议先用qmk new-keymap命令创建一个基于默认配置的个人映射，这样可以避免直接修改默认文件。

总结与展望

恭喜你！至此，你已成功搭建了QMK固件开发环境，为定制专属键盘迈出了关键的第一步！接下来，你可以开始探索创建自己的键盘映射、设计独特功能和绚丽灯效的奇妙旅程。

QMK固件的真正魅力在于它的无限可能性。通过自定义按键映射，你可以根据个人习惯优化键盘布局；通过设置宏，可以一键触发复杂的按键组合；通过配置RGB灯效，可以让键盘在视觉上也与众不同。掌握QMK，你的键盘将不再只是简单的输入设备，而是能够真正提升工作效率的得力助手。

在我的下一篇教程中，我将详细讲解如何创建和编译个人键盘映射，敬请期待！

文件分享：本教程所涉及的所有文件已打包上传至网盘：
链接: https://pan.baidu.com/s/1L4xZf-t-OekgnYE-r7Ltkg?pwd=im3h
提取码: im3h

键盘小课堂：QMK固件的强大之处在于它是完全开源的，由全球键盘爱好者共同维护。如果你在使用过程中发现了新功能需求或bug，可以通过GitHub提交issue或PR，为这个伟大的项目贡献自己的力量。对于中文用户，也可以加入国内的QMK交流群，与志同道合的键友们一起探讨和学习。