QMK 开发环境搭建指南从装好依赖到跑通第一次固件编译【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmwareQMK Firmware 是支持 Atmel AVR 与 Arm USB 芯片的开源机械键盘固件。本指南带你完成 QMK 开发环境搭建选对平台方案、装齐依赖与工具链、跑通第一条 QMK 固件编译命令全程不需要键盘硬件。30 秒选路 ⚡先看这张表5 秒定位你该跳到哪一段平台推荐方案预估耗时难度跳到WindowsQMK MSYS 一体化环境15–30 分钟★☆☆下面第 1 个 H3macOSHomebrew Tap 装 QMK CLI10–20 分钟Apple Silicon 40–90 分钟★☆☆下面第 2 个 H3Linux / WSL系统包管理器 pip 装 CLI15–40 分钟★★☆下面第 3 个 H3FreeBSDpkg 装工具链 pip 装 CLI30–60 分钟★★☆下面第 4 个 H3四个平台最终殊途同归都得到qmk命令 一个 qmk_firmware 仓库 AVR/ARM 两套交叉编译器。区别只在谁帮你把这些装好。动手前先备齐这些不分平台先把这几件事确认掉前置条件用途必须稳定网络工具链和 git 子模块下载量不小中途断网会前功尽弃是≥5GB 可用磁盘仓库 两套工具链 编译缓存是Git 账号GitHub 或 GitCodefork 一份 qmk_firmwareqmk setup会克隆你的 fork之后改键位也能提 PR只编译可跳过命令行基础会用终端、认识export、sudo是键盘硬件编译固件完全不需要刷写阶段才用得上否上图这种手焊小键盘就是 QMK 的典型用户。但放心编译阶段一根线都不用焊等固件跑通了再碰硬件。按你的环境走Windows装好 QMK MSYS 只需 3 步# 1. 从 QMK 官方下载页拿到 QMK MSYS 安装包双击按向导装完 # 装到默认位置 C:\QMK_MSYS建议勾选添加到 Windows Terminal # 2. 从开始菜单启动 QMK MSYS 终端 # 3. 在终端里执行 qmk setup为什么这么装QMK MSYS 把 MSYS2、Python、Git、AVR-GCC、ARM-GCC 全部打包你不需要像 Linux 那样逐条装依赖装完即有完整 QMK 开发环境。qmk setup会克隆 qmk_firmware 仓库并核对工具链。提示是否克隆官方仓库时选Y位置用默认即可。之后在 Windows Terminal 里直接敲qmk就能用不用再切回 MSYS 老终端。一句话架构QMK MSYS MSYS2 基础环境 QMK CLI 交叉编译工具链相当于给 Windows 装了一个嵌入式编译发行版。macOS用 Homebrew Tap 装 QMK CLI # 没有 Homebrew 的话先按其官方说明安装然后验证 brew --version # 添加 QMK 官方 tap 并安装 CLI自动带出 Python、Git、工具链等依赖 brew tap qmk/qmk brew install qmk/qmk/qmk # 初始化环境 qmk setup几个要点tap 里的 formula 帮你把依赖图整个解开了手动装 Python 版本、AVR/ARM 编译器容易踩的坑brew 都替你绕过去了。Apple SiliconM 系列芯片上 setup 会明显变慢AVR 和 ARM 工具链没有现成的原生 ARM 二进制包需要本地编译多等 30–60 分钟是正常的别中途杀掉进程。不想把仓库放在默认~/qmk_firmware设置环境变量再跑 setupexport QMK_HOME~/custom_qmk_firmware qmk setupLinux / WSL装依赖 装 QMK CLI把工具链和 CLI 一次装齐按发行版选一段# ---- Ubuntu / Debian ---- sudo apt update sudo apt install -y git python3-pip python3-venv build-essential \ libusb-1.0-0-dev libudev-dev pkg-config \ avr-libc avrdude binutils-avr gcc-avr \ gcc-arm-none-eabi binutils-arm-none-eabi # ---- Fedora / RHEL 系 ---- sudo dnf install -y git python3-pip python3-virtualenv gcc make \ libusb1-devel libudev-devel pkgconfig \ avr-libc avrdude avr-gcc avr-binutils \ arm-none-eabi-gcc arm-none-eabi-binutils # ---- Arch / Manjaro ---- sudo pacman -S --needed git python-pip python-virtualenv base-devel \ libusb udev pkgconf avr-libc avr-gcc arm-none-eabi-gcc # ---- 装 QMK CLI 并初始化 ---- python3 -m pip install --user qmk qmk setup为什么是这些包libusblibudev是给qmk flash用的刷写时靠它们和 USB 设备通信只编译不刷可以省但建议装上。两套工具链对应两类芯片avr-*服务 AtmelATmega32U4 这类 AVR 芯片arm-none-eabi-*服务 STM32、RP2040 等 Arm 芯片。你的键盘是哪类芯片编译时就用哪套。WSL 用户编译完全没问题刷写时需要在 Windows 侧用 usbipd 把键盘的 USB 设备 attach 进 WSLwinget install usbipd装 Windows 端工具usbipd bind WSL 内usbip attach。不想装 CLI、直接手工编译clone 下来用 makegit clone --recurse-submodules https://gitcode.com/GitHub_Trending/qm/qmk_firmwareFreeBSD用 pkg 装工具链和 QMK CLIpkg update pkg install -y git wget gmake gcc zip unzip diffutils pkg install -y python3 py39-pip pkg install -y avr-binutils avr-gcc avr-libc pkg install -y arm-none-eabi-binutils arm-none-eabi-gcc arm-none-eabi-newlib pkg install -y avrdude dfu-programmer dfu-util python3 -m pip install qmk qmk setup两个 FreeBSD 特有的点用gmake而不是makepkg 装的是 GNU makeARM 侧除了 gcc 还要arm-none-eabi-newlib这是裸机 C 库缺了它链接阶段必炸。刷录工具 avrdude / dfu-util 一次装齐后面刷写不用再折腾。踩坑速查常见报错一条命令解决 现象原因一条命令解决qmk: command not foundCLI 安装目录不在 PATHexport PATH$HOME/.local/bin:$PATHmacOS 则是eval $(/opt/homebrew/bin/brew shellenv)编译报avr-gcc: command not foundAVR 工具链没装sudo apt install -y gcc-avr binutils-avr avr-libc编译报找不到arm-none-eabi-gccARM 工具链没装sudo apt install -y gcc-arm-none-eabi binutils-arm-none-eabi缺子模块/依赖文件仓库没完整拉取qmk git-submodule qmk setup -yLinux 刷写找不到 USB 设备没有设备权限echo SUBSYSTEMSusb, ATTRS{idVendor}feed, MODE:0666 \| sudo tee /etc/udev/rules.d/50-qmk.rules sudo udevadm control --reload-rulesWindows 上编译异常慢杀毒软件逐文件扫描把C:\QMK_MSYS加入 Defender 排除项macOS setup 卡很久不动Apple Silicon 在本地编译工具链属正常现象关后台程序耐心等装好了验证 → 下一步三条命令从上往下跑全绿即环境就绪qmk --version # CLI 版本 qmk doctor # 环境自检 qmk compile -kb planck/rev6 -km default # QMK 固件编译冒烟测试✅ 最后一条会在当前目录生成planck_rev6_default.hex——你能编译出第一份 QMK 固件了。接下来三个方向按兴趣挑配置键位qmk new-keymap mymap生成自己的键位文件再用qmk config user.keyboardplanck/rev6 user.keymapmymap设为默认日常直接qmk compile。键位写法参考 keymap 文档。刷写固件qmk flash一步到位或者不去编译直接从仓库 Releases 页面下载预编译的.hex/.bin配合 QMK Toolbox 刷入。分享你的键位把改动提交到 fork 的仓库再发 Pull Request社区维护者会 review这是让千名用户用上你键位的正规路径。更多资料看 官方文档。从qmk setup到qmk compile出 hex你的 QMK 开发环境就已经立住了——剩下的就是改键位、烧键盘、开打了。【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考