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版本以保持轻量级并避免不必要的工具干扰。

安装步骤：

1. 前往Eclipse官网
2. 选择"Eclipse IDE for C/C++ Developers"版本
3. 下载后解压到你选择的位置（这将创建一个eclipse文件夹）

或者直接下载Eclipse IDE for C/C++ Developers。

2.2 首次启动Eclipse

1. 点击"Launch"按钮启动Eclipse（若手动解压，则双击可执行文件）
2. 当提示选择工作区时，选择一个存放Eclipse元数据的目录

   注意：不要选择qmk_firmware目录，应该选择其父文件夹或其他空文件夹

3. 启动后，点击右上角的"Workbench"按钮切换到工作台视图

2.3 安装必要插件

A. AVR插件（关键）

该插件使Eclipse能够理解AVR C代码，是必不可少的：

1. 按照使用更新站点的说明进行安装
2. 同意未签名内容的安全警告继续安装

B. 控制台ANSI转义插件

此插件用于正确显示QMK makefile生成的彩色构建输出：

1. 打开"Help > Eclipse Marketplace…"
2. 搜索"ANSI Escape in Console"
3. 点击插件的"Install"按钮
4. 按照指示完成安装并同意安全警告

安装完毕后，根据提示重启Eclipse。

3. 为QMK配置Eclipse项目

3.1 导入QMK项目

1. 点击"File > New > Makefile Project with Existing Code"
2. 在下一个界面：
   • 选择克隆QMK存储库的目录作为"Existing Code Location"
   • 可选择为项目指定不同名称（如"QMK"或"Quantum"）
   • 选择"AVR-GCC"工具链
   • 保持其余部分默认设置，然后点击"Finish"

注意：如果使用自定义名称导入项目出现问题，可尝试保留默认项目名称（即目录名称，可能是qmk_firmware）。

项目加载后，就可以通过左侧的"Project Explorer"轻松浏览文件。

3.2 配置键盘构建目标

接下来我们将项目的默认make目标从all更改为特定键盘和键盘映射组合：

1. 将编辑器选项卡聚焦在项目上
2. 打开"Project > Properties"窗口，选择"C/C++ Build > Behavior"列表条目
3. 将所有已启用版本的默认文本字段从all更改为特定键盘目标，如kinesis/kint41:stapelberg
4. 通过选择"Project > Clean…"验证设置是否有效

第二部分：VS Code配置指南

Visual Studio Code（简称VS Code）作为一款轻量级但功能强大的编辑器，越来越受到开发者喜爱。下面介绍如何配置VS Code进行QMK开发。

1. 安装VS Code

Windows环境准备

1. 安装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风格）
   • 其他选项保留默认设置

2. 可选安装Windows的Git凭据管理器，提供更好的凭证管理

3. 下载并安装VS Code

配置MSYS2终端集成（Windows环境）

1. 点击"File > Preferences > Settings"
2. 单击右上角的{}按钮打开settings.json文件
3. 设置文件内容如下（如已有内容，则添加并用逗号分隔）：

{"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安装在其他位置，需修改对应路径为正确位置。

4. 使用快捷键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开发环境

1. 点击"File > Open Folder"，打开从GitHub克隆的QMK固件文件夹
2. 点击"File > Save Workspace As…"保存工作区

配置智能补全和代码导航

通过标准的compile_commands.json数据库，可以让VS Code的clangd扩展正确识别包含路径和定义：

1. 运行命令生成配置：qmk generate-compilation-database -kb <keyboard> -km <keymap>
2. 在VS Code中，按Ctrl+Shift+P（macOS：Command+Shift+P）打开命令面板
3. 输入并选择"clangd: Download Language Server"（仅需在安装clangd扩展后执行一次）
4. 再次打开命令面板，输入并选择"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. 构建并调试

1. 通过常规命令构建并刷写固件：qmk compile ...和qmk flash ...
2. 在VS Code中切换到调试视图（侧边栏中的"播放"按钮旁）
3. 在侧边栏顶部下拉列表中选择创建的调试目标
4. 点击绿色播放按钮开始调试

此时应该可以看到调试器已连接并正在执行固件，断点和变量监视功能也应正常工作。

常见问题与解决方案

1. Windows环境下GDB路径问题：
   QMK固件在Windows上通常使用QMK MSYS进行编译，需要在gdb设置中指定正确路径。你可能需要在VSCode Cortex-Debug用户设置中修改GDB路径为：C:\\QMK_MSYS\\mingw64\\bin\\gdb-multiarch.exe

2. Eclipse项目导入失败：
   尝试使用默认项目名称（即目录名称，通常是qmk_firmware）重新导入

3. 调试器无法连接：

   • 检查硬件连接是否正确
   • 尝试不同的COM端口（通常会创建两个串行端口设备）
   • 验证固件是否正确编译并启用了调试信息

拓展知识：QMK固件开发进阶技巧

1. 使用版本控制管理键盘配置：
   为不同键盘创建Git分支，方便管理多种配置和回退更改

2. 利用宏定义优化代码：
   QMK支持强大的宏定义功能，可极大简化复杂功能的实现

3. Custom Matrix实现：
   了解键盘矩阵原理，可以自定义扫描方式实现更复杂的功能

4. OLED显示屏开发：
   QMK支持集成OLED显示，可显示层信息、键盘状态等

5. 无线键盘开发：
   结合BLE或其他无线模块，实现无线键盘功能

总结

通过本教程，我们详细介绍了如何使用Eclipse和VS Code两种IDE配置QMK固件开发环境。无论你偏好哪种IDE，都能获得比纯文本编辑器更高效的开发体验。调试功能的加入更是让固件问题定位变得简单直观。

希望这篇教程对你的QMK开发之旅有所帮助！如有任何问题，欢迎在评论区留言交流。

---

觉得教程有用的话，别忘了点赞、收藏、关注哦！后续会带来更多键盘开发相关教程~