企业官网建设流程全解析

从 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 用户把实时保护先静音一会儿，安装器、交叉工具链都可能被误报，装完记得加进排除列表。
• ⚠️ 磁盘留足 10GB，子模块加 ARM/AVR 两条工具链比你想象的占地方。
• ⚠️ WSL 用户先想清楚刷固件的事：WSL 2 不直通 USB，要么用 usbipd 绑设备，要么忍忍用 WSL 1。

选择你的安装路径

先别急着敲命令，往下看。同样是装环境，有人五分钟搞定，有人折腾一下午，差别全在路径选择。对号入座：

判断逻辑一句话：Windows 走 A；macOS 和 Linux/WSL 走 B；其他系统或者工具链已经齐了想自己掌控的走 C。拿不准就从 B 开始，它是覆盖面最广的一条路。

按路径逐步搭建

三条路径最终都收敛到同一件事：仓库就位、工具链就位、qmk命令能用。整体流程长这样：

路径 A：用 QMK MSYS 打包环境（Windows 首选）

Windows:从 QMK 官方的 MSYS 发行页下载最新安装器，双击运行。安装时建议默认路径C:\QMK_MSYS，"添加到 Windows Terminal" 勾上，之后开终端就能直接用。

装完打开 QMK MSYS 终端，跑这一条：

qmk setup qmk --version

qmk 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 setup

tap 里打包了 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-config

sudo dnf install -y git python3-pip python3-virtualenv gcc make libusb1-devel libudev-devel pkgconfig

sudo pacman -S --needed git python-pip python-virtualenv base-devel libusb udev pkgconf

再装 CLI 并初始化：

python3 -m pip install --user qmk qmk setup

qmk 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-libc

sudo pkg install -y arm-none-eabi-gcc arm-none-eabi-binutils arm-none-eabi-newlib

sudo pkg install -y avrdude dfu-util

OpenBSD/NetBSD 的包名基本同名，把pkg换成pkg_add或pkgin即可，个别 ARM 工具链要从 ports 树里编。各平台对照一下：

工具链齐活后，克隆仓库（记得带上子模块）：

git clone --recurse-submodules https://gitcode.com/GitHub_Trending/qm/qmk_firmware cd qmk_firmware make setup

make setup会替你装齐构建所需的其余依赖。装完用两条命令验尸，版本能打出来就说明编译器可用：

avr-gcc --version arm-none-eabi-gcc --version

Linux 上如果后面刷固件认不到设备，顺手跑一句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 个坑

排错最怕没方向。九成问题落在这五行里，先对号，别盲目重装：

下一步：从"能编译"到"能刷固件"

环境只是门票，下面是接下来几天你会反复翻的几个地方：

• keyboards/目录：每张板子的硬件定义都在这，找到你的型号后先看它的info.json，确认芯片和布局，编译命令里的-kb参数就照着它填。
• users/目录：自定义 userspace 放这里，个人键位的 C 代码、自定义宏都往这扔，构建系统会自动把它编进固件。
• util/drivers.txt：支持的芯片驱动清单，选板子之前先扫一眼，能避开一堆"芯片不受支持"的弯路。
• docs/newbs_getting_started.md：官方新手文档，刷写那一章配着 QMK Toolbox（Windows/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