直接用phpgangsta/googleauthenticator就够了，它兼容PHP 5.3+、无外部依赖、RFC 6238合规且持续维护；推荐Composer安装：composer require phpgangsta/googleauthenticator，或手动引入单文件；密钥须为16位Base32字符串并存入VARCHAR(16)字段；verifyCode容差参数2表示±60秒偏差；务必配置NTP确保服务器时间准确。
直接用 phpgangsta/googleauthenticator 就够了，别折腾其他库——它兼容 PHP 5.3+、无外部依赖、RFC 6238 合规，且至今仍在维护。其他库要么已弃用（如早期 huaweichenai/google-authenticator），要么引入额外组件（如 pragmarx/google2fa + bacon/bacon-qr-code），徒增部署复杂度和安全面。
安装 php-gangsta/googleauthenticator 库的两种可靠方式
你不需要 clone 整个仓库再手动加载，Composer 是唯一推荐路径：
- 运行
composer require phpgangsta/googleauthenticator，自动下载并注册自动加载 - 若项目禁用 Composer（极少数遗留环境），可下载
GoogleAuthenticator.php单文件，放入/lib/目录后用require_once 'lib/GoogleAuthenticator.php';引入 - ⚠️ 避免用
git clone https://gitcode.com/gh_mirrors/go/GoogleAuthenticator——该镜像非官方，且不含 composer autoloading 配置，容易导致Class not found
用户密钥生成与数据库存储的关键细节
密钥不是随便存字符串，必须满足 Base32 编码 + 长度严格为 16 字符，否则手机端扫码失败或验证总返回 false：
- 调用
$ga->createSecret()生成密钥，它内部已做 Base32 编码和长度校验 - 数据库字段必须是
totp_secret VARCHAR(16)，不能是TEXT或带默认值的NULL（DEFAULT NULL可以，但首次启用时必须显式写入非空值） - 不要对密钥再做
base64_encode或md5——TOTP 算法直接消费原始 Base32 字符串 - 密钥一旦生成，就应立即存库并返回给前端生成二维码；不要缓存、不要延迟写入，否则用户扫码后验证必失败
verifyCode() 的时间容差参数到底怎么设
这个参数不是“允许误差秒数”，而是“允许跨越几个 30 秒窗口”：
立即学习“PHP免费学习笔记（深入）”；
-
$ga->verifyCode($secret, $input, 1)= 允许当前窗口 ±1 个窗口（即最多 ±30 秒偏差） -
$ga->verifyCode($secret, $input, 2)= 允许当前窗口 ±2 个窗口（即最多 ±60 秒偏差） - 生产环境建议用
2：既覆盖常见设备时间漂移（尤其 Android 低端机），又不扩大攻击窗口 - 服务器时间不准会直接导致验证失败——务必配置 NTP，运行
ntpq -p检查偏移量，超过 ±1 秒就得调
getQRCodeGoogleUrl() 生成的链接为什么扫不了
二维码内容本质是 URI，格式错误或缺失字段会导致 Google Authenticator 拒绝识别：
- 必须传三个参数：
$ga->getQRCodeGoogleUrl('MyApp', $secret, 'user@example.com') - 第一个参数是 issuer（应用名），第二个是密钥，第三个是账户标识（通常是用户名或邮箱）
- issuer 和 account 里不能含空格或特殊字符（如
@必须 URL 编码，但库内部已处理，你传原始邮箱即可） - 生成的 URL 以
otpauth://totp/...开头，如果浏览器打开是乱码或 404，说明生成逻辑被截断或输出前被 htmlspecialchars 过滤了——检查模板层是否误转义
最常被忽略的一点：用户启用双因素后，密码登录流程必须拆成两步——先验密码，成功后再跳转到验证码输入页，并在 session 中标记“已通过第一因子”。跳过这一步，等于把双因素做成摆设。
