QMK开发环境手把手指南：四大系统30分钟编译出你的第一个键盘固件

QMK开发环境手把手指南：四大系统30分钟编译出你的第一个键盘固件

【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware

QMK 是面向 AVR 与 ARM 微控制器的开源机械键盘固件项目。这篇指南按"选型→安装→初始化→验证→排错"的统一主线，带你在 Windows、macOS、Linux/WSL 与 FreeBSD 上搭好完整的 QMK 键盘固件开发环境，每一步都给出可对照的成功标志，跑通后你就能编译仓库里任意一款键盘的固件。

先做决策：四个平台的安装方案对比

装之前花 30 秒对号入座，能少走一半弯路：

不管选哪条路，后面都要走同一套四步主线：装工具链 → 装 QMK CLI → 跑qmk setup→ 编译验证。下面先展开各平台的差异点，再讲通用步骤。

各平台安装差异点

Windows：QMK MSYS 一键装完

QMK MSYS 是基于 MSYS2 定制的整合环境，把编译 QMK 所需的一切预装到位。

1. 从 QMK 官方下载页获取最新安装程序，双击运行；
2. 安装位置保持默认C:\QMK_MSYS，勾选"添加到 Windows Terminal"方便日后调用；
3. 杀毒软件可能误报安装器，安装期间临时关闭实时保护即可；
4. 安装完成打开 QMK MSYS 终端，运行下面四条命令自检：

gcc --version avr-gcc --version python --version git --version

✅ 完成标志：四条命令都能打印出版本号，说明基础环境就绪。之后如需补装工具，用pacman -S <包名>即可，例如pacman -S mingw-w64-x86_64-nano。

macOS：Homebrew Tap 是最省事的路径

macOS 上不需要手动装任何编译器，Homebrew 的官方 tap 会处理全部依赖：

brew tap qmk/qmk brew install qmk/qmk/qmk

第二条命令会自动带上 Python 3.9+、Git 以及 AVR/ARM 交叉编译器。装完运行qmk --version验证。

⚠️ Apple Silicon（M 系列芯片）用户注意：工具链目前没有原生 ARM 二进制包，brew 会在本地现场编译，brew install的耗时会比 Intel Mac 多出 30–60 分钟，耐心等待即可。

如果装完提示qmk: command not found，是 Homebrew 路径没进 shell 配置，追加这两行后重开终端：

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc source ~/.zshrc

✅ 完成标志：which qmk能返回 brew 前缀下的可执行文件路径。

Linux / WSL：按发行版选包，CLI 走 pip

系统依赖因发行版而异，三套常用命令如下：

其中libusb和libudev是刷写固件时与 USB 设备通信用的，缺了编译能过但烧录会失败，务必装上。

AVR / ARM 交叉编译器的包名同样按发行版区分：

CLI 本身用 pip 装到用户目录（不需要 root）：

python3 -m pip install --user qmk

偏好隔离环境的可以改用uv tool install qmk；Arch 用户也可直接sudo pacman -S qmk。

✅ 完成标志：which qmk输出~/.local/bin/qmk；若提示找不到命令，把$HOME/.local/bin加进~/.bashrc的 PATH 再source一次。

WSL2 额外一步：键盘是硬件，物理上插在 Windows 上，需要透传给 WSL 才能刷写。在 Windows 端装usbipd（winget install usbipd），用usbipd list找到键盘设备 ID，usbipd bind -b <设备ID>绑定；WSL 内执行sudo usbip attach -r 127.0.0.1 -b <设备ID>。✅ 完成标志：WSL 内lsusb能看到键盘的 USB 条目。

FreeBSD 及其他类 Unix 系统（附录）

FreeBSD 走 pkg，命令很短：

sudo pkg update sudo pkg install -y git gmake gcc zip unzip python3 py39-pip sudo pkg install -y avr-binutils avr-gcc avr-libc sudo pkg install -y arm-none-eabi-binutils arm-none-eabi-gcc arm-none-eabi-newlib sudo pkg install -y avrdude dfu-util

OpenBSD 用doas pkg_add、NetBSD 用pkgin，模式相同：基础工具 + Python 3 + AVR/ARM 工具链 + 烧录工具。装完确认avr-gcc --version与arm-none-eabi-gcc --version都能输出版本号即可。

统一主线第一步：qmk setup 一键初始化

工具链就位后，所有平台执行同一条命令：

qmk setup

它会自动克隆 QMK 固件仓库（默认落在~/qmk_firmware）、初始化全部 Git 子模块（ChibiOS 等硬件抽象库都在子模块里）、并配置构建所需的环境。对所有交互式提示直接回车确认即可。

两个常用变体：

• 想用自己的 fork：qmk setup <你的用户名>/qmk_firmware
• 想自定义仓库位置：qmk setup -H ~/my_qmk

不想用 CLI 的，也可以手动克隆（记得带--recurse-submodules，否则子模块缺失会编译报错）：

git clone --recurse-submodules https://gitcode.com/GitHub_Trending/qm/qmk_firmware

✅ 完成标志：终端提示 setup 完成，且~/qmk_firmware目录下能看到keyboards/、quantum/等核心目录，lib/chibios子模块目录非空。

统一主线第二步：编译一个固件验证环境

验证用仓库内置的虚拟键盘null，它不依赖任何真实硬件，专门用来测编译链路：

qmk compile -kb null -km default

✅ 完成标志：输出中依次出现下面几行，并且固件大小检查通过：

Linking: .build/null_default.elf [OK] Creating load file for flashing: .build/null_default.hex [OK] * The firmware size is fine

想测真实键盘，把-kb换成具体型号即可，比如qmk compile -kb clueboard/66/rev3 -km default。不确定支持哪些键盘时，qmk list-keyboards | head -20先扫一眼列表。

高频坑点速查表

编译通过后，接下来做什么

• 把刚编出的.hex刷进键盘，流程见 刷写指南；Windows 上 DFU 模式识别异常时，参考 Zadig 驱动安装文档。
• 为自己的键盘写键位映射，从 键映射入门 开始，进阶功能查 键码参考。
• 习惯 Makefile 工作流的，可以跳过 CLI 直接用make，见 make 构建指南。
• 遇到编译报错先翻 构建 FAQ 和 CLI 命令手册，大部分问题都有现成答案。

【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware