QMK 开发环境搭建指南：从第一条命令到编译出第一个 .hex
【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware
这篇指南带你从零搭好 QMK 开发环境，并把第一版键盘固件编译出来。你只需要一台 Windows、macOS、Linux（或 WSL）或 FreeBSD 的机器，全程跟着敲命令就行。卡住了也不用慌，文章后半部分按报错症状排了障，直接对号入座。
30 秒速查：核心命令一览
赶时间？看完这张表就能动手，后面的内容当补充：
| 步骤 | Windows | macOS | Linux / WSL | FreeBSD |
|---|---|---|---|---|
| 安装 | 官网下载 QMK MSYS 安装包，双击装好 | brew install qmk/qmk/qmk | python3 -m pip install --user qmk | python3 -m pip install qmk |
| 初始化 | qmk setup | qmk setup | qmk setup | qmk setup |
| 验证 | qmk compile -kb clueboard/66/rev3 -km default | 同左 | 同左 | 同左 |
各平台装 CLI 之前，还有一步装工具链的活，Windows 和 macOS 帮你干完了，Linux 和 FreeBSD 要自己敲几条包管理命令，见下文对应小节。
你装的到底是什么：QMK 编译环境的四层结构
QMK 编译环境不是某一个工具，而是一条四个环节的链：
- 包管理器：Windows 上的 MSYS2 pacman、macOS 的 Homebrew、Linux 的 apt / dnf / pacman、FreeBSD 的 pkg，负责拉取所有依赖包；
- 交叉编译工具链：
avr-gcc（专门编译 Atmel AVR 芯片固件的编译器）和arm-none-eabi-gcc（编译 ARM 芯片的交叉编译器）。之所以叫"交叉"，是因为代码最终跑在键盘芯片上，而不是你的电脑里； - CLI 入口：
qmk命令行工具，它替你管着固件仓库的位置、git 子模块和构建配置； - 固件仓库：
qmk_firmware，所有键盘定义、键位图和驱动代码都在这里。
知道这条链之后，后面遇到编译失败你就能先定位"断在哪一环"，再去对应的位置排障，而不是从头开始怀疑一切。
Windows 上装 QMK MSYS：一个安装包带走工具链
前置
- Windows 10 或 11（64 位）
- 约 5 GB 空闲磁盘
- 安装过程中把杀毒软件放一边，别让它抢戏
装
- 去 QMK 官网的下载区，拿到 QMK MSYS 的安装程序。它把 MSYS2、git、Python 和两条工具链打成一个包，不用自己拼装。
- 双击安装程序，路径保持默认（一般是
C:\QMK_MSYS）。 - 安装向导里有一项"Add to Windows Terminal"，勾上，后面在 Windows Terminal 里直接就能开。
装完打开 QMK MSYS 终端，验证工具链就位：
qmk --version avr-gcc --version预期能看到 qmk 的版本号，以及一行avr-gcc (GCC) 12.x之类的输出。
init
qmk setup它会问你是否克隆固件仓库，输入 "y" 即可；路径提示直接回车用默认值。完成后~/qmk_firmware就出现了。
⚠️ 杀毒软件可能把安装包标成可疑文件。它是官方安装包，放行即可；更彻底的做法是把 QMK_MSYS 整个目录加进排除列表，编译会明显变快。
切到 macOS 这边，路径管理交给 Homebrew，更省心。
macOS 用 Homebrew Tap 装 QMK CLI
前置
- macOS 12 及以上
- 已安装 Homebrew（终端里
brew --version有输出即可）
装
两条命令的事：
- 添加 QMK 官方 tap（可以理解为给 Homebrew 加一个 QMK 专用的配方源）：
brew tap qmk/qmk- 安装 CLI 本体：
brew install qmk/qmk/qmk预期：依赖列表刷过之后，终端安静下来、回到提示符，没有任何报错。
- 验证一下：
qmk --versioninit
qmk setup提示是否克隆仓库时输 "y"，仓库会落在~/qmk_firmware，路径提示直接回车。
⚠️ Apple Silicon（M 系列芯片）上 setup 会明显更久，因为 AVR 和 ARM 工具链没有现成的 arm64 二进制包，需要在本地编译，预留 30 到 60 分钟。期间终端没输出是正常的。
Linux 与 WSL 下装 QMK CLI 和工具链
前置
- 发行版较新（Ubuntu 20.04+ / Fedora 38+ / Arch 等主流版）
- 已安装 python3 和 git
装
- 先装基础依赖：
sudo apt update sudo apt install -y build-essential libusb-1.0-0-dev pkg-configFedora 用dnf，包名换成gcc make libusb1-devel pkgconfig，以你的发行版文档为准。
- 装 CLI 本体：
python3 -m pip install --user qmk预期：Successfully installed qmk-x.x.x。
- 再补上工具链，缺一条对应一条：
sudo apt install -y gcc-avr binutils-avr avr-libc avrdude sudo apt install -y gcc-arm-none-eabi两条都装，才能同时覆盖 AVR 和 ARM 两种芯片的键盘。
init
qmk setup输入 "y" 确认克隆，路径回车用默认的~/qmk_firmware。
⚠️ 如果装完敲
qmk提示找不到命令，九成是~/.local/bin不在 PATH 里，直接跳第⑤节第一条。
FreeBSD 这边同样走包管理器的路子：pkg install装 git、gmake、python3、avr-gcc、arm-none-eabi-gcc和avrdude，再python3 -m pip install qmk，最后qmk setup，流程与 Linux 相同。OpenBSD、NetBSD 思路一致，包名以各自系统的包列表为准。
第一次编译：一条命令生成 .hex
环境是否真的通了，编译一把最诚实。进仓库，挑一台仓库里真实存在的键盘，用默认键位：
cd ~/qmk_firmware qmk compile -kb clueboard/66/rev3 -km default⚠️ 注意
-kb和-km是"短横线 kb"，不是下划线，这行别抄错。
一切顺利的话，终端最后几行长这样：
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 - 17216/32256 (15040 bytes free)看到Linking和Creating load file都是[OK]，并且工作目录下多了.hex和.elf文件，恭喜，你的 QMK 开发环境算是正式开张了。哪一步挂了？翻到下面按症状对号入座。
按症状排障：报错原文在这里对号入座
| 症状 | 一句话原因 | 解法 |
|---|---|---|
qmk: command not found | 用户 bin 目录不在 PATH | 见下方第一条 |
| 编译报子模块缺失 | 仓库子模块没拉下来 | qmk git-submodule |
| 编译规则不匹配 | 仓库与工具链版本错位 | 更新仓库后重跑 setup |
| 刷固件提示权限不足 | 没有 USB 访问权限 | 加 udev 规则 |
| WSL 里设备不存在 | USB 没透传进 Linux | usbipd 三步透传 |
| ARM 键盘编译失败 | 只装了 AVR 工具链 | 补装arm-none-eabi-gcc |
qmk: command not found
- 现象：
bash: qmk: command not found - 原因：pip 装到了
~/.local/bin，但这个目录不在 PATH 里。 - 解法：
export PATH="$HOME/.local/bin:$PATH" echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc which qmk最后一行能打印出路径就修好了。
子模块缺失
- 现象：编译时报
... is not a valid submodule之类的错误。 - 原因：固件仓库依赖 git 子模块，单独 clone 或更新时没带上。
- 解法：
qmk git-submodule qmk compile -kb clueboard/66/rev3 -km default再不行就把仓库删掉重新qmk setup，干净利落。
工具链版本冲突
- 现象：
No rule to make target '.build/...'。 - 原因：固件仓库更新了，本机的
qmk setup没跟着重新跑，工具链版本对不上。 - 解法：
cd ~/qmk_firmware git pull qmk setupsetup 会把工具链补齐到仓库要求的版本，然后再编译。
USB 权限不足
- 现象：刷固件时
libusb_error: LIBUSB_ERROR_ACCESS。 - 原因：Linux 没给你当前用户访问这个 USB 设备的权限。
- 解法：
echo 'SUBSYSTEMS=="usb", ATTRS{idVendor}=="feed", MODE:="0666"' | sudo tee /etc/udev/rules.d/50-qmk.rules sudo udevadm control --reload-rules拔插一下设备，再刷一次试试。
WSL 里设备不存在
- 现象：
lsusb里根本看不到你的键盘。 - 原因：键盘插在 Windows 侧，WSL 的 Linux 内核看不到它。
- 解法：用 Windows 自带的 usbipd 把设备"递"给 WSL（包名以官方文档为准）：
usbipd list usbipd bind --busid 2-4sudo usbip attach -r 127.0.0.1 -b 2-4WSL 里再lsusb，应该能看到设备了。
编译 ARM 键盘报找不到工具链
- 现象：
arm-none-eabi-gcc: command not found。 - 原因：QMK 同时支持 AVR 和 ARM 两类芯片，两条工具链是分开装的，装过 AVR 不等于装过 ARM。
- 解法：按 Linux 小节第 3 步补装
gcc-arm-none-eabi，然后重编。
环境跑通之后做什么
- 改键位：从键位图（keymap）入手，参考 keymap 文档 把 F13 换成你喜欢的键；
- 刷固件：编译出的 .hex 需要写进键盘，流程见 flashing 文档；
- 完整构建细节：QMK 官方构建指南 里有 make 参数的逐项说明；
- 进阶方向：宏、OLED 屏幕、编码器这些 Quantum 功能，等你第一版键位稳定后再碰不迟。
环境跑通了，接下来就是调键位的快乐时光了。
【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
