QMK 开发环境搭建指南：从第一条命令到编译出第一个 .hex

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 秒速查核心命令一览赶时间看完这张表就能动手后面的内容当补充步骤WindowsmacOSLinux / WSLFreeBSD安装官网下载 QMK MSYS 安装包双击装好brew install qmk/qmk/qmkpython3 -m pip install --user qmkpython3 -m pip install qmk初始化qmk setupqmk setupqmk setupqmk 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 或 1164 位约 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之类的输出。initqmk 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 --versioninitqmk setup提示是否克隆仓库时输 y仓库会落在~/qmk_firmware路径提示直接回车。⚠️ Apple SiliconM 系列芯片上 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 两种芯片的键盘。initqmk 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 没透传进 Linuxusbipd 三步透传ARM 键盘编译失败只装了 AVR 工具链补装arm-none-eabi-gccqmk: 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 SUBSYSTEMSusb, 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），仅供参考