应使用 league/oauth2-client 而非手写 OAuth 2.0 客户端逻辑，因手动实现易漏 state 校验、redirect_uri 全匹配、Basic 认证头等关键安全细节，导致 CSRF、401 错误等问题。
别手写 OAuth 2.0 客户端逻辑，直接用 league/oauth2-client；授权码模式必须走服务端换 token，隐式模式已不推荐，刷新令牌不能复用旧 refresh_token。
为什么不能自己拼 authorization URL 和 POST 换 token
手动构造 URL 或 curl 请求极易漏掉关键安全约束：缺 state 参数会引入 CSRF 漏洞；redirect_uri 少个斜杠、协议写成 http 而不是 https，平台直接返回 invalid_redirect_uri；用 mt_rand() 生成 state 会被暴力猜中；把 client_secret 暴露在前端 JS 里等于公开后门。
常见错误现象包括：跳转后无 code、回调页报 invalid_grant、token 换成功但后续请求始终 401。这些问题 90% 都源于手动实现时忽略协议细节或状态校验。
-
redirect_uri必须和服务商后台注册的**全字符串一致**（含协议、端口、路径、末尾斜杠） -
state必须由服务端生成：bin2hex(random_bytes(16))，并存入$_SESSION['oauth2state'] - 换 token 的 POST 请求必须带
Authorization: Basic {base64(client_id:client_secret)}头 - body 必须用
http_build_query()拼装，不能手拼字符串或 JSON
授权码模式下怎么安全地换 access_token
拿到 code 后，必须由 PHP 后端发起 POST 请求到 urlAccessToken，绝不能让浏览器发。微信等非标准平台还需额外处理字段缺失问题——比如它不返回 expires_in，得自己算 time() + 7200；也不返回 refresh_token，意味着无法刷新。
立即学习“PHP免费学习笔记（深入）”；
关键点：
- 请求头
Content-Type必须是application/x-www-form-urlencoded - 参数必须包含：
grant_type=authorization_code、code、redirect_uri（再次传，且必须和授权时一致） - 响应体是 JSON，需用
json_decode($res, true)解析，并检查是否有errcode（微信特有）或error字段 - 成功后立即
unset($_SESSION['oauth2state'])，防止重放
隐式模式（Implicit Grant）现在还能用吗
不能。OAuth 2.0 RFC 6749 已明确将隐式模式标记为“不推荐”，主流平台（Google、GitHub、Microsoft）已弃用或限制使用。它要求前端 JS 直接从 URL fragment（#access_token=xxx）里取 token，既无法验证 state，也无法隐藏 client_secret，还容易被 XSS 窃取。
如果你看到文档里还有 response_type=token，说明该平台尚未升级，但你不该主动选它。现代替代方案是 PKCE（code_challenge + code_verifier），适用于纯前端应用，league/oauth2-client 本身不内置支持，需手动扩展或换用 firebase/php-jwt + 自行封装。
refresh_token 怎么用才不会失效或冲突
刷新 token 不是“拿旧 refresh_token 再 POST 一次”那么简单。每次成功刷新后，旧 refresh_token 必须立即作废（某些平台如 Auth0 默认单次有效），否则攻击者截获后可无限续期。而且不是所有平台都支持刷新——微信完全不返回 refresh_token，GitLab 要求额外传 scope，而自建 league/oauth2-server 则依赖 RefreshTokenRepositoryInterface::getNewRefreshToken() 的实现是否调用了 revokeUsedRefreshToken()。
实操要点：
- 换 token 成功响应里若含
refresh_token，务必和新access_token一起持久化存储（建议加密后存数据库，而非 Cookie） - 刷新请求的
grant_type是refresh_token，且 body 中不能带code或redirect_uri - 若响应返回
invalid_grant或invalid_refresh_token，大概率是旧 token 已被用过一次，或服务端未实现单次有效逻辑 - 调试时可用
error_log(print_r($response, true), 3, '/tmp/oauth.log')查原始响应，别只看 HTTP 状态码
最常被忽略的是：不同平台对 redirect_uri 的校验粒度差异极大，微信要求末尾带 #wechat_redirect，GitHub 强制绝对 URL，而自建 server 若没实现 RedirectUriRepositoryInterface::validateRedirectUri() 的全量比对，就等于没设防。
