QMK Firmware 2022 年 11 月 Breaking Changes 解析Autocorrect 落地与 Keycode、配置体系全面重构迁移指南【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware导读docs/ChangeLog/20221126.md记录了 QMK Firmware 在 2022 年 11 月 26 日发布的一次大规模不兼容更新Breaking Changes。本次更新将 Autocorrect自动纠错特性正式并入核心同时完成了 QMK 历史上最彻底的一次 keycode 规范化——为 keycode 引入强版本化并发布到官方 API并同步重命名了 RGB Matrix、LED Matrix、Joystick 等大量配置项将 USB ID 彻底迁移到info.json数据驱动体系。阅读本文后你将掌握本次升级所需的全部迁移动作键盘目录更名对照、keycode 新旧名称映射、配置宏重命名对照表、config.h到info.json的 USB 信息迁移方法以及 RGB/LED Matrix 指示器回调函数的新写法并理解其背后的源码级实现。一、本次 Breaking Changes 概览QMK 的 Breaking Changes 周期是社区约定俗成的破坏性更新节奏核心团队在develop分支上累积一批会影响现有用户配置与键位的改动随后在固定日期合并到master发布。2022 年 11 月 26 日这一期主要有三件事值得所有使用者关注Autocorrect 并入核心由 getreuer 实现、drashna 适配进核心的自动纠错特性正式成为 QMK 的一等公民相关用法参见 docs/features/autocorrect.md。Keycode 大规模重构与版本化keycode 被重命名、重排、删除并开始以强版本化的形式对外发布为第三方改键工具提供稳定参照。配置与回调接口规范化RGB/LED Matrix、Joystick 配置项统一命名USB ID 全面转向info.jsonRGB/LED Matrix 指示器回调改为bool *_user()标准模式。下文按“需要用户采取行动的变化”与“核心内部变化”两个维度展开最后给出完整的变更清单索引。二、需要用户采取行动的变化迁移指南2.1 键盘代码库目录迁移以下键盘的源码在仓库内的位置发生了变化。如果你的个人键位、用户空间或编译脚本中硬编码了旧路径请同步更新旧键盘名Old Keyboard Name新键盘名New Keyboard Nameconverter/numeric_keypad_IIeconverter/numeric_keypad_iiedurgod/k3x0/k310durgod/k310durgod/k3x0/k320durgod/k320emptystring/NQGemptystring/nqghandwired/hillside/46hillside/46handwired/hillside/48hillside/48handwired/hillside/52hillside/52maple_computing/christmas_tree/V2017maple_computing/christmas_tree/v2017这类改名主要源于 QMK 对键盘目录命名规范全小写、去重层级的收口例如 Hillside 系列整体从handwired移出成为独立厂商目录对应 PR #18751。升级后请用新名称执行编译与刷写例如qmk compile -kb hillside/46 -km default。2.2 Keycode 重构与强版本化本次周期内 keycode 迎来了“非常显著的大规模整改”原文档用语由 zvecr 与 fauxpark 主导涵盖重命名、重排序与删除三个方向。其背景是为了标准化键盘与宿主应用如改键工具、VIA 类软件之间的互操作keycode 值从此拥有强版本号任何连接的应用都能确信它认为键盘上存在的按键与实际编译进固件的按键一致。这些带版本号的 keycode 定义会在线发布且不再变动为第三方改键工具提供稳定参照。从仓库源码看这份元数据正是以 HJSON 常量文件的形式维护在 data/constants/keycodes/例如keycodes_0.0.1.hjson及按子系统拆分的keycodes_0.0.1_audio.hjson、keycodes_0.0.1_basic.hjson等并对应 docs/api_docs.md 中描述的qmk-constantsAPI 端点对外发布。QMK 未来版本中任何新增或修改的 keycode 都会产生新的版本号规范。仓库内大多数用户键位已同步更新为新命名如果你在仓库之外维护键位遇到“找不到旧名 keycode”的编译错误大概率是该名称早已被标记废弃——应立即改用新名。::: warning 在绝大多数情况下 QMK 已经为“旧名 → 新名”建立了别名alias但文档体系已全面采用新命名。 :::2.3 配置项重命名对照表为了命名一致性一批配置宏被重命名。下表是原文档给出的完整对照旧宏名在本版本起不再生效请按新名修改config.h或info.json中对应字段。RGB Matrix 配置旧配置Old Config新配置New ConfigDRIVER_LED_COUNTRGB_MATRIX_LED_COUNTRGB_DISABLE_TIMEOUTRGB_MATRIX_TIMEOUTRGB_MATRIX_STARTUP_HUERGB_MATRIX_DEFAULT_HUERGB_MATRIX_STARTUP_MODERGB_MATRIX_DEFAULT_MODERGB_MATRIX_STARTUP_SATRGB_MATRIX_DEFAULT_SATRGB_MATRIX_STARTUP_SPDRGB_MATRIX_DEFAULT_SPDRGB_MATRIX_STARTUP_VALRGB_MATRIX_DEFAULT_VALLED Matrix 配置旧配置Old Config新配置New ConfigDRIVER_LED_COUNTLED_MATRIX_LED_COUNTLED_DISABLE_TIMEOUTLED_MATRIX_TIMEOUTLED_MATRIX_STARTUP_MODELED_MATRIX_DEFAULT_MODELED_MATRIX_STARTUP_SPDLED_MATRIX_DEFAULT_SPDLED_MATRIX_STARTUP_VALLED_MATRIX_DEFAULT_VALJoystick 配置旧配置Old Config新配置New ConfigJOYSTICK_AXES_COUNTJOYSTICK_AXIS_COUNTJOYSTICK_AXES_RESOLUTIONJOYSTICK_AXIS_RESOLUTION从实现层面看新宏确实已经在源码中全面接管默认值逻辑。例如 quantum/rgb_matrix/rgb_matrix.c 中初始化使用RGB_MATRIX_DEFAULT_MODE与RGB_MATRIX_DEFAULT_HUE/SAT/VAL并在 quantum/rgb_matrix/rgb_matrix.h 中为RGB_MATRIX_TIMEOUT默认 0即不超时、RGB_MATRIX_DEFAULT_MODE有 RGBLIGHT 时为RGB_MATRIX_CYCLE_LEFT_RIGHT否则为RGB_MATRIX_SOLID_COLOR、RGB_MATRIX_DEFAULT_HUE默认 0等提供后备定义RGB_MATRIX_TIMEOUT则在 quantum/rgb_matrix/rgb_matrix.c 中用于判断无操作自动熄灭。对应改动落地于 PR #18399、#18415、#19079、#19080 等。2.4 Data-driven USB ID 重构config.h→info.jsonQMK 决定弃用在config.h中指定 USB IDinfo.json成为唯一合法途径。这是延续上一期制定的弃用时间表执行的正式切换。迁移前config.h中的旧写法#define VENDOR_ID 0x1234 #define PRODUCT_ID 0x5678 #define DEVICE_VER 0x0001 #define MANUFACTURER Me #define PRODUCT MyKeyboard迁移后info.json中的新写法{ keyboard_name: MyKeyboard, manufacturer: Me, usb: { vid: 0x1234, pid: 0x5678, device_version: 0.0.1 } }几点实操提示由仓库 CLI 侧的配套改动佐证usb.device_ver与info.json的解耦在 PR #18259 中完成device_version采用x.y.z三段式字符串MANUFACTURER/PRODUCT全面切换为字符串字面量PR #18183字符串转义处理在 PR #18194 中完善info.json 解析侧还加强了健壮性例如拒绝含重复键的 JSONPR #18108、规范化 info_config.h 的宏生成PR #18439。2.5 RGB/LED Matrix 指示器回调重构传统上RGB Matrix 与 LED Matrix 的指示灯显示代码很难在键位层覆盖因为它们没有遵循 QMK 标准的bool *_kb()委托bool *_user()模式。本次重构将回调统一为标准模型键盘可以提供基础实现同时键位层仍可覆盖且无需修改键盘代码。旧写法键位层void无返回值void rgb_matrix_indicators_user(void) { // keymap LED code }新写法键位层改为bool并返回falsebool rgb_matrix_indicators_user(void) { // keymap LED code return false; }键盘设计者应这样组织键盘级例程以便让键位层覆盖bool rgb_matrix_indicators_kb(void) { // Defer to the keymap if they want to override if (!rgb_matrix_indicators_user()) { return false; } // keyboard LED code return true; }LED Matrix 键盘需要做完全等价的改造。仓库源码印证了这一模式在 quantum/rgb_matrix/rgb_matrix.c 中rgb_matrix_indicators_kb()与rgb_matrix_indicators_user()均为__attribute__((weak))弱符号定义默认_kb()直接委托_user()quantum/led_matrix/led_matrix.c 中led_matrix_indicators_kb()/led_matrix_indicators_user()结构完全一致头文件声明位于 quantum/led_matrix/led_matrix.h 与 quantum/rgb_matrix/rgb_matrix.h。配套修复参见 PR #18450 “Fix Per Key LED Indicator Callbacks”。2.6 Unicode 模式重命名为避免与等价 keycode 冲突Unicode 输入模式被重命名UNICODE_SELECTED_MODES可用的取值列表随之变化。完整取值与配置方法见 docs/features/unicode.md“Input Modes”一节。典型配置仍是在键位config.h中定义例如#define UNICODE_SELECTED_MODES UNICODE_MODE_LINUX // 或 #define UNICODE_SELECTED_MODES UNICODE_MODE_MACOS, UNICODE_MODE_WINCOMPOSE随后可用UC_NEXT/UC_PREV在已启用模式间循环切换。本次周期内 Unicode 特性本身也做了重构PR #18333并移除了UNICODE_KEY_OSX与UC_OSXPR #18290、清理了遗留 Unicode keycodePR #18800。三、核心内部变化Notable Core Changes本次周期核心代码的主体是清理与重构——也就是俗称的“技术债偿还”。3.1 Keycode 重构全景原文档以 PR 清单的形式展现了这次重构的广度。以下按类别整理编号均为对应 PR废弃Deprecate与重命名对齐音频 keycode 命名对齐#18962动态按位时间 keycode 命名对齐#18963触觉反馈 keycode 命名对齐#18964CAPS_WORD/CAPSWRD废弃改用CW_TOGG#18834KC_LEAD废弃改用QK_LEAD#18792KC_LOCK废弃改用QK_LOCK#18796KEY_OVERRIDE_*废弃改用KO_*#18843ONESHOT_*废弃改用QK_ONE_SHOT_*#18844SECURE_*废弃改用QK_SECURE_*#18847VLK_TOG废弃改用VK_TOGG#18807规范化NormaliseAuto Shift keycode#18892、Autocorrect keycode#18893、Combo keycode#18877、Dynamic Macro keycode#18939、Joystick 与 Programmable Button keycode#18832、MIDI keycode#18972、输出选择/蓝牙 keycode#19004、Space Cadet keycode#18864、Unicode keycode#18898删除RemoveKC_DELT#18882遗留 Debug keycode#18769遗留 EEPROM 清除 keycode#18782遗留 fauxclicky 与 Unicode keycode#18800遗留 Grave Escape keycode#18787遗留国际 keycode#18588遗留 keycode 六连删#18660、#18669、#18683、#18710、#18740遗留锁定 Caps/Num/Scroll keycode#18601遗留 sendstring keycode#18749废弃的 RESET keycode 别名#18271其他结构性动作鼠标键 keycode 迁入新腾出的 keycode 块#16076初始数据驱动DDkeycode 迁移#18643Macro keycode 命名重构#18958背光 keycode 重做#18961US ANSI shifted keycode 别名搬迁#18634常量元数据发布到 API#19143从仓库看这些版本化常量以 HJSON 形式沉淀在 data/constants/keycodes/并经由 API 供工具使用详见 docs/api_docs.md 的#qmk-constants一节。3.2 板级转换器Board Converters历史上一块 Pro Micro 键盘可以“转换”为 QMK Proton-C 构建最近几个版本持续扩充了此类替代主控的支持本周期也不例外新增 Bonsai C4 平台板文件#18901为keymap.json增加 converter 支持#18776Elite-C 加入 converters#18309新增 Elite-Pi converter#18236允许QK_MAKE与 converters 协同工作#18637完整可用转换列表见 docs/feature_converters.md。当前仓库支持的转换路径包括promicro → proton_c/kb2040/sparkfun_pm2040/blok/bit_c_pro/stemcell/bonsai_c4/rp2040_ce/elite_pi/helios/liatris/imera/michi/svlinky以及elite_c → stemcell/rp2040_ce/elite_pi/helios/liatris等。使用方式是在编译/刷写命令后追加-e CONVERT_TOtarget例如qmk flash -c -kb keebio/bdn9/rev1 -km default -e CONVERT_TOproton_c也可以在keymap.json中通过converter字段配置对应 PR #18776。3.3 指针设备与 Digitizer 更新指针设备pointing device与 digitizer 本次收获颇丰惯性inertia、自动鼠标层、防休眠修复digitizer 还增加了更多按键为鼠标键新增“inertia”惯性模式#18774Digitizer 特性改进#19034在注册码函数中启用指针设备支持#18363指针设备自动鼠标层特性#17962修复共享端点上鼠标报告比较失败修复键盘阻止睡眠的问题#18060修复send_string中使用鼠标的问题#18659更一致地处理鼠标键#18513反转 Cirque 触摸板运动引脚#18404重构更多 host 代码programmable button 与 digitizer#18565其中 inertia 模式已落地于 quantum/mousekey.c源码中通过MOUSEKEY_INERTIA条件编译启用维护mousekey_x_inertia/mousekey_y_inertia两个速度状态变量quantum/mousekey.c并以calc_inertia()在每次鼠标刷新时更新速度、在无方向输入时按惯性衰减quantum/mousekey.c。值得一提的是 AVR 上MOUSEKEY_INERTIA的编译问题也在 #19096 中被单独修复。四、完整变更清单Full Changelist以下按原文档分类归纳覆盖 Core、CLI、Submodule、Keyboards、Keyboard fixes、Others、Bugs 七个部分作为深入追踪的索引。4.1 核心Core特性与平台Autocorrect 并入核心#15699RP2040 PWM 背光#17706与 PWM 硬件音频驱动调整#17723WS2812 PIO 驱动允许自定义时序#18006ChromeOS keycode#18212VIA V3 自定义 UI 更新#18222unicode 模式变更回调#18235WB32 模拟量支持#18289Kinetis 板 UART 支持#18370Quantum Painter 新增 RGB565 表面#18396IS31FL3737 4 驱动支持#18750ARM Cortex-M 家族扩展、USB 外设可更换#18767EFL wear-leveling 驱动在 F1/F3/F4/L4/G4/WB32/GD32V 上设为默认#19020OLED 脏块处理新增默认上限#19068重构与基础设施led_update_ports()拆分以便自定义 LED 行为#14452指针设备专属调试消息#17663防止 tap dance 清空动态宏#17880编码器映射默认使用TAP_CODE_DELAY#18098oneshot mod 回调移到 mods 设置之后#18101移除废弃 USBasp 与 bootloadHID 引导类型#18195bootloader.mk 移入 platforms#18228host 驱动层简化 extrakeys 发送#18230更妥善地处理 EEPROM 重置 keycode#18244规避 WinCompose 在 UAxxx/UExxx 的问题#18260蓝牙相关调用上移到 host/keyboard 层#18274fake EE_HANDS 移出 EEPROM 初始化#18352蓝牙 API 起步#18366拆分事务处理器加锁重写#18417rgblight 函数去除忙等待#18418分体键盘串行协议主侧清空接收队列#18419RP2040 半双工 PIO 分体通信稳定性修复#18421RP2040 启动时向量表复制到 RAM#18424RP2040 使用内置整数硬件除法器与优化 i64 乘法#18464仅主侧触发编码器回调#18467朝向 introspection 式数据检索推进#18441分体通信看门狗#18599未启用 STRICT_LAYER_RELEASE 时切换图层不再清空按键#18577QP 驱动 init 函数改为 weak#18717移除rgblight_list.h#18878可覆盖动态键位起始地址#18867正式化键盘/用户专属 EEPROM 块#18874并扩展其 API#19094简化 Keymap Config EEPROM#18886移除 quantum/audio 全局 VPATH#18753大量头文件 include 精简sequencer、crc、caps_word、wpm、dip_switch、send_string#18946–#18952移除热敏打印机#18959NVRAM 重构第一阶段#18969移除 .noci 功能#191224.2 CLI拒绝含重复键的 JSON#18108指针设备接入数据驱动配置#18215随后 #19063 回退解耦usb.device_ver#18259规范化 info_config.h 宏生成#18439生成 DD RGBLight/LED/RGB Matrix 动画宏#18459keymap.json 支持 converter#18776一致的 clean 行为#18781格式化 DD mappings 与 schemas#18924HJSON 文件以 JSON 形式发布#18996QGF/QFF 文件新增 raw 输出选项#18998改进 LED 配置解析错误消息#19007追加 DD 背光配置#19124常量元数据发布到 API#191434.3 子模块更新编译期数组尺寸宏#18044pico-sdk 升级至 1.4.0#184234.4 键盘相关PS/2 驱动选择重做#17892Durgod K310/K320 重构#18224LAYOUT 宏生成优化#18262大写字母键盘改名#18268移除遗留USE_SERIAL系列宏#18292、#18298、#18299Hillside 移出 handwired#18751KBDfans Odin V2 支持#18910移除UNUSED_PINS定义#18940移除硬编码 VIA keycode 范围#18956KC_GESC→QK_GESC#19018补充缺失manufacturer字段#19065清理遗留DRIVER_LED_TOTAL/RGBLIGHT_ANIMATION引用#18475、#18594、#18662、#18725–#18730、#19089 等4.5 键盘修复节选GMMK Pro 编码器误触音量键修复#17129Luna 键盘宠物 OLED 超时修复#17189确保所有键盘都设置了 bootloader#18234反转键位搜索顺序#18449onekey 平台 ADC 启用#18545、#18592大量具体键盘keychron/q1/q3/q5/q6、aurora/sweep、aurora/corne、keebio/sinc、hotdox76v2、cradio、bn006 等的修复#18560、#18651、#18687、#18692、#18701、#18840、#18858、#18859、#18866、#19006、#19029、#19066、#19072、#19119、#19137、#19144 等4.6 其他DD 映射补充LED/RGB Matrix 最大亮度#18403、分体数量#18408、HSVS 步进#18414、中心点#18432API 更新工作流合并#191214.7 关键 Bug 修复节选修复 tap dance 图层切换重做键位查找#17935ws2812 驱动与 RGBLED/RGBMATRIX 解耦#18036WB32 重启 USB 时外设故障预防#18058修复共享端点鼠标报告比较失败键盘阻止睡眠#18060ChibiOS USB 总线断开处理修复#18566 子模块更新#18574ST7565 处理器死锁修复#18609修复 ChibiOS/OTGBlackpill下 joystick 功能#18631修复 MIDI 输出端点方向#18654OLED 渲染全部脏块#18887修复 WPM 编译问题#18965修复 Cirque 缩放变化时 mouse_report 跳变#18992修复encoder_init调用顺序#19140修复 Fedora 各版本安装流程#19159五、升级实操建议先看告警编译时若出现“deprecated keycode/define”告警优先按上文的对照表全局替换而不是用别名掩盖问题——别名本身也可能在未来周期被移除。优先数据驱动新键盘与新键位请直接在info.json中声明 USB 信息不再写config.h宏。检查自定义回调如果你写过rgb_matrix_indicators_user/led_matrix_indicators_user务必改为bool返回类型并返回false键盘作者则按_kb()委托_user()的标准模式组织代码。关注 keycode 版本改键类工具开发者应订阅 docs/api_docs.md 中的 constants 元数据端点以版本号为准解析 keycode。善用 converterPro Micro/Elite-C 键盘换装 RP2040 系主控如 Elite-Pi时优先尝试-e CONVERT_TO可省去大量手工移植工作。本次更新体量大但路径清晰命名规范化 数据驱动 可覆盖回调是贯穿始终的主线掌握了这三条主线就能平稳跨越这次 Breaking Changes。【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考