社交登录这事儿，说穿了就四个字：一看就懂，一跑就崩。很多人拿着文档调接口，token换得好好的，一到绑账号那步就翻车。其实问题大多集中在参数合规、用户状态映射和token生命周期的管理上——看着零碎，但踩过坑的人都知道，套路基本就那几样。

第三方账号绑定时，auth_code 换 access_token 失败的常见原因

不是接口调不通，而是没按平台规则拼参数或漏了必要头信息。微信开放平台要求 grant_type=authorization_code 且必须用 POST，而 QQ 登录的 client_id 和 client_secret 必须 URL 编码后再传——不编码会返回 100010 invalid request。

• 微信回调拿到的 code 5分钟内必须兑换，超时直接报 invalid code
• QQ / 微博的 redirect_uri 必须和申请应用时填写的完全一致（含末尾斜杠），否则返回 redirect_uri_mismatch
• ThinkPHP 的 Http::post() 默认不带 Content-Type: application/x-www-form-urlencoded，手动补上才不会被微博接口拒收

用户首次登录 vs 已绑定账号：如何用 whereOr() 安全查库

不能只查 openid，得同时支持「已绑手机号」和「未绑但邮箱重复」两种合并逻辑。直接 where('openid', $openid) 会漏掉用同一邮箱注册过但没绑三方的用户。

• 用 Db::name('user')->whereOr([['openid', $openid], ['email', $email]])->find()，避免两次查询引发竞态
• 如果查到记录但 openid 为空，说明是老用户，此时要更新 openid 和 platform 字段，而不是新建
• 注意 MySQL 的 WHERE OR 在大表上可能走不了索引，给 openid 和 email 都加单独索引

think-auth 扩展不兼容社交登录的权限校验断点

原生 Auth::check() 只认 user_id，但三方登录初期根本没写入 user_id 到 session，直接调用会永远返回 false。

• 必须在登录成功后手动调用 Auth::login($user, true)，第二个参数 true 表示跳过密码验证
• 别依赖 Auth::id() 判断是否登录，改用 Auth::check() && Auth::id() > 0，防止未初始化时返回 null 导致空指针
• 如果用了多 guard（比如 admin/user 分离），记得在配置里把 user guard 的 user_model 指向你自己的用户模型，否则 Auth::user() 拿不到扩展字段

Token 过期刷新时，refresh_token 被微信回收的静默失败

微信的 refresh_token 用一次就失效，且不提供「是否已用」的查询接口。如果用户在两个设备上同时操作，第二次刷新必然失败，但错误响应是 {"errcode":40001,"errmsg":"invalid credential"}，看起来像 access_token 错了。

• 把 refresh_token 存进数据库并加 for update 行锁，避免并发覆盖
• 刷新失败后不要立即重试，先查本地 DB 是否已有有效 access_token 且未过期（微信 token 有效期 2 小时）
• 微信不支持用旧 refresh_token 换新 token 后再换回旧的，所以一旦失败，只能引导用户重新授权

社交登录最麻烦的从来不是拿 token，而是用户身份在不同生命周期里的状态映射——比如一个手机号绑了微信又解绑，再绑微博，这时候数据库里留哪个 openid、哪个 platform 字段该清不该清，没有银弹，只能靠每次写库前加日志和状态快照。