二维码不等于 TOTP：如何读懂 otpauth URI 与兼容参数
验证器页面上的二维码只是编码载体。它可能包含 TOTP 配置，也可能是登录确认、设备绑定、迁移包或平台专用协议。判断能否导入，首先要读取二维码内容；即使看到otpauth://，还要继续核对类型、密钥、算法、位数和周期。
一个典型的 URI
otpauth://totp/Example:alice@example.com?secret=BASE32SECRET&issuer=Example&algorithm=SHA1&digits=6&period=30可拆成以下字段：
| 字段 | 含义 | 常见问题 |
|---|---|---|
totp | 基于时间的一次性密码 | 若为hotp，则是计数器模式，不能按 TOTP 处理 |
| Label | 条目显示标签，常含服务名和账号 | 标签不参与验证码计算，但重复命名会增加误用风险 |
secret | Base32 表示的共享密钥 | 缺失、截断或多余字符都会导致结果不同 |
issuer | 发行方/服务名 | 主要用于识别，应与标签保持清楚一致 |
algorithm | HMAC 哈希算法 | 常见 SHA-1、SHA-256、SHA-512，双方必须一致 |
digits | 输出位数 | 常见 6 位或 8 位 |
period | 时间步长 | 常见 30 秒，也可能不同 |
为什么“能扫进去”仍不代表兼容
有些验证器会接受二维码，却忽略未支持的参数，或回落到默认值。例如目标平台按 SHA-512 计算，而验证器固定使用 SHA-1，界面仍可能生成六位数，但平台不会接受。
因此兼容性至少有三层：
- 格式兼容：能识别 URI；
- 参数兼容：算法、位数、周期和密钥解析一致；
- 业务兼容：平台绑定和后续登录均成功。
缺少第三层真实验证，不能把产品列入“已支持平台”。
不要直接展示生产密钥
读取二维码参数时，优先在测试账号和隔离环境中进行。不要把生产二维码上传到在线解码网站，也不要把完整secret放进工单、聊天记录、截图或文章。
如果需要留存测试证据，可以记录：
Scheme: otpauth Type: totp Algorithm: SHA512 Digits: 6 Period: 30 Secret: 已脱敏，仅记录长度与格式是否有效密钥只要被第三方复制，就可能在同一时间生成有效验证码。二维码本身应按认证凭据处理，而不是普通图片。
验收一个验证器的正确步骤
第一步：确认平台入口
在平台官方安全设置中选择“Authenticator App”“验证器应用”或明确的 TOTP 入口。若页面要求安装平台专用 App，不能自行替换成通用验证器。
第二步：核对参数
读取测试二维码或手动配置说明，记录算法、位数、周期。平台没有公开参数时，以测试账号实测为准，不能靠六位码外观猜测。
第三步：连续核对两个周期
完成绑定后，至少等待一次验证码变化，并验证下一周期仍能通过。这样可以减少偶然踩中时间窗口造成的误判。
第四步：完成真实登录
退出测试账号后重新登录，并确认恢复码或备用方式已保存。只在绑定页面提交成功，还不等于完整登录链路可用。
第五步：记录环境
记录测试日期、账户类型、地区、客户端版本和平台入口。平台可能按地区、套餐或组织策略提供不同选项。
参数用于排查，结果要靠完整登录验证
读取 URI 参数可以帮助定位问题，但不能只凭参数表判断兼容。更可靠的验收顺序是：验证器能够添加条目、平台接受当前动态码、退出后能够重新登录，并且恢复码已经保存。参数和实测结果不一致时，优先保留测试记录，再继续排查二维码内容、设备时间和平台策略。
最小测试记录
- 平台与账户类型： - 测试日期： - 官方设置入口： - URI 类型： - Algorithm： - Digits： - Period： - 是否成功导入： - 连续两个周期是否通过： - 是否完成重新登录： - 恢复方式是否保存： - 结论：待确认 / 条件支持 / 已通过判断二维码时，先问“它编码了什么”，再问“双方是否按同一组参数计算”。这比看到六位码后直接下结论可靠得多。
用 Free2FA 做一次 URI 验收
理解otpauth最好的方式不是把二维码上传到解析网站，而是完成一次安全的真实验收。可以使用「二次验证码 Free2FA」，从 GitHub、OpenAI 或 Google Account 官方安全设置获取二维码，完成添加后观察两个周期，再退出账号重新登录。
二维码、手动密钥和动态码都不要放进截图、日志或在线工具。Free2FA 能添加条目只是第一步，平台接受验证码并成功登录才是兼容结论。