TOTP 调试台 是给正在实现两步验证的开发者用的。它不解决「我现在要一个验证码」，而解决「为什么我的码和对方对不上」。

三个面板分别回答什么

按时间出码 —— 把时钟拨到任意时刻，看那一刻的码是什么。表格同时列出前后各两个时间窗，以及每个窗口的 counter 和起止时间。服务端日志里有时间戳和被拒的码，对照这张表几秒钟就知道是差了一个窗口还是完全对不上。

反查验证码 —— 反过来问：这个码是什么时候产生的？以填入的时间戳为中心搜索，命中就告诉你它落在第几个窗口、对应哪个时刻、两边时钟差多少。这是定位「时间不同步」和「密钥不对」的最快路径——前者会在正负一两个窗口命中，后者怎么找都找不到。

HOTP —— 基于计数器而非时间（RFC 4226）。列出从指定 counter 开始的连续几个码，用来排查客户端和服务端计数器跑偏了几步。

TOTP 出错的四个常见原因

按实际遇到的频率排序：

1. 时钟不同步 —— TOTP 完全依赖双方系统时间。服务器没开 NTP、容器时区错乱、用户手机时间手动调过，差超过一个时间步就对不上。
2. 参数不一致 —— 默认是 SHA1、6 位、30 秒，但不是所有服务都用默认值。对方换了 SHA256 或 8 位而你没跟着改，码永远对不上。
3. Base32 解码 —— 密钥必须按 RFC 4648 Base32 解码成字节再做 HMAC。直接把 Base32 字符串当 ASCII 字节喂进去是最经典的实现 bug，自测能过（因为两边错得一样）、和标准验证器一对就穿帮。
4. 时间步取整 —— counter 是 floor(unix秒 / 周期)，用毫秒忘了除 1000、或者用了四舍五入而非向下取整，都会偏。

校验窗口该开多宽

服务端验证时通常会容忍前后若干个窗口。这是个安全与体验的权衡：

• 只认当前窗口：用户在窗口边缘输入就会失败，体验很差
• 正负 1 个窗口（即 ±30 秒）：常见的默认值，能覆盖绝大多数时钟漂移
• 正负 2 个以上：把重放窗口拉长到分钟级，除非你的用户群时钟普遍不准，否则不建议

用按时间出码面板把时钟前后拨几档，拿那些码去打自己的接口，就能实测出当前窗口到底开了多宽。