6 步搭好 QMK 固件编译环境从装 CLI 到出第一个 hex【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmwareQMK 是机械键盘的开源固件QMK 开发环境搭建要解决的事情只有一件让你电脑上的编译器能把键盘的键位代码keymap即哪个键位映射到什么动作的配置文件打包成芯片能执行的 .hex 固件文件。装完之后一条qmk compile就能出固件全程不用再手动折腾依赖。一、先选路线四平台推荐装法一张表先判断你现在用哪个系统——装法完全不同别照抄别人系统的命令。平台推荐方式为什么选它注意点WindowsQMK MSYS 安装包MSYS2 CLI 工具链打包成一个安装包安装路径保持默认方便 PATH 生效macOSHomebrew Tapbrew 自动处理全部依赖Apple Silicon 首次构建偏慢Linux / WSLpip 或 uv 装 QMK CLI装法最灵活发行版差异只在一行依赖命令尽量选主流发行版FreeBSDpkg 包系统社区维护尽力支持条件允许时优先前三种平台⚠️ FreeBSD 的支持来自社区而非官方维护者稳定性不作保证以官方文档为准。动手前的最低配置项目最低线推荐值内存4GB8GB 起磁盘空闲Windows 2GB / Linux 10GB5GB 以上网络能下载安装包稳定连接中途别断二、装 QMK CLI一个安装包或一条命令QMK CLI 是后面所有操作的入口工具拉仓库、装工具链、编译、刷写全靠它。各平台确认机器上有 Git 和 Python 3 之后按下面的路线走。Windows装 QMK MSYS从 QMK 官网的下载页拿到 QMK MSYS 安装包双击后按向导走三步选默认安装目录、勾选创建开始菜单快捷方式、把终端入口加入 Windows Terminal。安装过程可以临时关掉杀毒软件避免误报卡住进度。装完打开 QMK MSYS 终端跑一遍版本检查——GCC、AVR-GCC、Python、Git 四个版本号都打出来说明基础环境齐了# 逐个确认四个核心组件是否就位 gcc --version avr-gcc --version python --version git --versionmacOS走 Homebrew先确认 brew 可用brew --version有输出即可再添加 QMK 官方 tap 并安装 CLI# 加源后安装依赖会跟着一起装好 brew tap qmk/qmk brew install qmk/qmk/qmk这条命令会连带装好 Python 3.9、Git 以及 AVR 和 ARM 交叉编译器。M 系列芯片的机器没有现成的 ARM runner 二进制包工具链要在本地编译多等 30~60 分钟是正常现象别中途掐掉。Linux / WSL先补依赖再装 CLI各发行版先装系统依赖按你的包管理器取对应一行发行版依赖命令Ubuntu / Debiansudo apt install -y git python3-pip python3-venv build-essential libusb-1.0-0-dev libudev-dev pkg-configFedora / RHEL 系sudo dnf install -y git python3-pip python3-virtualenv gcc make libusb1-devel libudev-devel pkgconfigArch / Manjarosudo pacman -S --needed --noconfirm git python-pip python-virtualenv base-devel libusb udev pkgconf⚠️ 发行版软件源里现成的 qmk 包普遍过时不建议用包管理器装 CLI改用下面两种正规方式之一# 方式 Apip 用户级安装装到 ~/.local/bin python3 -m pip install --user qmk # 方式 B用 uv 装进隔离环境需先装好 uv 工具 uv tool install qmkArch 用户也可以走sudo pacman -S qmk或从 AUR 拿qmk-git开发版。FreeBSDpkg 一把梭基础工具、Python、AVR/ARM 工具链、刷写工具分四组装齐# 基础开发工具 sudo pkg install -y git wget gmake gcc zip unzip diffutils # Python 环境 sudo pkg install -y python3 py39-pip # AVR 工具链Atmel 芯片 sudo pkg install -y avr-binutils avr-gcc avr-libc # ARM 工具链STM32 等芯片 sudo pkg install -y arm-none-eabi-binutils arm-none-eabi-gcc arm-none-eabi-newlib # 刷写工具 sudo pkg install -y avrdude dfu-programmer dfu-util最后安装 CLI并把用户级 bin 目录挂进 PATHsudo python3 -m pip install qmk echo export PATH$HOME/.local/bin:$PATH ~/.bashrc source ~/.bashrcwhich qmk能返回路径这一步就算通了。三、初始化仓库qmk setup 在干什么装好 CLI 之后所有平台的下一步是同一条命令。它负责克隆固件仓库、装齐工具链、写入配置一路按 y 通过即可# 克隆仓库 装工具链 建配置一路按 y qmk setup想把仓库放到别的位置或者贡献者要用自己的 fork可以带参数qmk setup -H ~/qmk_firmware_custom # 指定仓库存放路径 qmk setup github用户名/qmk_firmware # 用个人 fork手动 clone 的话仓库地址是https://gitcode.com/GitHub_Trending/qm/qmk_firmware。WSL 用户特别注意仓库要放在 WSL 内部文件系统里放 /mnt 下的 Windows 盘上访问会慢到怀疑人生。终端提示 setup 完成、没有红色报错这一步过关。四、首次编译验证清单编译前确认对应芯片族的工具链在位按你的发行版取对应一列芯片族代表芯片Ubuntu/DebianFedoraArchAVRArduino 系列sudo apt install -y avr-libc avrdude binutils-avr gcc-avrsudo dnf install -y avr-libc avrdude avr-gcc avr-binutilssudo pacman -S avr-libc avrdude avr-gccARMSTM32 系列sudo apt install -y gcc-arm-none-eabi binutils-arm-none-eabisudo dnf install -y arm-none-eabi-gcc arm-none-eabi-binutilssudo pacman -S arm-none-eabi-gcc arm-none-eabi-binutils然后用示例键盘跑通一次完整编译。-kb传键盘在 keyboards/ 目录下的相对路径-km传键映射名# 不确定自己键盘叫什么先列出全部受支持的型号 qmk list-keyboards | head -10 # 编译 Clueboard 66% 的默认键映射 qmk compile -kb clueboard/66/rev3 -km default成功的信号是尾部打出这几行具体数字会有出入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] * The firmware size is fine - 26356/28672 (2316 bytes free)✅ 看到 The firmware size is fine 就说明工具链、代码生成器、链接器整条链路全通了这一步卡住很正常多半是工具链缺了一族回去对表补装即可。五、进阶配置默认键盘与仓库搬家把常用值写进配置以后编译键位就不用每次带参数# 一次性写入默认键盘、默认键映射、用户名 qmk config user.keyboardclueboard/66/rev4 user.keymapdefault user.nameyour_username配置项含义示例值user.keyboard默认编译的键盘路径clueboard/66/rev4user.keymap默认键映射名defaultuser.nameGitHub 用户名your_username想给固件仓库换家macOS 和 Linux 下直接设环境变量export QMK_HOME~/custom_qmk_firmware # 不设时默认是 ~/qmk_firmware日常维护三件事macOS 上brew update brew upgrade qmk更新 CLI进固件仓库git pull拉新代码编译报奇怪的缺件时qmk git-submodule刷新子模块再重跑qmk setup -y。六、排错速查表症状大概率原因处理动作qmk: command not found~/.local/bin 不在 PATHecho export PATH$HOME/.local/bin:$PATH ~/.bashrc source ~/.bashrcHomebrew 装的 qmk 找不到brew 未注入 shell 环境echo eval $(/opt/homebrew/bin/brew shellenv) ~/.zshrc source ~/.zshrcWSL 里刷写看不到 USB 键盘WSL 默认不直通 USBWindows 端winget install usbipd后用usbipd list拿设备 IDusbipd bind -b ID绑定WSL 端sudo usbip attach -r 127.0.0.1 -b ID接管Linux 上键盘识别异常缺 udev 权限规则写SUBSYSTEMSusb, ATTRS{idVendor}feed, MODE:0666到 /etc/udev/rules.d/50-qmk.rules再sudo udevadm control --reload-rules sudo udevadm trigger编译中途报缺文件子模块没拉全qmk git-submodule后重跑qmk setup -yM 系列 Mac 装得特别久无 ARM 二进制包在本地编译工具链等 30~60 分钟中途别 CtrlC顺手给终端加点料# 补全 别名日常能少敲一半字 echo eval $(register-python-argcomplete qmk) ~/.bashrc echo alias qmk-compileqmk compile ~/.bashrc echo alias qmk-flashqmk flash ~/.bashrc source ~/.bashrc七、下一步路线图找到自己的键盘qmk list-keyboards里定位型号进 keyboards/ 对应目录看默认 keymap 长什么样改自己的键位参照 官方入门文档 的建键位章节从 default 键映射抄一份再动手改把固件刷进键盘按 刷写指南 操作Windows/macOS 推荐图形工具 QMK Toolbox命令行党用qmk flash深挖 CLI所有命令参数详见 CLI 文档提速建议仓库放 SSD、编译期把 QMK 目录加进杀毒白名单速度立竿见影【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 6 步搭好 QMK 固件编译环境：从装 CLI 到出第一个 hex
6 步搭好 QMK 固件编译环境从装 CLI 到出第一个 hex【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmwareQMK 是机械键盘的开源固件QMK 开发环境搭建要解决的事情只有一件让你电脑上的编译器能把键盘的键位代码keymap即哪个键位映射到什么动作的配置文件打包成芯片能执行的 .hex 固件文件。装完之后一条qmk compile就能出固件全程不用再手动折腾依赖。一、先选路线四平台推荐装法一张表先判断你现在用哪个系统——装法完全不同别照抄别人系统的命令。平台推荐方式为什么选它注意点WindowsQMK MSYS 安装包MSYS2 CLI 工具链打包成一个安装包安装路径保持默认方便 PATH 生效macOSHomebrew Tapbrew 自动处理全部依赖Apple Silicon 首次构建偏慢Linux / WSLpip 或 uv 装 QMK CLI装法最灵活发行版差异只在一行依赖命令尽量选主流发行版FreeBSDpkg 包系统社区维护尽力支持条件允许时优先前三种平台⚠️ FreeBSD 的支持来自社区而非官方维护者稳定性不作保证以官方文档为准。动手前的最低配置项目最低线推荐值内存4GB8GB 起磁盘空闲Windows 2GB / Linux 10GB5GB 以上网络能下载安装包稳定连接中途别断二、装 QMK CLI一个安装包或一条命令QMK CLI 是后面所有操作的入口工具拉仓库、装工具链、编译、刷写全靠它。各平台确认机器上有 Git 和 Python 3 之后按下面的路线走。Windows装 QMK MSYS从 QMK 官网的下载页拿到 QMK MSYS 安装包双击后按向导走三步选默认安装目录、勾选创建开始菜单快捷方式、把终端入口加入 Windows Terminal。安装过程可以临时关掉杀毒软件避免误报卡住进度。装完打开 QMK MSYS 终端跑一遍版本检查——GCC、AVR-GCC、Python、Git 四个版本号都打出来说明基础环境齐了# 逐个确认四个核心组件是否就位 gcc --version avr-gcc --version python --version git --versionmacOS走 Homebrew先确认 brew 可用brew --version有输出即可再添加 QMK 官方 tap 并安装 CLI# 加源后安装依赖会跟着一起装好 brew tap qmk/qmk brew install qmk/qmk/qmk这条命令会连带装好 Python 3.9、Git 以及 AVR 和 ARM 交叉编译器。M 系列芯片的机器没有现成的 ARM runner 二进制包工具链要在本地编译多等 30~60 分钟是正常现象别中途掐掉。Linux / WSL先补依赖再装 CLI各发行版先装系统依赖按你的包管理器取对应一行发行版依赖命令Ubuntu / Debiansudo apt install -y git python3-pip python3-venv build-essential libusb-1.0-0-dev libudev-dev pkg-configFedora / RHEL 系sudo dnf install -y git python3-pip python3-virtualenv gcc make libusb1-devel libudev-devel pkgconfigArch / Manjarosudo pacman -S --needed --noconfirm git python-pip python-virtualenv base-devel libusb udev pkgconf⚠️ 发行版软件源里现成的 qmk 包普遍过时不建议用包管理器装 CLI改用下面两种正规方式之一# 方式 Apip 用户级安装装到 ~/.local/bin python3 -m pip install --user qmk # 方式 B用 uv 装进隔离环境需先装好 uv 工具 uv tool install qmkArch 用户也可以走sudo pacman -S qmk或从 AUR 拿qmk-git开发版。FreeBSDpkg 一把梭基础工具、Python、AVR/ARM 工具链、刷写工具分四组装齐# 基础开发工具 sudo pkg install -y git wget gmake gcc zip unzip diffutils # Python 环境 sudo pkg install -y python3 py39-pip # AVR 工具链Atmel 芯片 sudo pkg install -y avr-binutils avr-gcc avr-libc # ARM 工具链STM32 等芯片 sudo pkg install -y arm-none-eabi-binutils arm-none-eabi-gcc arm-none-eabi-newlib # 刷写工具 sudo pkg install -y avrdude dfu-programmer dfu-util最后安装 CLI并把用户级 bin 目录挂进 PATHsudo python3 -m pip install qmk echo export PATH$HOME/.local/bin:$PATH ~/.bashrc source ~/.bashrcwhich qmk能返回路径这一步就算通了。三、初始化仓库qmk setup 在干什么装好 CLI 之后所有平台的下一步是同一条命令。它负责克隆固件仓库、装齐工具链、写入配置一路按 y 通过即可# 克隆仓库 装工具链 建配置一路按 y qmk setup想把仓库放到别的位置或者贡献者要用自己的 fork可以带参数qmk setup -H ~/qmk_firmware_custom # 指定仓库存放路径 qmk setup github用户名/qmk_firmware # 用个人 fork手动 clone 的话仓库地址是https://gitcode.com/GitHub_Trending/qm/qmk_firmware。WSL 用户特别注意仓库要放在 WSL 内部文件系统里放 /mnt 下的 Windows 盘上访问会慢到怀疑人生。终端提示 setup 完成、没有红色报错这一步过关。四、首次编译验证清单编译前确认对应芯片族的工具链在位按你的发行版取对应一列芯片族代表芯片Ubuntu/DebianFedoraArchAVRArduino 系列sudo apt install -y avr-libc avrdude binutils-avr gcc-avrsudo dnf install -y avr-libc avrdude avr-gcc avr-binutilssudo pacman -S avr-libc avrdude avr-gccARMSTM32 系列sudo apt install -y gcc-arm-none-eabi binutils-arm-none-eabisudo dnf install -y arm-none-eabi-gcc arm-none-eabi-binutilssudo pacman -S arm-none-eabi-gcc arm-none-eabi-binutils然后用示例键盘跑通一次完整编译。-kb传键盘在 keyboards/ 目录下的相对路径-km传键映射名# 不确定自己键盘叫什么先列出全部受支持的型号 qmk list-keyboards | head -10 # 编译 Clueboard 66% 的默认键映射 qmk compile -kb clueboard/66/rev3 -km default成功的信号是尾部打出这几行具体数字会有出入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] * The firmware size is fine - 26356/28672 (2316 bytes free)✅ 看到 The firmware size is fine 就说明工具链、代码生成器、链接器整条链路全通了这一步卡住很正常多半是工具链缺了一族回去对表补装即可。五、进阶配置默认键盘与仓库搬家把常用值写进配置以后编译键位就不用每次带参数# 一次性写入默认键盘、默认键映射、用户名 qmk config user.keyboardclueboard/66/rev4 user.keymapdefault user.nameyour_username配置项含义示例值user.keyboard默认编译的键盘路径clueboard/66/rev4user.keymap默认键映射名defaultuser.nameGitHub 用户名your_username想给固件仓库换家macOS 和 Linux 下直接设环境变量export QMK_HOME~/custom_qmk_firmware # 不设时默认是 ~/qmk_firmware日常维护三件事macOS 上brew update brew upgrade qmk更新 CLI进固件仓库git pull拉新代码编译报奇怪的缺件时qmk git-submodule刷新子模块再重跑qmk setup -y。六、排错速查表症状大概率原因处理动作qmk: command not found~/.local/bin 不在 PATHecho export PATH$HOME/.local/bin:$PATH ~/.bashrc source ~/.bashrcHomebrew 装的 qmk 找不到brew 未注入 shell 环境echo eval $(/opt/homebrew/bin/brew shellenv) ~/.zshrc source ~/.zshrcWSL 里刷写看不到 USB 键盘WSL 默认不直通 USBWindows 端winget install usbipd后用usbipd list拿设备 IDusbipd bind -b ID绑定WSL 端sudo usbip attach -r 127.0.0.1 -b ID接管Linux 上键盘识别异常缺 udev 权限规则写SUBSYSTEMSusb, ATTRS{idVendor}feed, MODE:0666到 /etc/udev/rules.d/50-qmk.rules再sudo udevadm control --reload-rules sudo udevadm trigger编译中途报缺文件子模块没拉全qmk git-submodule后重跑qmk setup -yM 系列 Mac 装得特别久无 ARM 二进制包在本地编译工具链等 30~60 分钟中途别 CtrlC顺手给终端加点料# 补全 别名日常能少敲一半字 echo eval $(register-python-argcomplete qmk) ~/.bashrc echo alias qmk-compileqmk compile ~/.bashrc echo alias qmk-flashqmk flash ~/.bashrc source ~/.bashrc七、下一步路线图找到自己的键盘qmk list-keyboards里定位型号进 keyboards/ 对应目录看默认 keymap 长什么样改自己的键位参照 官方入门文档 的建键位章节从 default 键映射抄一份再动手改把固件刷进键盘按 刷写指南 操作Windows/macOS 推荐图形工具 QMK Toolbox命令行党用qmk flash深挖 CLI所有命令参数详见 CLI 文档提速建议仓库放 SSD、编译期把 QMK 目录加进杀毒白名单速度立竿见影【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考