企业官网建设流程全解析

QMK Firmware Linux 下刷写无权限：如何安装 udev 规则？

【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware

在 Linux 上给 QMK Firmware 的键盘刷写固件时，一个常见障碍是：刷写程序（dfu、dfu-util、teensy等 programmer）需要与 bootloader 设备通信，而普通用户没有对应设备的访问权限，导致刷写失败。QMK 构建 FAQ 中的 “Can't Program on Linux” 一节明确说明：Linux 用户要么刷写时用sudo（不推荐），要么安装 udev 规则来获得正确的设备访问权限。本文走第二条路——安装 QMK 官方 udev 规则，之后make <keyboard>:<keymap>:flash不再需要 root 权限。

适用前提：你在 Linux 系统上构建了 QMK 固件仓库，键盘已连接，构建环境已按 环境搭建指南 完成。

先确认问题出在 udev 规则

仓库自带的qmk doctor命令会检查环境并报告潜在的构建或刷写问题，其中就包括 Linux 下的 QMK udev 规则状态（见 CLI 命令参考）：

qmk doctor # 检查环境，发现问题时提示修复 qmk doctor -y # 自动修复发现的问题 qmk doctor -n # 只报告问题，不做修改

qmk doctor在 Linux 上的 udev 检查逻辑见 lib/python/qmk/cli/doctor/linux.py：它扫描/usr/lib/udev/rules.d/、/usr/local/lib/udev/rules.d/、/run/udev/rules.d/、/etc/udev/rules.d/四个目录中文件名含qmk的规则文件，并检查规则内容中是否带有ID_QMK标记。根据结果会看到三种情况：

• 规则内容含ID_QMK：检查通过；
• 找到的是旧版规则（含TAG+="uaccess"但没有ID_QMK）：输出警告Found legacy udev rules. Please run 'util/install_udev.sh' to install the latest rules；
• 完全没找到 QMK 规则：输出警告Missing udev rules for QMK boards. Please run 'util/install_udev.sh' to install the rules。

看到后两条警告，就按下一步安装最新规则。另外该检查在 WSL 环境下会被跳过（源码注释 “Don't bother with udev on WSL, for now”），WSL 用户不适用本文路径。

安装 udev 规则

在仓库根目录运行 util/install_udev.sh：

util/install_udev.sh

运行前需要知道这个脚本会做什么，因为它会改动系统目录：

• 仅限 Linux，支持 x86_64、aarch64/arm64、riscv64 架构，其他架构会直接退出；
• 需要系统中有sudo或doas，脚本通过它完成安装步骤；
• 需要curl或wget之一用于下载；
• 从 qmk_udev 官方仓库的最新 release 下载50-qmk.rules规则文件和与架构匹配的qmk_id辅助程序；
• 先删除各标准位置下已有的*-qmk.rules规则文件和旧的qmk_id（涉及/etc/udev/rules.d、/run/udev/rules.d、/usr/lib/udev/rules.d、/usr/local/lib/udev/rules.d、/lib/udev/rules.d）；
• 安装到/usr/lib/udev/qmk_id（权限 0755）和/etc/udev/rules.d/50-qmk.rules（权限 0644）；
• 最后执行udevadm control --reload-rules和udevadm trigger重新加载规则；若系统没有udevadm则跳过重载并提示。

也就是说，脚本只会触碰 QMK 自己的规则文件与qmk_id，但写入的是系统级目录，因此运行它会要求 root 授权，脚本执行过程中注意确认终端提示。

如果 ModemManager 版本较旧（< 1.12），过滤功能在非严格模式下才生效。构建 FAQ 给出以下命令来更新该项设置；它会写入 ModemManager 的 systemd 配置并重载、重启 ModemManager 服务，需要 root 权限：

printf '[Service]\nExecStart=\nExecStart=/usr/sbin/ModemManager --filter-policy=default' | sudo tee /etc/systemd/system/ModemManager.service.d/policy.conf sudo systemctl daemon-reload sudo systemctl restart ModemManager

验证规则已生效

1. 重新运行qmk doctor：之前出现的 “Missing udev rules” 或 “Found legacy udev rules” 警告应不再出现，说明/etc/udev/rules.d/50-qmk.rules已就位且含ID_QMK标记。
2. 不带sudo执行一次真实刷写：

make planck/rev4:default:flash

把planck/rev4、default换成你的键盘/版本与键名。按 Make 指南 的说明，flash目标会先编译再上传，且 “If the compilation fails, then nothing will be uploaded”——也就是说编译失败时设备不会被写入，可以安全重试。若编译通过且上传过程不再出现权限类报错，说明 udev 规则已生效。

备选路径与相邻问题

临时用sudo顶替（不推荐）。构建 FAQ 给出的权宜方案是：

sudo make <keyboard>:<keymap>:flash

控制器为 ATMega32u4 时也可以逐条执行：

sudo dfu-programmer atmega32u4 erase --force sudo dfu-programmer atmega32u4 flash your.hex sudo dfu-programmer atmega32u4 reset

其中your.hex是文档示例中的占位文件名，替换为你实际编译出的.hex。文档明确提示：用sudo跑make通常不是好主意，能装 udev 规则就优先装规则。

bootloader 模式下串口设备根本不被识别。这不属于权限问题，而是内核缺少设备支持：构建 FAQ 指出，使用 USB ACM 的设备（如 Pro Micro / Atmega32u4）需要内核包含CONFIG_USB_ACM=y，其他设备可能需要USB_SERIAL及其子选项。遇到这类情况先去核对内核配置，而不是继续折腾 udev。

【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware