2020年2月QMK固件Breaking Change变更详解子模块升级、编码器方向与背光重构实战指南【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware导读本文以 QMK Firmware 官方《Breaking Change - 2020 Feb 29 Changelog》仓库路径 docs/ChangeLog/20200229.md为骨架逐项拆解这次季度性重大变更所包含的九项改动ChibiOS/LUFA 子模块升级、16 位 SysTick 定时器溢出修复、编码器方向统一ENCODER_DIRECTION_FLIP、硬件 PWM 背光BACKLIGHT_ON_STATE支持、fn_actions弃用迁移、背光键码逻辑重构、Planck 键位宏化以及 GON NerD 固件目录拆分。读完本文你将理解这些变更的动机、对既有键盘配置的实际影响以及如何将存量键映射迁移到新 API 上。一、QMK 的 Breaking Change 机制为什么一年只合并四次破坏性变更QMK 每年执行四次 Breaking Change 合并流程。所谓 Breaking Change是指任何会改变 QMK 行为、且与旧行为不兼容或存在潜在风险的改动。官方刻意将这类改动限制为每年四次目的很明确——让用户有充分的信心只要在安全窗口期内更新 QMK 源码树就不会破坏自己已有的键映射keymap。这一机制决定了本文所描述的各项变更的呈现方式每一项都会明确列出对用户的影响以及需要采取的迁移动作。阅读 changelog 时请重点区分两类内容无需用户干预的底层修复如定时器溢出修复、子模块升级拉取代码后重新编译即可需要用户主动修改配置/键映射的破坏性变更如编码器方向语义反转、BACKLIGHT_ON_STATE默认值变更、fn_actions弃用、GON 目录拆分这类变更如果忽略会导致行为异常甚至编译失败。二、ChibiOS / ChibiOS-Contrib / uGFX 子模块升级2.1 升级概览本次变更将 QMK 依赖的三个核心子模块整体升级子模块目标版本/状态核心收益ChibiOSver19.1.3与上游同步更轻松旧版已落后约 2 年、MCU 支持增强、Bug 修复、定时器更精准ChibiOS-Contrib更新至新版本MCU 支持增强、Bug 修复uGFX更新至新版本适配新版 ChibiOS 所必需2.2 对用户的直接影响拉取代码后可能需要执行子模块更新官方在 changelog 中明确提示拉取最新 QMK 固件代码后可能需要运行一次make git-submodule来把受影响的子模块升级到新版本否则可能因子模块版本不匹配而编译失败。LINK_TIME_OPTIMIZATION_ENABLE yes在更多板子上可用启用链接时优化LTO的兼容性问题得到改善受益板卡范围扩大。如果你在rules.mk中设置了LINK_TIME_OPTIMIZATION_ENABLE yes升级后原本因工具链/固件兼容问题无法开启的板子现在有机会启用。2.3 工程层面的改进自动化升级脚本为简化未来升级官方提供了自动化更新脚本意味着后续 ChibiOS 上游更新可以更平滑地合入。版本信息可见性ChibiOS 与 ChibiOS-Contrib 的 revision修订号现在会包含在编译命令Command output输出中方便排查问题时定位固件基线版本。三、16 位 SysTick 设备的 ChibiOS 定时器溢出修复在 16 位 SysTick 设备上QMK 的定时器子系统原先对**溢出overflow**的处理存在缺陷当 SysTick 频率运行在 100000100 kHz时16 位设备上可行但较少见定时器计数值会在0.65 秒后溢出。修复前溢出会导致定时器行为错误修复后定时器正确处置溢出情况ChibiOS/ARM 平台的计时不再受此问题影响。这是一项纯底层修复用户无需任何配置变更但如果你使用 16 位 SysTick 的 ARM 设备且曾观察到定时器类功能如长按判定、动画刷新节拍异常此修复值得关注。四、LUFA 子模块更新LUFA 子模块同步了上游abcminiuser/lufa的更新并顺带对 QMK 的 DFU 生成流程做了清理。LUFA 主要用于 AVR 平台的 USB 协议栈因此该变更主要影响 AVR 键盘的 USB 行为与 DFU 刷写流程的稳定性属于低风险维护性升级。五、编码器方向统一ENCODER_DIRECTION_FLIP5.1 变更内容本次变更反转了编码器方向的语义使clockwise true真正对应顺时针转动旋钮这一直觉行为。在此之前部分实现中clockwise的实际含义与物理转动方向相反。同时新增了ENCODER_DIRECTION_FLIP编译宏让用户需要反转方向时例如旋钮安装方向与预期相反可以一行定义搞定无需修改键位代码。5.2 源码级原理方向宏如何生效在仓库的 drivers/encoder/encoder_quadrature.c 中可以看到该宏的实际作用#ifndef ENCODER_DIRECTION_FLIP # define ENCODER_CLOCKWISE true # define ENCODER_COUNTER_CLOCKWISE false #else # define ENCODER_CLOCKWISE false # define ENCODER_COUNTER_CLOCKWISE true #endif也就是说ENCODER_DIRECTION_FLIP并不改变底层脉冲计数的正负而是直接对换ENCODER_CLOCKWISE/ENCODER_COUNTER_CLOCKWISE两个符号的真值从而在驱动层完成方向反转。后续的脉冲处理例如encoder_pulses[i]累积计数、正负值判定方向都会基于这对宏工作。用户侧用法为在键盘或键映射的config.h中加入#define ENCODER_DIRECTION_FLIP5.3 需要执行的动作如果你在此前版本中为了补偿反向问题在encoder_update_user()里写了顺时针当作逆时针的交换逻辑升级后应删除这部分补偿代码如果升级后旋钮方向与预期相反直接添加ENCODER_DIRECTION_FLIP即可。六、硬件 PWM 背光支持BACKLIGHT_ON_STATE6.1 变更内容此前BACKLIGHT_ON_STATE仅影响软件 PWM 背光硬件 PWM 背光则默认假设使用 N 沟道 MOSFET。本次变更让硬件 PWM 背光也遵循该宏。关键点BACKLIGHT_ON_STATE的默认值被改为1这会影响所有未显式定义该宏的软件 PWM 背光键盘。如果你的键盘背光升级后表现异常例如逻辑反了开灯变关灯很可能是 P 沟道 MOSFET 的板子需要在键盘级config.h中显式添加#define BACKLIGHT_ON_STATE 06.2 源码级原理默认值与电平切换仓库 quantum/backlight/backlight.h 中定义了默认值#ifndef BACKLIGHT_ON_STATE # define BACKLIGHT_ON_STATE 1而在 quantum/backlight/backlight_driver_common.c 中开关背光的电平切换逻辑完全由该宏决定static inline void backlight_on(pin_t backlight_pin) { #if BACKLIGHT_ON_STATE 0 gpio_write_pin_low(backlight_pin); #else gpio_write_pin_high(backlight_pin); #endif } static inline void backlight_off(pin_t backlight_pin) { #if BACKLIGHT_ON_STATE 0 gpio_write_pin_high(backlight_pin); #else gpio_write_pin_low(backlight_pin); #endif }从源码可以看到BACKLIGHT_ON_STATE 0意味着低电平点亮P 沟道 MOSFET 常见BACKLIGHT_ON_STATE 1意味着高电平点亮N 沟道 MOSFET 常见。默认值定为1后未配置的板子统一按 N 沟道假设处理使用 P 沟道的板子必须显式声明0否则背光逻辑会整体反转。6.3 排查建议升级后如果背光出现该亮的时候灭、该灭的时候亮或亮度行为诡异优先检查键盘config.h中是否定义了BACKLIGHT_ON_STATEPCB 上背光驱动 MOSFET 的极性N 沟道还是 P 沟道对照上述源码逻辑核对电平设置。七、fn_actions迁移ACTION_LAYER_TAP_KEY()改为LT()键码7.1 弃用背景fn_actions机制已被弃用其功能被直接键码与process_record_user()所取代。迁移后最直接的收益是固件体积下降、代码复杂度降低不再需要为函数动作维护额外的动作表与解析逻辑。7.2 迁移动作所有受影响键映射建议从fn_actions迁移到以下两种现代方式自定义键码custom keycode在keymap.c中定义自己的键码并在process_record_user()中处理。文档参考docs/custom_quantum_functions.md宏macro使用宏功能封装按键序列。文档参考docs/feature_macros.md。典型的迁移示例——原写法已废弃const uint16_t PROGMEM fn_actions[] { [0] ACTION_LAYER_TAP_KEY(1, KC_SPACE), // 旧式按住在层1点按为空格 // ... };新写法推荐// 直接用 LT() 键码Layer Tap替换 fn_actions 中的 ACTION_LAYER_TAP_KEY const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] { [0] LAYOUT( // ... 将 FN0 位置改为 LT(1, KC_SPACE) LT(1, KC_SPACE) ), };LT(layer, kc)即层点按键码按下后进入指定层点按则输出指定的基础键码语义上与ACTION_LAYER_TAP_KEY()完全对应但无需经过fn_actions[]数组。八、背光键码处理迁移至process_keycode/8.1 变更内容本次重构将背光键码的处理逻辑集中到单一文件中使代码更清晰、更模块化所有背光相关键码如BL_*系列现在统一在process_keycode/下的模块中处理ACTION_BACKLIGHT_*宏已被删除。仓库现状印证了这一点quantum/process_keycode/process_backlight.c 与对应的头文件 quantum/process_keycode/process_backlight.h 即背光键码处理的单一入口。8.2 需要执行的动作如果你仍在fn_actions[]中使用ACTION_BACKLIGHT_*系列宏请改为直接使用背光键码或背光函数。推荐方式在键映射矩阵中直接放置背光键码如BL_TOGG、BL_STEP、BL_BRTG、BL_UP、BL_DOWN等或在process_record_user()/ 自定义键码中直接调用背光 API 函数。九、Planck 键映射重构改用 Layout MacrosPlanck 的键映射被重构为使用**布局宏Layout Macros**替代裸的矩阵赋值raw matrix assignments。带来的收益键映射与具体 PCB 版本解耦revision-agnostic同一份键映射代码可以跨 Planck 各硬件版本复用减少 Travis CI 日志中的噪音与错误提升 CI 稳定性。对用户的意义如果你维护 Planck 键映射应改用LAYOUT_*宏来描述键位这与 QMK 通用的布局宏实践一致可参考 docs/feature_layouts.md而不是直接操作MATRIX_ROWS/MATRIX_COLS矩阵下标。十、GON NerD 代码库重构目录拆分与构建命令变更GON NerD 60 与 NerD TKL 两款 PCB 的代码被拆分为两个独立目录构建命令随之改变PCB旧构建命令新构建命令NerD 60make gon/nerd:keymapmake gon/nerd60:keymapNerD TKLmake gon/nerd:keymapmake gon/nerdtkl:keymap这是本次变更中最直接可见的破坏性影响如果你使用 GON 键盘必须按上表更新自己的make命令否则会因目标不存在而构建失败。十一、变更清单速查与升级建议为便于升级时逐项核对汇总如下变更项是否破坏性用户动作ChibiOS/Contrib/uGFX 子模块升级否需更新子模块必要时执行make git-submodule16 位 SysTick 定时器溢出修复否无需操作LUFA 子模块更新否无需操作编码器方向反转 ENCODER_DIRECTION_FLIP是检查方向必要时在config.h定义ENCODER_DIRECTION_FLIP硬件 PWM 背光支持BACKLIGHT_ON_STATE默认改为 1是P 沟道板子在config.h定义BACKLIGHT_ON_STATE 0fn_actions/ACTION_LAYER_TAP_KEY()弃用是迁移到LT()键码、自定义键码或宏ACTION_BACKLIGHT_*宏删除是改用背光键码或背光函数Planck 键映射 Layout Macros 化否推荐迁移新键映射使用LAYOUT_*宏GON NerD 目录拆分是构建命令改用make gon/nerd60:或make gon/nerdtkl:升级路径建议先更新子模块并编译验证无编译错误再逐一检查编码器方向、背光行为最后完成fn_actions与 GON 构建命令的迁移。若升级后行为异常优先回到本文第五、六、七、八、十节对应的排查步骤。参考文档与源码变更日志原文docs/ChangeLog/20200229.md编码器方向宏实现drivers/encoder/encoder_quadrature.c背光默认值与电平切换quantum/backlight/backlight.h、quantum/backlight/backlight_driver_common.c背光键码处理模块quantum/process_keycode/process_backlight.c自定义键码指南docs/custom_quantum_functions.md宏功能指南docs/feature_macros.md布局宏指南docs/feature_layouts.md【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 2020年2月QMK固件Breaking Change变更详解：子模块升级、编码器方向与背光重构实战指南
2020年2月QMK固件Breaking Change变更详解子模块升级、编码器方向与背光重构实战指南【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware导读本文以 QMK Firmware 官方《Breaking Change - 2020 Feb 29 Changelog》仓库路径 docs/ChangeLog/20200229.md为骨架逐项拆解这次季度性重大变更所包含的九项改动ChibiOS/LUFA 子模块升级、16 位 SysTick 定时器溢出修复、编码器方向统一ENCODER_DIRECTION_FLIP、硬件 PWM 背光BACKLIGHT_ON_STATE支持、fn_actions弃用迁移、背光键码逻辑重构、Planck 键位宏化以及 GON NerD 固件目录拆分。读完本文你将理解这些变更的动机、对既有键盘配置的实际影响以及如何将存量键映射迁移到新 API 上。一、QMK 的 Breaking Change 机制为什么一年只合并四次破坏性变更QMK 每年执行四次 Breaking Change 合并流程。所谓 Breaking Change是指任何会改变 QMK 行为、且与旧行为不兼容或存在潜在风险的改动。官方刻意将这类改动限制为每年四次目的很明确——让用户有充分的信心只要在安全窗口期内更新 QMK 源码树就不会破坏自己已有的键映射keymap。这一机制决定了本文所描述的各项变更的呈现方式每一项都会明确列出对用户的影响以及需要采取的迁移动作。阅读 changelog 时请重点区分两类内容无需用户干预的底层修复如定时器溢出修复、子模块升级拉取代码后重新编译即可需要用户主动修改配置/键映射的破坏性变更如编码器方向语义反转、BACKLIGHT_ON_STATE默认值变更、fn_actions弃用、GON 目录拆分这类变更如果忽略会导致行为异常甚至编译失败。二、ChibiOS / ChibiOS-Contrib / uGFX 子模块升级2.1 升级概览本次变更将 QMK 依赖的三个核心子模块整体升级子模块目标版本/状态核心收益ChibiOSver19.1.3与上游同步更轻松旧版已落后约 2 年、MCU 支持增强、Bug 修复、定时器更精准ChibiOS-Contrib更新至新版本MCU 支持增强、Bug 修复uGFX更新至新版本适配新版 ChibiOS 所必需2.2 对用户的直接影响拉取代码后可能需要执行子模块更新官方在 changelog 中明确提示拉取最新 QMK 固件代码后可能需要运行一次make git-submodule来把受影响的子模块升级到新版本否则可能因子模块版本不匹配而编译失败。LINK_TIME_OPTIMIZATION_ENABLE yes在更多板子上可用启用链接时优化LTO的兼容性问题得到改善受益板卡范围扩大。如果你在rules.mk中设置了LINK_TIME_OPTIMIZATION_ENABLE yes升级后原本因工具链/固件兼容问题无法开启的板子现在有机会启用。2.3 工程层面的改进自动化升级脚本为简化未来升级官方提供了自动化更新脚本意味着后续 ChibiOS 上游更新可以更平滑地合入。版本信息可见性ChibiOS 与 ChibiOS-Contrib 的 revision修订号现在会包含在编译命令Command output输出中方便排查问题时定位固件基线版本。三、16 位 SysTick 设备的 ChibiOS 定时器溢出修复在 16 位 SysTick 设备上QMK 的定时器子系统原先对**溢出overflow**的处理存在缺陷当 SysTick 频率运行在 100000100 kHz时16 位设备上可行但较少见定时器计数值会在0.65 秒后溢出。修复前溢出会导致定时器行为错误修复后定时器正确处置溢出情况ChibiOS/ARM 平台的计时不再受此问题影响。这是一项纯底层修复用户无需任何配置变更但如果你使用 16 位 SysTick 的 ARM 设备且曾观察到定时器类功能如长按判定、动画刷新节拍异常此修复值得关注。四、LUFA 子模块更新LUFA 子模块同步了上游abcminiuser/lufa的更新并顺带对 QMK 的 DFU 生成流程做了清理。LUFA 主要用于 AVR 平台的 USB 协议栈因此该变更主要影响 AVR 键盘的 USB 行为与 DFU 刷写流程的稳定性属于低风险维护性升级。五、编码器方向统一ENCODER_DIRECTION_FLIP5.1 变更内容本次变更反转了编码器方向的语义使clockwise true真正对应顺时针转动旋钮这一直觉行为。在此之前部分实现中clockwise的实际含义与物理转动方向相反。同时新增了ENCODER_DIRECTION_FLIP编译宏让用户需要反转方向时例如旋钮安装方向与预期相反可以一行定义搞定无需修改键位代码。5.2 源码级原理方向宏如何生效在仓库的 drivers/encoder/encoder_quadrature.c 中可以看到该宏的实际作用#ifndef ENCODER_DIRECTION_FLIP # define ENCODER_CLOCKWISE true # define ENCODER_COUNTER_CLOCKWISE false #else # define ENCODER_CLOCKWISE false # define ENCODER_COUNTER_CLOCKWISE true #endif也就是说ENCODER_DIRECTION_FLIP并不改变底层脉冲计数的正负而是直接对换ENCODER_CLOCKWISE/ENCODER_COUNTER_CLOCKWISE两个符号的真值从而在驱动层完成方向反转。后续的脉冲处理例如encoder_pulses[i]累积计数、正负值判定方向都会基于这对宏工作。用户侧用法为在键盘或键映射的config.h中加入#define ENCODER_DIRECTION_FLIP5.3 需要执行的动作如果你在此前版本中为了补偿反向问题在encoder_update_user()里写了顺时针当作逆时针的交换逻辑升级后应删除这部分补偿代码如果升级后旋钮方向与预期相反直接添加ENCODER_DIRECTION_FLIP即可。六、硬件 PWM 背光支持BACKLIGHT_ON_STATE6.1 变更内容此前BACKLIGHT_ON_STATE仅影响软件 PWM 背光硬件 PWM 背光则默认假设使用 N 沟道 MOSFET。本次变更让硬件 PWM 背光也遵循该宏。关键点BACKLIGHT_ON_STATE的默认值被改为1这会影响所有未显式定义该宏的软件 PWM 背光键盘。如果你的键盘背光升级后表现异常例如逻辑反了开灯变关灯很可能是 P 沟道 MOSFET 的板子需要在键盘级config.h中显式添加#define BACKLIGHT_ON_STATE 06.2 源码级原理默认值与电平切换仓库 quantum/backlight/backlight.h 中定义了默认值#ifndef BACKLIGHT_ON_STATE # define BACKLIGHT_ON_STATE 1而在 quantum/backlight/backlight_driver_common.c 中开关背光的电平切换逻辑完全由该宏决定static inline void backlight_on(pin_t backlight_pin) { #if BACKLIGHT_ON_STATE 0 gpio_write_pin_low(backlight_pin); #else gpio_write_pin_high(backlight_pin); #endif } static inline void backlight_off(pin_t backlight_pin) { #if BACKLIGHT_ON_STATE 0 gpio_write_pin_high(backlight_pin); #else gpio_write_pin_low(backlight_pin); #endif }从源码可以看到BACKLIGHT_ON_STATE 0意味着低电平点亮P 沟道 MOSFET 常见BACKLIGHT_ON_STATE 1意味着高电平点亮N 沟道 MOSFET 常见。默认值定为1后未配置的板子统一按 N 沟道假设处理使用 P 沟道的板子必须显式声明0否则背光逻辑会整体反转。6.3 排查建议升级后如果背光出现该亮的时候灭、该灭的时候亮或亮度行为诡异优先检查键盘config.h中是否定义了BACKLIGHT_ON_STATEPCB 上背光驱动 MOSFET 的极性N 沟道还是 P 沟道对照上述源码逻辑核对电平设置。七、fn_actions迁移ACTION_LAYER_TAP_KEY()改为LT()键码7.1 弃用背景fn_actions机制已被弃用其功能被直接键码与process_record_user()所取代。迁移后最直接的收益是固件体积下降、代码复杂度降低不再需要为函数动作维护额外的动作表与解析逻辑。7.2 迁移动作所有受影响键映射建议从fn_actions迁移到以下两种现代方式自定义键码custom keycode在keymap.c中定义自己的键码并在process_record_user()中处理。文档参考docs/custom_quantum_functions.md宏macro使用宏功能封装按键序列。文档参考docs/feature_macros.md。典型的迁移示例——原写法已废弃const uint16_t PROGMEM fn_actions[] { [0] ACTION_LAYER_TAP_KEY(1, KC_SPACE), // 旧式按住在层1点按为空格 // ... };新写法推荐// 直接用 LT() 键码Layer Tap替换 fn_actions 中的 ACTION_LAYER_TAP_KEY const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] { [0] LAYOUT( // ... 将 FN0 位置改为 LT(1, KC_SPACE) LT(1, KC_SPACE) ), };LT(layer, kc)即层点按键码按下后进入指定层点按则输出指定的基础键码语义上与ACTION_LAYER_TAP_KEY()完全对应但无需经过fn_actions[]数组。八、背光键码处理迁移至process_keycode/8.1 变更内容本次重构将背光键码的处理逻辑集中到单一文件中使代码更清晰、更模块化所有背光相关键码如BL_*系列现在统一在process_keycode/下的模块中处理ACTION_BACKLIGHT_*宏已被删除。仓库现状印证了这一点quantum/process_keycode/process_backlight.c 与对应的头文件 quantum/process_keycode/process_backlight.h 即背光键码处理的单一入口。8.2 需要执行的动作如果你仍在fn_actions[]中使用ACTION_BACKLIGHT_*系列宏请改为直接使用背光键码或背光函数。推荐方式在键映射矩阵中直接放置背光键码如BL_TOGG、BL_STEP、BL_BRTG、BL_UP、BL_DOWN等或在process_record_user()/ 自定义键码中直接调用背光 API 函数。九、Planck 键映射重构改用 Layout MacrosPlanck 的键映射被重构为使用**布局宏Layout Macros**替代裸的矩阵赋值raw matrix assignments。带来的收益键映射与具体 PCB 版本解耦revision-agnostic同一份键映射代码可以跨 Planck 各硬件版本复用减少 Travis CI 日志中的噪音与错误提升 CI 稳定性。对用户的意义如果你维护 Planck 键映射应改用LAYOUT_*宏来描述键位这与 QMK 通用的布局宏实践一致可参考 docs/feature_layouts.md而不是直接操作MATRIX_ROWS/MATRIX_COLS矩阵下标。十、GON NerD 代码库重构目录拆分与构建命令变更GON NerD 60 与 NerD TKL 两款 PCB 的代码被拆分为两个独立目录构建命令随之改变PCB旧构建命令新构建命令NerD 60make gon/nerd:keymapmake gon/nerd60:keymapNerD TKLmake gon/nerd:keymapmake gon/nerdtkl:keymap这是本次变更中最直接可见的破坏性影响如果你使用 GON 键盘必须按上表更新自己的make命令否则会因目标不存在而构建失败。十一、变更清单速查与升级建议为便于升级时逐项核对汇总如下变更项是否破坏性用户动作ChibiOS/Contrib/uGFX 子模块升级否需更新子模块必要时执行make git-submodule16 位 SysTick 定时器溢出修复否无需操作LUFA 子模块更新否无需操作编码器方向反转 ENCODER_DIRECTION_FLIP是检查方向必要时在config.h定义ENCODER_DIRECTION_FLIP硬件 PWM 背光支持BACKLIGHT_ON_STATE默认改为 1是P 沟道板子在config.h定义BACKLIGHT_ON_STATE 0fn_actions/ACTION_LAYER_TAP_KEY()弃用是迁移到LT()键码、自定义键码或宏ACTION_BACKLIGHT_*宏删除是改用背光键码或背光函数Planck 键映射 Layout Macros 化否推荐迁移新键映射使用LAYOUT_*宏GON NerD 目录拆分是构建命令改用make gon/nerd60:或make gon/nerdtkl:升级路径建议先更新子模块并编译验证无编译错误再逐一检查编码器方向、背光行为最后完成fn_actions与 GON 构建命令的迁移。若升级后行为异常优先回到本文第五、六、七、八、十节对应的排查步骤。参考文档与源码变更日志原文docs/ChangeLog/20200229.md编码器方向宏实现drivers/encoder/encoder_quadrature.c背光默认值与电平切换quantum/backlight/backlight.h、quantum/backlight/backlight_driver_common.c背光键码处理模块quantum/process_keycode/process_backlight.c自定义键码指南docs/custom_quantum_functions.md宏功能指南docs/feature_macros.md布局宏指南docs/feature_layouts.md【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考