QMK开发环境搭建指南：Eclipse和VS Code详解
QMK开发环境搭建指南：Eclipse和VS Code详解
前言
各位键盘DIY爱好者们，今天跟大家分享如何搭建QMK固件开发环境。无论你是想定制自己的客制化键盘固件，还是对开源键盘固件开发感兴趣，这篇教程都能帮你搞定开发环境配置。本文将详细介绍如何使用Eclipse和VS Code两种IDE来进行QMK固件开发，让你的开发体验更加流畅高效！
为什么要使用IDE而不是纯文本编辑器？
相比纯文本编辑器，使用IDE进行开发有以下明显优势：
- 智能代码补全：减少拼写错误，提高编码速度
- 便捷的代码导航：快速定位函数和变量定义
- 强大的重构工具：轻松进行代码结构优化
- 自动化构建：无需频繁使用命令行
- Git图形界面：更直观地进行版本控制
- 静态代码分析：提前发现潜在问题
- 丰富的辅助功能：包括调试、代码格式化、调用层次结构显示等
下面我们就分别介绍两种主流IDE的配置方法。
第一部分：Eclipse配置指南
1. 准备工作
在开始配置Eclipse之前，请确保：
- 已经按照QMK官方教程的"入门"部分搭建好基础构建环境
- 能够使用
qmk compile命令成功构建固件 - 已安装Java 8或更高版本（Eclipse是Java应用程序）
2. 安装Eclipse及必要插件
2.1 下载并安装Eclipse CDT
提示：即使你已经安装了其他版本的Eclipse，建议重新安装CDT版本以保持轻量级并避免不必要的工具干扰。
安装步骤：
- 前往Eclipse官网
- 选择"Eclipse IDE for C/C++ Developers"版本
- 下载后解压到你选择的位置（这将创建一个
eclipse文件夹）
或者直接下载Eclipse IDE for C/C++ Developers。
2.2 首次启动Eclipse
- 点击"Launch"按钮启动Eclipse（若手动解压，则双击可执行文件）
- 当提示选择工作区时，选择一个存放Eclipse元数据的目录
注意：不要选择qmk_firmware目录，应该选择其父文件夹或其他空文件夹
- 启动后，点击右上角的"Workbench"按钮切换到工作台视图
2.3 安装必要插件
A. AVR插件（关键）
该插件使Eclipse能够理解AVR C代码，是必不可少的：
- 按照使用更新站点的说明进行安装
- 同意未签名内容的安全警告继续安装
B. 控制台ANSI转义插件
此插件用于正确显示QMK makefile生成的彩色构建输出：
- 打开"Help > Eclipse Marketplace…"
- 搜索"ANSI Escape in Console"
- 点击插件的"Install"按钮
- 按照指示完成安装并同意安全警告
安装完毕后，根据提示重启Eclipse。
3. 为QMK配置Eclipse项目
3.1 导入QMK项目
- 点击"File > New > Makefile Project with Existing Code"
- 在下一个界面：
- 选择克隆QMK存储库的目录作为"Existing Code Location"
- 可选择为项目指定不同名称（如"QMK"或"Quantum"）
- 选择"AVR-GCC"工具链
- 保持其余部分默认设置，然后点击"Finish"
注意：如果使用自定义名称导入项目出现问题，可尝试保留默认项目名称（即目录名称，可能是
qmk_firmware）。
项目加载后，就可以通过左侧的"Project Explorer"轻松浏览文件。
3.2 配置键盘构建目标
接下来我们将项目的默认make目标从all更改为特定键盘和键盘映射组合：
- 将编辑器选项卡聚焦在项目上
- 打开"Project > Properties"窗口，选择"C/C++ Build > Behavior"列表条目
- 将所有已启用版本的默认文本字段从
all更改为特定键盘目标，如kinesis/kint41:stapelberg - 通过选择"Project > Clean…"验证设置是否有效
第二部分：VS Code配置指南
Visual Studio Code（简称VS Code）作为一款轻量级但功能强大的编辑器，越来越受到开发者喜爱。下面介绍如何配置VS Code进行QMK开发。
1. 安装VS Code
Windows环境准备
-
安装Git for Windows
- 禁用除
Git LFS和Check daily for Git for Windows updates以外的所有选项 - 将默认编辑器设置为"Use Visual Studio Code as Git’s default editor"
- 选择"Use Git from Git Bash only"选项
- 对于"Choosing HTTPS transport backend"，任一选项均可
- 选择"Checkout as-is, commit Unix-style line endings"选项（QMK使用Unix风格）
- 其他选项保留默认设置
- 禁用除
-
可选安装Windows的Git凭据管理器，提供更好的凭证管理
-
下载并安装VS Code
配置MSYS2终端集成（Windows环境）
- 点击"File > Preferences > Settings"
- 单击右上角的
{}按钮打开settings.json文件 - 设置文件内容如下（如已有内容，则添加并用逗号分隔）：
{"terminal.integrated.profiles.windows": {"QMK_MSYS": {"path": "C:/QMK_MSYS/usr/bin/bash.exe","env": {"MSYSTEM": "MINGW64","CHERE_INVOKING": "1"},"args": ["--login"]}},"terminal.integrated.cursorStyle": "line"
}
提示：如果MSYS2安装在其他位置，需修改对应路径为正确位置。
- 使用快捷键Ctrl+`调出终端，或通过"View > Terminal"打开
其他操作系统安装
对于Linux、macOS等系统，只需下载安装VS Code即可，无需额外配置。
2. 安装扩展
VS Code的强大功能很大程度上依赖于其丰富的扩展。以下是推荐安装的扩展：
- Git Extension Pack：安装一系列Git相关工具，方便与QMK固件一起使用
- clangd（可选）：C/C++语言服务器，提供智能补全等功能
- EditorConfig for VS Code（可选）：帮助代码符合QMK编码规范
- GitHub Markdown Preview（可选）：使Markdown预览更接近GitHub效果
- VS Live Share Extension Pack（可选）：允许他人远程访问你的工作区提供帮助
安装任何扩展后，请重启VS Code。
3. 配置QMK开发环境
- 点击"File > Open Folder"，打开从GitHub克隆的QMK固件文件夹
- 点击"File > Save Workspace As…"保存工作区
配置智能补全和代码导航
通过标准的compile_commands.json数据库，可以让VS Code的clangd扩展正确识别包含路径和定义：
- 运行命令生成配置：
qmk generate-compilation-database -kb <keyboard> -km <keymap> - 在VS Code中，按
Ctrl+Shift+P（macOS：Command+Shift+P）打开命令面板 - 输入并选择"clangd: Download Language Server"（仅需在安装clangd扩展后执行一次）
- 再次打开命令面板，输入并选择"clangd: Restart Language Server"
现在，你已准备好在VS Code中进行QMK固件开发了！
第三部分：使用VS Code调试ARM MCU
如果你的键盘使用ARM MCU（如STM32系列），并且有Black Magic Probe调试器，可以配置VS Code进行固件调试。
1. 硬件连接
确保Black Magic Probe与MCU的电气连接正确，至少需要连接NRST、SWDIO、SWCLK和GND引脚。
2. 安装调试扩展
安装VS Code扩展：Cortex-Debug，为VS Code添加ARM Cortex目标调试支持。
3. 配置调试目标
在项目根目录创建或编辑.vscode/launch.json文件，添加以下内容：
{"version": "0.2.0","configurations": [{"name": "Black Magic Probe (OneKey Proton-C)","type": "cortex-debug","request": "launch","cwd": "${workspaceRoot}","executable": "${workspaceRoot}/.build/handwired_onekey_proton_c_default.elf","servertype": "bmp","BMPGDBSerialPort": "COM4","svdFile": "Q:\\svd\\STM32F303.svd","device": "STM32F303","v1": false,"windows": {"armToolchainPath": "C:\\QMK_MSYS\\mingw64\\bin"}}]
}
需要根据你的设备修改以下参数：
"name"：描述性名称，自定义即可"cwd"：QMK固件存储库根目录路径"executable"：生成的ELF文件路径（位于.build目录）"BMPGDBSerialPort"：Windows下的COM端口或Linux/macOS的设备路径"svdFile"：[可选] SVD文件路径，定义MCU寄存器布局"device"：MCU名称，与SVD文件匹配"armToolchainPath"：[可选] ARM工具链安装路径（主要用于Windows）
4. 修改键盘配置启用调试
编辑键盘的rules.mk文件，添加以下内容：
# Enable debug information in the final binaries
DEBUG_ENABLE = yes
# Disable optimisations for debugging purposes
LTO_ENABLE = no
OPT = g
5. 构建并调试
- 通过常规命令构建并刷写固件：
qmk compile ...和qmk flash ... - 在VS Code中切换到调试视图（侧边栏中的"播放"按钮旁）
- 在侧边栏顶部下拉列表中选择创建的调试目标
- 点击绿色播放按钮开始调试
此时应该可以看到调试器已连接并正在执行固件，断点和变量监视功能也应正常工作。
常见问题与解决方案
-
Windows环境下GDB路径问题：
QMK固件在Windows上通常使用QMK MSYS进行编译，需要在gdb设置中指定正确路径。你可能需要在VSCode Cortex-Debug用户设置中修改GDB路径为：C:\\QMK_MSYS\\mingw64\\bin\\gdb-multiarch.exe -
Eclipse项目导入失败：
尝试使用默认项目名称（即目录名称，通常是qmk_firmware）重新导入 -
调试器无法连接：
- 检查硬件连接是否正确
- 尝试不同的COM端口（通常会创建两个串行端口设备）
- 验证固件是否正确编译并启用了调试信息
拓展知识：QMK固件开发进阶技巧
-
使用版本控制管理键盘配置：
为不同键盘创建Git分支，方便管理多种配置和回退更改 -
利用宏定义优化代码：
QMK支持强大的宏定义功能，可极大简化复杂功能的实现 -
Custom Matrix实现：
了解键盘矩阵原理，可以自定义扫描方式实现更复杂的功能 -
OLED显示屏开发：
QMK支持集成OLED显示，可显示层信息、键盘状态等 -
无线键盘开发：
结合BLE或其他无线模块，实现无线键盘功能
总结
通过本教程，我们详细介绍了如何使用Eclipse和VS Code两种IDE配置QMK固件开发环境。无论你偏好哪种IDE，都能获得比纯文本编辑器更高效的开发体验。调试功能的加入更是让固件问题定位变得简单直观。
希望这篇教程对你的QMK开发之旅有所帮助！如有任何问题，欢迎在评论区留言交流。
觉得教程有用的话，别忘了点赞、收藏、关注哦！后续会带来更多键盘开发相关教程~