机械按键存在物理抖动，直接读GPIO电平会导致误判；必须用基于时间戳的状态机消抖而非delay阻塞；通过IDLE→PRESSED→LONG_HELD→RELEASED四状态支持短按、长按、双击共存；需用unsigned long防millis()溢出，并为多按键独立封装状态结构体。
为什么不能直接读 GPIO 电平判断按键
因为机械按键存在物理抖动，按下/释放瞬间电平会反复跳变几毫秒到十几毫秒，裸读 digitalRead()（或直接读寄存器）大概率触发多次误判。你看到的“按一下触发两次”“松手后又触发一次”，基本都源于这个。消抖不是可选项，是前提。
用状态机而非延时函数做消抖
别用 delay(20) 等固定延时——它会阻塞整个程序，无法响应其他事件（比如串口收数、LED 呼吸、传感器采样）。正确做法是：记录上次有效电平时间，每次循环检查当前电平 + 时间间隔是否稳定超过阈值（通常 15–25ms）。
- 维护一个结构体，含：
last_level（上次确认有效的电平）、stable_since（该电平持续稳定的起始毫秒数） - 每次主循环调用检测函数时，先读当前硬件电平；若与
last_level不同，更新stable_since为millis()；否则检查millis() - stable_since >= DEBOUNCE_MS -
DEBOUNCE_MS建议设为 20，太小易误抖，太大响应迟钝
短按、长按、双击怎么共存不打架
关键在时间窗口划分和状态迁移。不能等“松手了才处理”，必须在按下的过程中就预判可能的后续动作。推荐四状态：IDLE → PRESSED → LONG_HELD → RELEASED，再叠加双击所需的“上次释放时间缓存”。
- IDLE：等待上升沿（从高→低），检测到则进入 PRESSED，并记录
press_time = millis() - PRESSED：持续检查是否超时（如 800ms），是则转 LONG_HELD；同时监控下降沿（松手）→ 进入 RELEASED
- RELEASED：立即检查
millis() - last_release_time <= DOUBLE_CLICK_MS（建议 300ms），成立则触发双击；否则触发单击；最后更新last_release_time - LONG_HELD：只在松手时退出，触发长按事件，不干扰单/双击逻辑
实际编码要注意的硬伤点
很多手写实现翻车，不是逻辑错，而是细节失控：
立即学习“C++免费学习笔记（深入）”；
- 所有时间戳变量（
stable_since、press_time、last_release_time）必须用unsigned long，否则millis()溢出（约 49 天）会导致负数比较失效 - 避免在状态机里调用阻塞函数（
Serial.print()在无缓冲时可能卡住）；事件回调最好只设标志位，主循环再处理输出 - 多个按键共用同一套逻辑？把状态数据封装成结构体实例，每个按键独立持有一份，别用全局变量硬编码索引
- 长按重复触发（类似键盘连按）需要额外计时器，和基础长按检测分离，否则逻辑爆炸
最易被忽略的是：不同按键的消抖/触发阈值未必相同——薄膜按键抖动比船型开关严重，同一块板上混用时，得允许 per-key 配置 DEBOUNCE_MS 和 LONG_PRESS_MS。
