QMK开发环境搭建3 条路径跑通你的第一次固件编译【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware读完后你会得到一个能用的 QMK开发环境搭建成果给一把键盘名和一个键位图名qmk compile就能吐出可直接刷写的 .hex。Windows、macOS、Linux / WSL、FreeBSD 都能走通三条路径任选其一。先说清楚QMK 编译到底要装哪几样别急着敲命令先把购物清单过一遍。QMK 编译的本质就是把仓库里的 C 代码翻译成芯片能执行的机器码再让你用一条命令拿到固件文件。最小依赖集就六样组件干嘛用的要不要装Git拉 qmk_firmware 仓库、管理子模块必须Python3.9QMK CLI 靠它跑编译命令本质是脚本必须AVR 工具链avr-gcc编译 Atmel ATmega32u4 这类老牌芯片键盘是 AVR 就要ARM 工具链arm-none-eabi-gcc编译 STM32 这类新芯片键盘是 ARM 就要QMK CLIqmk setup/qmk compile/qmk config的入口必须烧录工具QMK Toolbox / dfu-util / avrdude把固件写进键盘必须刷机环节两点说明多数键盘只用其中一类芯片查一下你键盘的 MCU 型号就能省掉另一套工具链不确定就都装体积不大。挑一条路把 QMK 装完三条路装出来的东西一样选你系统上最顺手的。路径一官方打包方案最省心Windows 首选装 QMK MSYS。安装器把 Git、Python、AVR 和 ARM 工具链全打包好了双击装完打开QMK MSYS终端就能用PATH 都不用操心。macOS 最省心用 Homebrew 装 QMK两行命令的事brew tap qmk/qmk brew install qmk/qmk/qmkApple SiliconM 系列上首次安装会明显慢这个架构没有现成的工具链二进制会本地编译预留 30~60 分钟别以为卡死了。Linux / WSL / FreeBSD 一行装官方 CLI 是 Python 包pip 直接搞定python3 -m pip install --user qmk路径二包管理器手动拼装官方包不覆盖你的发行版、或者你想自己掌控版本就手动来。Ubuntu / Debian两组命令走完全程先装通用依赖再装两套工具链sudo apt update sudo apt install -y git python3-pip build-essential libusb-1.0-0-dev libudev-dev pkg-config sudo apt install -y gcc-avr avr-libc avr-gcc gcc-arm-none-eabiFedora换成dnf install -y git python3-pip gcc make libusb1-devel avr-gcc arm-none-eabi-gccFreeBSD同理pkg install -y git python3 avr-gcc arm-none-eabi-gcc avrdude。看着包不少其实各司其职libusb / libudev 管 USB 通信build-essential 是宿主机 C 编译器。路径三隔离环境不污染系统 Python不想全局装、或者系统 Python 被发行版托管较新发行版上 pip 装会被 PEP 668 拒绝用隔离方式uv tool install qmk不想引入 uv 也行python3 -m venv qmk-venv建个虚拟环境再pip install qmk。Arch Linux 用户直接拿社区包yay -S qmk-git更省事。跑通第一次编译qmk setup → qmk compile 验证闭环✅ 装完别急着庆祝先验证闭环。第一条命令是 setup它会把固件仓库克隆下来本文基于的仓库为 https://gitcode.com/GitHub_Trending/qm/qmk_firmware并初始化全部子模块qmk setup第二条编译仓库里最小的键盘。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 - 24404/30720 (6316 bytes free)看到[OK]就是成了。从这一刻起你的机器就具备完整的机械键盘固件编译环境仓库里任意一把键盘都能编。完整编译流程可以看官方文档 docs/getting_started_make_guide.md。qmk compile 报错先看这张踩坑速查⚠️ 你大概率会碰到的问题别人早就碰过了直接对表现象高发平台一句解法qmk: command not found全平台把~/.local/bin加进 PATH重载 shell 配置安装器/构建被杀毒拦截Windows把 QMK_MSYS 目录加排除项装的时候关掉实时保护克隆仓库中途断网全平台重跑qmk setup它会续传拉了新代码后报缺文件全平台qmk git-submodule或重跑qmk setup -y刷机时提示 USB 权限拒绝Linux / WSL加一条 idVendor 为feed的 udev 规则放权首次编译巨慢macOS Apple Silicon工具链在本地编译等它跑完之后正常WSL 里看不到 USB 键盘WSL用 usbipd 从 Windows 侧把设备直通进来从能编译走到能刷写编出 .hex 只算完成一半另一半是把它写进键盘。Windows上最省事的是 QMK Toolbox选文件、点烧录结束。Linux / macOS走命令行STM32 用dfu-util、AVR 用avrdude流程见 docs/flashing.md。刷通之后马上能做的三件小事去keyboards/目录找到你板子的键位图开始改键qmk config user.keyboard你的键盘 user.keymap键位名设好默认值以后只敲qmk compile就够卡住了直接去 QMK 的 Discord 社区问比搜资料快。顺手调几个体验项 ⚡仓库放 SSDQMK 编译相当一部分时间在读写中间文件机械盘和 SSD 的差距肉眼可见Windows 编译时关实时保护或给仓库加排除项杀毒软件反复扫 .o 文件是 Windows 编译慢的头号原因内存4GB 能应付大多数板子编大型 ARM 板建议 8GBshell 别名alias cqmk compile每次敲命令省两下下一步就是打开 keyboards/ 找到和你硬件对得上的那把键盘开始改键位了。【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考