QMK Firmware 2022 年 11 月 Breaking Changes 解析：Autocorrect 落地与 Keycode、配置体系全面重构迁移指南

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 日这一期主要有三件事值得所有使用者关注：

1. Autocorrect 并入核心：由 @getreuer 实现、@drashna 适配进核心的自动纠错特性正式成为 QMK 的一等公民，相关用法参见 docs/features/autocorrect.md。
2. Keycode 大规模重构与版本化：keycode 被重命名、重排、删除，并开始以强版本化的形式对外发布，为第三方改键工具提供稳定参照。
3. 配置与回调接口规范化：RGB/LED Matrix、Joystick 配置项统一命名，USB ID 全面转向info.json，RGB/LED Matrix 指示器回调改为bool *_user()标准模式。

下文按“需要用户采取行动的变化”与“核心内部变化”两个维度展开，最后给出完整的变更清单索引。

二、需要用户采取行动的变化（迁移指南）

2.1 键盘代码库目录迁移

以下键盘的源码在仓库内的位置发生了变化。如果你的个人键位、用户空间或编译脚本中硬编码了旧路径，请同步更新：

这类改名主要源于 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 配置：

LED Matrix 配置：

Joystick 配置：

从实现层面看，新宏确实已经在源码中全面接管默认值逻辑。例如 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.json）

QMK 决定弃用在config.h中指定 USB ID，info.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 解析侧还加强了健壮性，例如拒绝含重复键的 JSON（PR #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并返回false）：

bool 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_OSX（PR #18290）、清理了遗留 Unicode keycode（PR #18800）。

三、核心内部变化（Notable Core Changes）

本次周期核心代码的主体是清理与重构——也就是俗称的“技术债偿还”。

3.1 Keycode 重构全景

原文档以 PR 清单的形式展现了这次重构的广度。以下按类别整理（编号均为对应 PR）：

废弃（Deprecate）与重命名对齐：

• 音频 keycode 命名对齐（#18962）
• 动态按位时间 keycode 命名对齐（#18963）
• 触觉反馈 keycode 命名对齐（#18964）
• CAPS_WORD/CAPSWRD废弃，改用CW_TOGG（#18834）
• KC_LEAD废弃，改用QK_LEAD（#18792）
• KC_LOCK废弃，改用QK_LOCK（#18796）
• KEY_OVERRIDE_*废弃，改用KO_*（#18843）
• ONESHOT_*废弃，改用QK_ONE_SHOT_*（#18844）
• SECURE_*废弃，改用QK_SECURE_*（#18847）
• VLK_TOG废弃，改用VK_TOGG（#18807）

规范化（Normalise）：

• Auto 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）

删除（Remove）：

• KC_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）
• 初始数据驱动（DD）keycode 迁移（#18643）
• Macro keycode 命名重构（#18958）
• 背光 keycode 重做（#18961）
• US 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 支持（#18776）
• Elite-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_TO=<target>，例如：

qmk flash -c -kb keebio/bdn9/rev1 -km default -e CONVERT_TO=proton_c

也可以在keymap.json中通过"converter"字段配置（对应 PR #18776）。

3.3 指针设备与 Digitizer 更新

指针设备（pointing device）与 digitizer 本次收获颇丰：惯性（inertia）、自动鼠标层、防休眠修复，digitizer 还增加了更多按键：

• 为鼠标键新增“inertia”惯性模式（#18774）
• Digitizer 特性改进（#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 并入核心（#15699）
• RP2040 PWM 背光（#17706）与 PWM 硬件音频驱动调整（#17723）
• WS2812 PIO 驱动允许自定义时序（#18006）
• ChromeOS keycode（#18212）
• VIA V3 自定义 UI 更新（#18222）
• unicode 模式变更回调（#18235）
• WB32 模拟量支持（#18289）
• Kinetis 板 UART 支持（#18370）
• Quantum Painter 新增 RGB565 表面（#18396）
• IS31FL3737 4 驱动支持（#18750）
• ARM Cortex-M 家族扩展、USB 外设可更换（#18767）
• EFL wear-leveling 驱动在 F1/F3/F4/L4/G4/WB32/GD32V 上设为默认（#19020）
• OLED 脏块处理新增默认上限（#19068）

重构与基础设施：

