OTP 验证码不显示或倒计时异常 - 排查清单
症状分类
| 症状 | 大致方向 |
|---|---|
| 条目里完全看不到 OTP 字段 | 没正确配置 OTP / OTP 字段不在条目里 |
| OTP 字段有但值是空白 | 参数配置错误 / 密钥无效 |
| 验证码每 30 秒刷新一次但始终不对 | 手机时间不准 / 密钥不正确 |
| 验证码偶尔对偶尔不对 | 周期参数不匹配 |
条目里看不到 OTP
确认数据库版本
TOTP 等 OTP 功能只在 KDBX 2.x / 3.1 / 4.x 数据库里可用。如果你的数据库是非常老的 KDBX 1.x 格式（现在几乎没有人用），OTP 功能不会出现。
确认 OTP 字段确实添加了
编辑条目 → 滚动到自定义字段区域 → 找 OTP 或 Time-Based OTP 相关的字段。如果确实没加：
- 编辑条目
- 点击"+ 添加 OTP"或类似按钮
- 配置参数（扫码自动填，或手动输入密钥）
- 保存
确认数据库已打开
OTP 值是实时计算的，需要数据库已解锁。如果数据库关闭状态下，条目列表里的 OTP 倒计时不显示（部分版本）。
验证码不对
手机时间不准
TOTP 严格依赖当前时间（每 30 秒计算一次）。如果手机系统时间和 UTC 偏差超过 20 秒，验证码就会不对。
解决办法：
- 设置 → 日期和时间 → 开启"自动设置时间"（网络时间协议 NTP）
- 关闭手动时间调整
- 某些国产 ROM 的自动时间和网络同步有延迟，手动改到正确时间测试
密钥不正确
密钥（Secret Key）是 OTP 的种子，如果输入错了（比如少了一个字符、或大小写不对），算出来的验证码永远不对。
解决办法：
- 回到目标网站，重新获取 TOTP 密钥/扫描二维码
- 从扫码 App 分享给 KeePassDX，重新配置
- 确认分享的链接格式是
otpauth://totp/...或 Steam 的格式
参数不匹配
手动配置 OTP 时如果参数和网站不一致，也会出问题：
| 参数 | 网站要求 | KeePassDX 默认 | 不匹配后果 |
|---|---|---|---|
| 算法 | SHA-1 | SHA-1 | 大多数网站匹配 |
| 周期 | 30 秒 | 30 秒 | 匹配 |
| 位数 | 6 位 | 6 位 | 匹配 |
| Steam 格式 | 自定义 | 标准 TOTP | Steam 验证码不对 |
如果是 Steam 账户：必须用 Pro 版的 Steam OTP 配置，不能用标准 TOTP。
服务端漂移
某些服务商会故意让服务器时间漂移（虽然不常见）。如果你的时间完全正确但验证码还是不对：
- 确认网站显示的验证码和你 KeePassDX 里的是否有规律差——如果总差 1-2 位，可能是算法问题
- 把 KeePassDX 里的 OTP 配置里的周期从 30 改成 28 或 32 试试（不推荐，治标不治本）
- 或者在 Google Authenticator / 其他 2FA App 里重新扫同一个二维码，看验证码是否和 KeePassDX 一致（应该一致——这是标准算法）
倒计时闪烁/不停刷新
这是 KeePassDX 条目列表的正常行为：
- TOTP 每 30 秒刷新一次
- 倒计时显示剩余秒数
- 快到 0 时会闪一下提醒即将刷新
如果觉得太吵，可以：
- 进入条目详情看完整视图（倒计时不会闪烁）
- 或开启 OTP 通知（设置 → 表单填充 → OTP 通知）
Pro 版 Steam TOTP 不工作
确认：
- 你确实已解锁 Pro 功能（Google Play 内购记录）
- OTP 配置里类型选的是"Steam"不是"标准 TOTP"
- 密钥格式正确（Steam 的密钥和标准 otpauth:// 密钥格式不同）
- KeePassDX 版本 ≥ 4.3.0（Steam 算法是后来加的）