2026/9/7 5:31:34
FEATURED · 精选文章 
3步搭好QMK开发环境从工具链到QMK固件编译完整走通【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmwareQMK 是面向机械键盘的开源固件支持 Atmel AVR 与 Arm USB 系列芯片。本文带你用三步搭好 QMK 开发环境装编译器工具链、装 QMK CLI、初始化固件仓库再用一次试编译验证。完成后即可开始 QMK 固件编译、自定义键位与固件刷写Windows、macOS、Linux/WSL 全程约半小时。环境认知搭好 QMK 开发环境后能做什么装环境本质上只装三样东西AVR/ARM 交叉编译器、qmk 命令行工具、固件仓库源码。三者就位后你可以为自己的键盘编写键位映射执行 QMK 固件编译用qmk compile一条命令产出可烧录的.hex固件通过 USB 把固件写入芯片立即生效。路线决策一张表选对你的安装方式先按系统对号入座后文主线安装直接照此执行平台推荐路线理由WindowsQMK MSYS 一体安装包MSYS2、qmk CLI、AVR/ARM 工具链全部内置开箱即用macOSHomebrew Tap两条 brew 命令装齐全部依赖自动解析Linux / WSL系统包管理器 pip/uvapt/dnf/pacman 装工具链pip 装 CLIFreeBSDpkg官方包系统直接提供 AVR/ARM 工具链⚠️ Windows 不建议手工拼凑 MSYS2 组件macOS 不建议单独找编译器包用 Tap 最省心。三步主线工具链 → QMK CLI → 固件仓库所有平台都是同一个顺序只是每步的命令不同。第 1 步安装 AVR/ARM 交叉编译器工具链WindowsQMK MSYS安装程序已内置 AVR-GCC、ARM-GCC 与 DFU 烧录工具无需再装 ✅ macOS工具链会随 QMK 的 formula 一起安装也不用单独处理。Linux 与 FreeBSD 用各自包管理器安装# Ubuntu/Debian sudo apt install -y avr-libc avrdude binutils-avr gcc-avr gcc-arm-none-eabi binutils-arm-none-eabi # Fedora sudo dnf install -y avr-libc avrdude avr-gcc avr-binutils arm-none-eabi-gcc arm-none-eabi-binutils # Arch Linux sudo pacman -S avr-libc avrdude avr-gcc arm-none-eabi-gcc arm-none-eabi-binutils # FreeBSD含 avrdude 等烧录工具 sudo pkg install -y avr-gcc avr-libc arm-none-eabi-gcc arm-none-eabi-newlib avrdude dfu-programmer dfu-util成功的标志avr-gcc --version与arm-none-eabi-gcc --version都能打印版本号。⚠️ 两个平台差异各记一句Apple SiliconM 系列芯片没有预编译工具链需在本地编译首次安装多花 30~60 分钟WSL2 下要在 Windows 端装 usbipd 做 USB 直通物理键盘才能被识别编译 QMK 本身不受影响。第 2 步一条命令装好 QMK CLIWindows 用户在完成 QMK MSYS 安装后已自带 CLI安装时选默认路径C:\QMK_MSYS建议勾选“添加到 Windows Terminal”。其余平台# macOSHomebrew 安装 QMK官方 Tap两条命令 brew tap qmk/qmk brew install qmk/qmk/qmk # Linux / WSLpip 安装到用户目录 python3 -m pip install --user qmk # 有 uv 的话也可以uv tool install qmk # FreeBSD sudo python3 -m pip install qmkArch Linux 走官方仓库也行sudo pacman -S qmk开发版yay -S qmk-git。成功的标志which qmk有输出。若提示找不到命令说明 CLI 安装目录不在 PATH 里补两行即可echo export PATH$HOME/.local/bin:$PATH ~/.bashrc source ~/.bashrc第 3 步用 qmk setup 初始化固件仓库qmk setup是必做的收尾一步克隆仓库、装构建依赖、生成配置文件提示统一回答y。# 方式一一条命令初始化推荐默认克隆到 ~/qmk_firmware qmk setup # 方式二手动克隆后构建 git clone https://gitcode.com/GitHub_Trending/qm/qmk_firmware # 仓库想放别处 qmk setup -H ~/qmk_firmware_custom维护自己 fork 的开发者可以指向它qmk setup 你的用户名/qmk_firmware。成功的标志命令结束出现仓库目录进入后能看到Makefile、keyboards/等主目录文件。验证 QMK 固件编译试编译与默认配置qmk --version qmk compile -kb planck/rev6 -km default qmk config user.keyboardplanck/rev6 user.keymapdefault成功的标志编译结束出现类似The firmware size is fine - 26356/28672的提示且目录里多出planck_rev6_default.hex文件 ✅常用配置项qmk config 键值设置配置项作用示例user.keyboard默认键盘后续直接qmk compile即可clueboard/66/rev4user.keymap默认键位映射名defaultuser.name你的 GitHub 用户名自行填写常见问题速查现象、原因、解决现象可能原因解决办法qmk: command not foundCLI 目录不在 PATHexport PATH$HOME/.local/bin:$PATH并写入~/.bashrcWindows 安装程序无法启动系统兼容性问题以管理员身份运行安装程序Windows 下载中断或误报网络不稳/杀毒拦截临时关闭实时保护将 QMK_MSYS 目录加入排除列表macOS 安装长时间无输出Apple Silicon 本地编译工具链属正常现象等待 30~60 分钟键盘 USB 设备无反应缺少 udev 权限为厂商号feed建立 udev 规则并重载规则编译报依赖缺失子模块不完整执行qmk git-submodule或重跑qmk setup -yWindows 编译速度慢实时扫描拖慢读写排除仓库目录 使用 SSD搭好之后接下来做三件事至此你可以编译仓库里任何受支持键盘的固件了。建议按顺序推进先读键位映射文档、改一遍keymap.c完成第一次键位定制再装 QMK Toolbox把刚编译出的.hex刷进键盘平时维护用git pull更新仓库macOS 可加brew upgrade qmk更新 CLI有卡壳的地方再回头翻上面的速查表。【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
3步搭好QMK开发环境：从工具链到QMK固件编译完整走通
3步搭好QMK开发环境从工具链到QMK固件编译完整走通【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmwareQMK 是面向机械键盘的开源固件支持 Atmel AVR 与 Arm USB 系列芯片。本文带你用三步搭好 QMK 开发环境装编译器工具链、装 QMK CLI、初始化固件仓库再用一次试编译验证。完成后即可开始 QMK 固件编译、自定义键位与固件刷写Windows、macOS、Linux/WSL 全程约半小时。环境认知搭好 QMK 开发环境后能做什么装环境本质上只装三样东西AVR/ARM 交叉编译器、qmk 命令行工具、固件仓库源码。三者就位后你可以为自己的键盘编写键位映射执行 QMK 固件编译用qmk compile一条命令产出可烧录的.hex固件通过 USB 把固件写入芯片立即生效。路线决策一张表选对你的安装方式先按系统对号入座后文主线安装直接照此执行平台推荐路线理由WindowsQMK MSYS 一体安装包MSYS2、qmk CLI、AVR/ARM 工具链全部内置开箱即用macOSHomebrew Tap两条 brew 命令装齐全部依赖自动解析Linux / WSL系统包管理器 pip/uvapt/dnf/pacman 装工具链pip 装 CLIFreeBSDpkg官方包系统直接提供 AVR/ARM 工具链⚠️ Windows 不建议手工拼凑 MSYS2 组件macOS 不建议单独找编译器包用 Tap 最省心。三步主线工具链 → QMK CLI → 固件仓库所有平台都是同一个顺序只是每步的命令不同。第 1 步安装 AVR/ARM 交叉编译器工具链WindowsQMK MSYS安装程序已内置 AVR-GCC、ARM-GCC 与 DFU 烧录工具无需再装 ✅ macOS工具链会随 QMK 的 formula 一起安装也不用单独处理。Linux 与 FreeBSD 用各自包管理器安装# Ubuntu/Debian sudo apt install -y avr-libc avrdude binutils-avr gcc-avr gcc-arm-none-eabi binutils-arm-none-eabi # Fedora sudo dnf install -y avr-libc avrdude avr-gcc avr-binutils arm-none-eabi-gcc arm-none-eabi-binutils # Arch Linux sudo pacman -S avr-libc avrdude avr-gcc arm-none-eabi-gcc arm-none-eabi-binutils # FreeBSD含 avrdude 等烧录工具 sudo pkg install -y avr-gcc avr-libc arm-none-eabi-gcc arm-none-eabi-newlib avrdude dfu-programmer dfu-util成功的标志avr-gcc --version与arm-none-eabi-gcc --version都能打印版本号。⚠️ 两个平台差异各记一句Apple SiliconM 系列芯片没有预编译工具链需在本地编译首次安装多花 30~60 分钟WSL2 下要在 Windows 端装 usbipd 做 USB 直通物理键盘才能被识别编译 QMK 本身不受影响。第 2 步一条命令装好 QMK CLIWindows 用户在完成 QMK MSYS 安装后已自带 CLI安装时选默认路径C:\QMK_MSYS建议勾选“添加到 Windows Terminal”。其余平台# macOSHomebrew 安装 QMK官方 Tap两条命令 brew tap qmk/qmk brew install qmk/qmk/qmk # Linux / WSLpip 安装到用户目录 python3 -m pip install --user qmk # 有 uv 的话也可以uv tool install qmk # FreeBSD sudo python3 -m pip install qmkArch Linux 走官方仓库也行sudo pacman -S qmk开发版yay -S qmk-git。成功的标志which qmk有输出。若提示找不到命令说明 CLI 安装目录不在 PATH 里补两行即可echo export PATH$HOME/.local/bin:$PATH ~/.bashrc source ~/.bashrc第 3 步用 qmk setup 初始化固件仓库qmk setup是必做的收尾一步克隆仓库、装构建依赖、生成配置文件提示统一回答y。# 方式一一条命令初始化推荐默认克隆到 ~/qmk_firmware qmk setup # 方式二手动克隆后构建 git clone https://gitcode.com/GitHub_Trending/qm/qmk_firmware # 仓库想放别处 qmk setup -H ~/qmk_firmware_custom维护自己 fork 的开发者可以指向它qmk setup 你的用户名/qmk_firmware。成功的标志命令结束出现仓库目录进入后能看到Makefile、keyboards/等主目录文件。验证 QMK 固件编译试编译与默认配置qmk --version qmk compile -kb planck/rev6 -km default qmk config user.keyboardplanck/rev6 user.keymapdefault成功的标志编译结束出现类似The firmware size is fine - 26356/28672的提示且目录里多出planck_rev6_default.hex文件 ✅常用配置项qmk config 键值设置配置项作用示例user.keyboard默认键盘后续直接qmk compile即可clueboard/66/rev4user.keymap默认键位映射名defaultuser.name你的 GitHub 用户名自行填写常见问题速查现象、原因、解决现象可能原因解决办法qmk: command not foundCLI 目录不在 PATHexport PATH$HOME/.local/bin:$PATH并写入~/.bashrcWindows 安装程序无法启动系统兼容性问题以管理员身份运行安装程序Windows 下载中断或误报网络不稳/杀毒拦截临时关闭实时保护将 QMK_MSYS 目录加入排除列表macOS 安装长时间无输出Apple Silicon 本地编译工具链属正常现象等待 30~60 分钟键盘 USB 设备无反应缺少 udev 权限为厂商号feed建立 udev 规则并重载规则编译报依赖缺失子模块不完整执行qmk git-submodule或重跑qmk setup -yWindows 编译速度慢实时扫描拖慢读写排除仓库目录 使用 SSD搭好之后接下来做三件事至此你可以编译仓库里任何受支持键盘的固件了。建议按顺序推进先读键位映射文档、改一遍keymap.c完成第一次键位定制再装 QMK Toolbox把刚编译出的.hex刷进键盘平时维护用git pull更新仓库macOS 可加brew upgrade qmk更新 CLI有卡壳的地方再回头翻上面的速查表。【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