• led_update_ports()拆分以便自定义 LED 行为（#14452）
• 指针设备专属调试消息（#17663）
• 防止 tap dance 清空动态宏（#17880）
• 编码器映射默认使用TAP_CODE_DELAY（#18098）
• oneshot mod 回调移到 mods 设置之后（#18101）
• 移除废弃 USBasp 与 bootloadHID 引导类型（#18195）
• bootloader.mk 移入 platforms（#18228）
• host 驱动层简化 extrakeys 发送（#18230）
• 更妥善地处理 EEPROM 重置 keycode（#18244）
• 规避 WinCompose 在 U+Axxx/U+Exxx 的问题（#18260）
• 蓝牙相关调用上移到 host/keyboard 层（#18274）
• fake EE_HANDS 移出 EEPROM 初始化（#18352）
• 蓝牙 API 起步（#18366）
• 拆分事务处理器加锁重写（#18417）
• rgblight 函数去除忙等待（#18418）
• 分体键盘串行协议主侧清空接收队列（#18419）
• RP2040 半双工 PIO 分体通信稳定性修复（#18421）
• RP2040 启动时向量表复制到 RAM（#18424）
• RP2040 使用内置整数硬件除法器与优化 i64 乘法（#18464）
• 仅主侧触发编码器回调（#18467）
• 朝向 introspection 式数据检索推进（#18441）
• 分体通信看门狗（#18599）
• 未启用 STRICT_LAYER_RELEASE 时切换图层不再清空按键（#18577）
• QP 驱动 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）
• 移除热敏打印机（#18959）
• NVRAM 重构第一阶段（#18969）
• 移除 .noci 功能（#19122）

4.2 CLI

• 拒绝含重复键的 JSON（#18108）
• 指针设备接入数据驱动配置（#18215，随后 #19063 回退）
• 解耦usb.device_ver（#18259）
• 规范化 info_config.h 宏生成（#18439）
• 生成 DD RGBLight/LED/RGB Matrix 动画宏（#18459）
• keymap.json 支持 converter（#18776）
• 一致的 clean 行为（#18781）
• 格式化 DD mappings 与 schemas（#18924）
• HJSON 文件以 JSON 形式发布（#18996）
• QGF/QFF 文件新增 raw 输出选项（#18998）
• 改进 LED 配置解析错误消息（#19007）
• 追加 DD 背光配置（#19124）
• 常量元数据发布到 API（#19143）

4.3 子模块更新

• 编译期数组尺寸宏（#18044）
• pico-sdk 升级至 1.4.0（#18423）

4.4 键盘相关

• PS/2 驱动选择重做（#17892）
• Durgod K310/K320 重构（#18224）
• LAYOUT 宏生成优化（#18262）
• 大写字母键盘改名（#18268）
• 移除遗留USE_SERIAL系列宏（#18292、#18298、#18299）
• Hillside 移出 handwired（#18751）
• KBDfans Odin V2 支持（#18910）
• 移除UNUSED_PINS定义（#18940）
• 移除硬编码 VIA keycode 范围（#18956）
• KC_GESC→QK_GESC（#19018）
• 补充缺失manufacturer字段（#19065）
• 清理遗留DRIVER_LED_TOTAL/RGBLIGHT_ANIMATION引用（#18475、#18594、#18662、#18725–#18730、#19089 等）

4.5 键盘修复（节选）

• GMMK Pro 编码器误触音量键修复（#17129）
• Luna 键盘宠物 OLED 超时修复（#17189）
• 确保所有键盘都设置了 bootloader（#18234）
• 反转键位搜索顺序（#18449）
• onekey 平台 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）、中心点（#18432）
• API 更新工作流合并（#19121）

4.7 关键 Bug 修复（节选）

• 修复 tap dance 图层切换：重做键位查找（#17935）
• ws2812 驱动与 RGBLED/RGBMATRIX 解耦（#18036）
• WB32 重启 USB 时外设故障预防（#18058）
• 修复共享端点鼠标报告比较失败（键盘阻止睡眠，#18060）
• ChibiOS USB 总线断开处理修复（#18566）+ 子模块更新（#18574）
• ST7565 处理器死锁修复（#18609）
• 修复 ChibiOS/OTG（Blackpill）下 joystick 功能（#18631）
• 修复 MIDI 输出端点方向（#18654）
• OLED 渲染全部脏块（#18887）
• 修复 WPM 编译问题（#18965）
• 修复 Cirque 缩放变化时 mouse_report 跳变（#18992）
• 修复encoder_init调用顺序（#19140）
• 修复 Fedora 各版本安装流程（#19159）

五、升级实操建议

1. 先看告警：编译时若出现“deprecated keycode/define”告警，优先按上文的对照表全局替换，而不是用别名掩盖问题——别名本身也可能在未来周期被移除。
2. 优先数据驱动：新键盘与新键位请直接在info.json中声明 USB 信息，不再写config.h宏。
3. 检查自定义回调：如果你写过rgb_matrix_indicators_user/led_matrix_indicators_user，务必改为bool返回类型并返回false；键盘作者则按_kb()委托_user()的标准模式组织代码。
4. 关注 keycode 版本：改键类工具开发者应订阅 docs/api_docs.md 中的 constants 元数据端点，以版本号为准解析 keycode。
5. 善用 converter：Pro 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