从 0 到 1 搭好 QMK 固件编译环境3 条路径跑通第一次编译【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware第一次接触 QMK这篇讲清 Windows、macOS、Linux 全平台搭建 QMK 固件编译环境的路径选择读完你能独立编译出第一个键盘固件。动手前先确认你的起点机械键盘固件开发听起来唬人其实前置条件不高一台能跑命令行的电脑、几 GB 磁盘、稳定网络。不同平台的差异主要在于依赖怎么装先对表看一眼你的情况平台最低配置预计耗时需要管理员权限吗Windows 10/114GB 内存、5GB 空闲磁盘约 30 分钟安装器需要macOS 10.154GB 内存、10GB 空闲磁盘40 分钟起Apple Silicon 更久一般不需要Ubuntu/Debian/Fedora4GB 内存、10GB 空闲磁盘约 30 分钟sudo装依赖时WSL 2同 LinuxWindows 10 21H2约 30 分钟内核升级时需要FreeBSD 134GB 内存、10GB 空闲磁盘约 40 分钟pkg install需要⚠️ 三条最容易翻车的预备动作先做掉能省后面一半时间⚠️ Windows 用户把实时保护先静音一会儿安装器、交叉工具链都可能被误报装完记得加进排除列表。⚠️ 磁盘留足 10GB子模块加 ARM/AVR 两条工具链比你想象的占地方。⚠️ WSL 用户先想清楚刷固件的事WSL 2 不直通 USB要么用 usbipd 绑设备要么忍忍用 WSL 1。选择你的安装路径先别急着敲命令往下看。同样是装环境有人五分钟搞定有人折腾一下午差别全在路径选择。对号入座路径想要零配置愿意手动装依赖适合谁A打包环境越高越好完全不用Windows 桌面用户B包管理器 CLI一般装十几个包macOS / Linux / WSLC手动工具链无所谓全手动FreeBSD 等其余系统判断逻辑一句话Windows 走 AmacOS 和 Linux/WSL 走 B其他系统或者工具链已经齐了想自己掌控的走 C。拿不准就从 B 开始它是覆盖面最广的一条路。按路径逐步搭建三条路径最终都收敛到同一件事仓库就位、工具链就位、qmk命令能用。整体流程长这样路径 A用 QMK MSYS 打包环境Windows 首选Windows:从 QMK 官方的 MSYS 发行页下载最新安装器双击运行。安装时建议默认路径C:\QMK_MSYS添加到 Windows Terminal 勾上之后开终端就能直接用。装完打开 QMK MSYS 终端跑这一条qmk setup qmk --versionqmk setup会克隆固件仓库、装 AVR/ARM 工具链提示基本一路Y就行。它的好处是 git、Python、两条工具链都捆在一起你唯一要做的事就是别中途断网。如果qmk报找不到echo $PATH看一眼确认C:/QMK_MSYS/usr/bin在里面不在就手动补一行export PATH即可。路径 B包管理器装依赖 QMK CLI这条路是自己搭积木但每块都有标准件照单抓药就行。macOS:brew tap qmk/qmk brew install qmk/qmk/qmk qmk setuptap 里打包了 CLI 和它需要的所有依赖一条brew install收尾。Apple Silicon 机器上工具链要在本地现编qmk setup会多跑 30-60 分钟泡杯茶的时间。Linux WSL:先装基础依赖按发行版三选一sudo apt install -y git python3-pip python3-venv build-essential libusb-1.0-0-dev libudev-dev pkg-configsudo dnf install -y git python3-pip python3-virtualenv gcc make libusb1-devel libudev-devel pkgconfigsudo pacman -S --needed git python-pip python-virtualenv base-devel libusb udev pkgconf再装 CLI 并初始化python3 -m pip install --user qmk qmk setupqmk setup默认把仓库克隆到~/qmk_firmware想换位置加-H参数。装完which qmk没反应的话把export PATH$HOME/.local/bin:$PATH写进你的 shell 配置里。Windows:除非你非要用原生 MSYS2否则别走这条路径 A 更省事。路径 C手动装交叉编译工具链FreeBSD 和少数小众系统没有现成的 CLI 打包渠道思路就变成把编译器一个个装齐再直接克隆仓库。命令都短只是多敲几回。FreeBSD 及其他:sudo pkg install -y git python3 gmake avr-gcc avr-binutils avr-libcsudo pkg install -y arm-none-eabi-gcc arm-none-eabi-binutils arm-none-eabi-newlibsudo pkg install -y avrdude dfu-utilOpenBSD/NetBSD 的包名基本同名把pkg换成pkg_add或pkgin即可个别 ARM 工具链要从 ports 树里编。各平台对照一下平台AVR 工具链ARM 工具链烧录工具FreeBSDavr-gccavr-binutilsavr-libcarm-none-eabi-*三件套avrdudedfu-utilOpenBSD / NetBSD同名包pkg_add/pkgin安装部分需从 ports 源码编译avrdude工具链齐活后克隆仓库记得带上子模块git clone --recurse-submodules https://gitcode.com/GitHub_Trending/qm/qmk_firmware cd qmk_firmware make setupmake setup会替你装齐构建所需的其余依赖。装完用两条命令验尸版本能打出来就说明编译器可用avr-gcc --version arm-none-eabi-gcc --versionLinux 上如果后面刷固件认不到设备顺手跑一句sudo ./util/install_udev.sh仓库里自带了 udev 规则脚本。第一次编译用最小键盘验证环境先拿仓库里最轻量的测试键盘null开刀它没有真实硬件纯粹用来验证工具链qmk compile -kb null -km default编译顺利的话结尾应该是这几行Linking: .build/null_default.elf Creating load file for flashing: .build/null_default.hex Checking file size of null_default.hex * The firmware size is fine输出对不对得上过一遍自检清单✅ 命令正常退出全程没有红色报错✅ 当前目录或.build/下出现了null_default.hex✅ 没有出现command not found之类的字样✅ 没有avr-gcc、arm-none-eabi-gcc缺失报错✅qmk list-keyboards能刷出长长一串键盘列表hex 文件到手恭喜你这台机器正式具备机械键盘固件开发的完整能力了。卡住了这里是最常见的 5 个坑排错最怕没方向。九成问题落在这五行里先对号别盲目重装现象大概率原因一行修复命令qmk: command not found~/.local/bin不在 PATHexport PATH$HOME/.local/bin:$PATHgit clone卡住或子模块报错网络抖动 / 子模块没拉全qmk git-submodule编译时报avr-gcc: command not foundAVR 工具链没装上qmk setup -yLinux 上刷固件认不到键盘缺 udev 规则sudo ./util/install_udev.shWSL 2 里看不到键盘WSL 2 不直通 USB在 Windows 侧用usbipd绑定设备下一步从能编译到能刷固件环境只是门票下面是接下来几天你会反复翻的几个地方keyboards/目录每张板子的硬件定义都在这找到你的型号后先看它的info.json确认芯片和布局编译命令里的-kb参数就照着它填。users/目录自定义 userspace 放这里个人键位的 C 代码、自定义宏都往这扔构建系统会自动把它编进固件。util/drivers.txt支持的芯片驱动清单选板子之前先扫一眼能避开一堆芯片不受支持的弯路。docs/newbs_getting_started.md官方新手文档刷写那一章配着 QMK ToolboxWindows/macOS 的图形化工具一起看最顺。刷写本身命令行直接qmk flash -kb null -km default或者用图形化工具点按钮两条路效果一样。编译跑通那天别急着收工——去keyboards/里翻出你的那块板子改掉第一行键位刷进硬件听着咔哒声确认改动生效你就正式入坑了。【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
从 0 到 1 搭好 QMK 固件编译环境：3 条路径跑通第一次编译
从 0 到 1 搭好 QMK 固件编译环境3 条路径跑通第一次编译【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware第一次接触 QMK这篇讲清 Windows、macOS、Linux 全平台搭建 QMK 固件编译环境的路径选择读完你能独立编译出第一个键盘固件。动手前先确认你的起点机械键盘固件开发听起来唬人其实前置条件不高一台能跑命令行的电脑、几 GB 磁盘、稳定网络。不同平台的差异主要在于依赖怎么装先对表看一眼你的情况平台最低配置预计耗时需要管理员权限吗Windows 10/114GB 内存、5GB 空闲磁盘约 30 分钟安装器需要macOS 10.154GB 内存、10GB 空闲磁盘40 分钟起Apple Silicon 更久一般不需要Ubuntu/Debian/Fedora4GB 内存、10GB 空闲磁盘约 30 分钟sudo装依赖时WSL 2同 LinuxWindows 10 21H2约 30 分钟内核升级时需要FreeBSD 134GB 内存、10GB 空闲磁盘约 40 分钟pkg install需要⚠️ 三条最容易翻车的预备动作先做掉能省后面一半时间⚠️ Windows 用户把实时保护先静音一会儿安装器、交叉工具链都可能被误报装完记得加进排除列表。⚠️ 磁盘留足 10GB子模块加 ARM/AVR 两条工具链比你想象的占地方。⚠️ WSL 用户先想清楚刷固件的事WSL 2 不直通 USB要么用 usbipd 绑设备要么忍忍用 WSL 1。选择你的安装路径先别急着敲命令往下看。同样是装环境有人五分钟搞定有人折腾一下午差别全在路径选择。对号入座路径想要零配置愿意手动装依赖适合谁A打包环境越高越好完全不用Windows 桌面用户B包管理器 CLI一般装十几个包macOS / Linux / WSLC手动工具链无所谓全手动FreeBSD 等其余系统判断逻辑一句话Windows 走 AmacOS 和 Linux/WSL 走 B其他系统或者工具链已经齐了想自己掌控的走 C。拿不准就从 B 开始它是覆盖面最广的一条路。按路径逐步搭建三条路径最终都收敛到同一件事仓库就位、工具链就位、qmk命令能用。整体流程长这样路径 A用 QMK MSYS 打包环境Windows 首选Windows:从 QMK 官方的 MSYS 发行页下载最新安装器双击运行。安装时建议默认路径C:\QMK_MSYS添加到 Windows Terminal 勾上之后开终端就能直接用。装完打开 QMK MSYS 终端跑这一条qmk setup qmk --versionqmk setup会克隆固件仓库、装 AVR/ARM 工具链提示基本一路Y就行。它的好处是 git、Python、两条工具链都捆在一起你唯一要做的事就是别中途断网。如果qmk报找不到echo $PATH看一眼确认C:/QMK_MSYS/usr/bin在里面不在就手动补一行export PATH即可。路径 B包管理器装依赖 QMK CLI这条路是自己搭积木但每块都有标准件照单抓药就行。macOS:brew tap qmk/qmk brew install qmk/qmk/qmk qmk setuptap 里打包了 CLI 和它需要的所有依赖一条brew install收尾。Apple Silicon 机器上工具链要在本地现编qmk setup会多跑 30-60 分钟泡杯茶的时间。Linux WSL:先装基础依赖按发行版三选一sudo apt install -y git python3-pip python3-venv build-essential libusb-1.0-0-dev libudev-dev pkg-configsudo dnf install -y git python3-pip python3-virtualenv gcc make libusb1-devel libudev-devel pkgconfigsudo pacman -S --needed git python-pip python-virtualenv base-devel libusb udev pkgconf再装 CLI 并初始化python3 -m pip install --user qmk qmk setupqmk setup默认把仓库克隆到~/qmk_firmware想换位置加-H参数。装完which qmk没反应的话把export PATH$HOME/.local/bin:$PATH写进你的 shell 配置里。Windows:除非你非要用原生 MSYS2否则别走这条路径 A 更省事。路径 C手动装交叉编译工具链FreeBSD 和少数小众系统没有现成的 CLI 打包渠道思路就变成把编译器一个个装齐再直接克隆仓库。命令都短只是多敲几回。FreeBSD 及其他:sudo pkg install -y git python3 gmake avr-gcc avr-binutils avr-libcsudo pkg install -y arm-none-eabi-gcc arm-none-eabi-binutils arm-none-eabi-newlibsudo pkg install -y avrdude dfu-utilOpenBSD/NetBSD 的包名基本同名把pkg换成pkg_add或pkgin即可个别 ARM 工具链要从 ports 树里编。各平台对照一下平台AVR 工具链ARM 工具链烧录工具FreeBSDavr-gccavr-binutilsavr-libcarm-none-eabi-*三件套avrdudedfu-utilOpenBSD / NetBSD同名包pkg_add/pkgin安装部分需从 ports 源码编译avrdude工具链齐活后克隆仓库记得带上子模块git clone --recurse-submodules https://gitcode.com/GitHub_Trending/qm/qmk_firmware cd qmk_firmware make setupmake setup会替你装齐构建所需的其余依赖。装完用两条命令验尸版本能打出来就说明编译器可用avr-gcc --version arm-none-eabi-gcc --versionLinux 上如果后面刷固件认不到设备顺手跑一句sudo ./util/install_udev.sh仓库里自带了 udev 规则脚本。第一次编译用最小键盘验证环境先拿仓库里最轻量的测试键盘null开刀它没有真实硬件纯粹用来验证工具链qmk compile -kb null -km default编译顺利的话结尾应该是这几行Linking: .build/null_default.elf Creating load file for flashing: .build/null_default.hex Checking file size of null_default.hex * The firmware size is fine输出对不对得上过一遍自检清单✅ 命令正常退出全程没有红色报错✅ 当前目录或.build/下出现了null_default.hex✅ 没有出现command not found之类的字样✅ 没有avr-gcc、arm-none-eabi-gcc缺失报错✅qmk list-keyboards能刷出长长一串键盘列表hex 文件到手恭喜你这台机器正式具备机械键盘固件开发的完整能力了。卡住了这里是最常见的 5 个坑排错最怕没方向。九成问题落在这五行里先对号别盲目重装现象大概率原因一行修复命令qmk: command not found~/.local/bin不在 PATHexport PATH$HOME/.local/bin:$PATHgit clone卡住或子模块报错网络抖动 / 子模块没拉全qmk git-submodule编译时报avr-gcc: command not foundAVR 工具链没装上qmk setup -yLinux 上刷固件认不到键盘缺 udev 规则sudo ./util/install_udev.shWSL 2 里看不到键盘WSL 2 不直通 USB在 Windows 侧用usbipd绑定设备下一步从能编译到能刷固件环境只是门票下面是接下来几天你会反复翻的几个地方keyboards/目录每张板子的硬件定义都在这找到你的型号后先看它的info.json确认芯片和布局编译命令里的-kb参数就照着它填。users/目录自定义 userspace 放这里个人键位的 C 代码、自定义宏都往这扔构建系统会自动把它编进固件。util/drivers.txt支持的芯片驱动清单选板子之前先扫一眼能避开一堆芯片不受支持的弯路。docs/newbs_getting_started.md官方新手文档刷写那一章配着 QMK ToolboxWindows/macOS 的图形化工具一起看最顺。刷写本身命令行直接qmk flash -kb null -km default或者用图形化工具点按钮两条路效果一样。编译跑通那天别急着收工——去keyboards/里翻出你的那块板子改掉第一行键位刷进硬件听着咔哒声确认改动生效你就正式入坑了。【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
