Laravel ≥9.25 原生支持 TOTP 两步验证，需三字段（two_factor_secret、two_factor_recovery_codes、two_factor_confirmed_at）齐全且 verifyKey() 显式传 $window=1；缺字段或未设 confirmed_at 会导致静默失败，Fortify 需手动拦截登录并重定向至挑战页，Livewire 中应调用 getTwoFactorSecretQrCodeUrl() 而非 decrypt()。
直接用 Laravel ≥9.25 的 TwoFactorAuthenticatable trait 就能跑通标准 TOTP 流程，不用装第三方包——但必须三字段齐全、verifyKey() 显式传 $window = 1，否则验证码总提示无效。
数据库迁移缺一不可：three 字段必须同时存在
只加 two_factor_secret 是常见错误。Laravel 原生验证逻辑在 confirmTwoFactorAuthentication() 和 useRecoveryCode() 中会严格检查以下三个字段：
-
two_factor_secret：TEXT 类型，Base32 编码密钥（如JBSWY3DPEHPK3PXP），不能为 NULL -
two_factor_recovery_codes：TEXT 类型，存加密后的 JSON 字符串（如{"0":"xk9m2v8q","1":"t7r4f1p6"}），不是明文逗号分隔 -
two_factor_confirmed_at：TIMESTAMP NULLABLE，用于区分“已启用但未确认”和“已启用且已确认”
漏掉任意一个，前端扫码后点击“确认”会静默失败，无报错也无跳转。
Fortify 登录后不跳转 2FA 页面？得自己拦截
Features::twoFactorAuthentication() 只提供设置界面和密钥存储，不会自动阻断登录流程。用户输完密码就进去了，2FA 形同虚设。
必须在 app/Providers/FortifyServiceProvider.php 的 boot() 方法中重写认证逻辑：
- 用
Fortify::authenticateUsing()包裹原始验证 - 验证通过后，检查
$user->two_factor_secret && !$request->session()->has('two-factor-authenticated') - 成立则返回
redirect('/two-factor-challenge')，而非直接返回$user
别依赖 config/fortify.php 里的 features 配置，它不触发拦截。
Laravel Cloud（cloud.laravel.com）。此技能用于处理所有 Laravel Cloud 请求，包括搜索和读取数据。只要任务涉及 Laravel Cloud，即使用此技能。
Livewire 中别直接 decrypt($user->two_factor_secret)
模板或 Livewire 组件里调用 decrypt() 容易因 session 加密密钥未加载或上下文不一致而抛 DecryptException，结果是 QR 码空白或 404。
正确做法是调用模型方法：
- 用
$user->getTwoFactorSecretQrCodeUrl()生成 URL（内部已处理解密 + URL 编码） - 该方法要求
two_factor_secret不为空，且two_factor_confirmed_at为 NULL（即处于“待确认”状态） - 不要在 Blade 中写
{{ decrypt($this->user->two_factor_secret) }}，这是 Jetstream 模板的过时写法
verifyKey() 总失败？先看时钟和 session
输入 6 位码却提示 Invalid verification code，90% 不是算法问题，而是环境断开：
- 没传
$window = 1：原生verifyKey()默认$window = 0，只校验当前秒级窗口；服务器与手机时间偏差 >30 秒就必挂；生产务必显式传1或2 - Session 未维持：TOTP 校验必须发生在已登录且 session 有效的上下文中；若用 API 方式调用，需确保
session_start()已触发、session driver 配置正确 -
two_factor_confirmed_at为空：Laravel 会直接跳过验证，认为“还没确认启用”，返回 false 而不报错
最易忽略的是：two_factor_confirmed_at 字段必须由你手动 set，trait 不自动填；用户扫码后点确认按钮，控制器里得调 $user->confirmTwoFactorAuthentication() 才会写入该时间戳。
