league/oauth2-server是PHP最成熟的OAuth2实现，需手动实现四个Repository接口并构造PSR-7响应；Laravel项目建议直接集成该库而非使用Passport以获得完全控制权。
直接用 composer require 安装 league/oauth2-server 即可
不是所有 OAuth2 实现都适合生产，league/oauth2-server 是目前 PHP 生态最成熟、文档最清晰、Laravel/Symfony 都原生兼容的实现。它不带路由或控制器，只提供核心授权逻辑，这意味着你得自己接数据库、写响应逻辑——但好处是完全可控，不会被封装层绑架。
执行命令：
composer require league/oauth2-server
注意：PHP 版本需 ≥ 8.0，且必须启用 ext-sodium（现代 PHP 默认开启）；若报错 sodium_crypto_box_seal_open 找不到，请先运行 php -m | grep sodium 确认扩展已加载。
必须手动实现 GrantType 和 Repository 接口
安装完只是拿到类库，AuthorizationServer 初始化时强制要求传入四个 Repository 实例：ClientRepositoryInterface、AccessTokenRepositoryInterface、ScopeRepositoryInterface、RefreshTokenRepositoryInterface。官方不提供默认实现，因为用户的数据结构千差万别。
常见踩坑点：
- 误以为
in-memory示例代码能直接用于生产——它只适合 demo，没持久化，重启就丢 token - 把
ClientRepository::getClientEntity返回null当成正常流程，实际会导致InvalidClientException - 忘记在
AccessTokenRepository::persistNewAccessToken中设置过期时间（$accessToken->getExpiryDateTime()），结果 token 永不过期
最小可用 ClientRepository 示例（PDO）：
$pdo = new PDO('sqlite:/tmp/oauth.db');
$client = $pdo->prepare('SELECT * FROM oauth_clients WHERE client_id = ? AND revoked = 0');
$client->execute([$clientIdentifier]);
return $client->fetch() ? new ClientEntity($clientIdentifier) : null;access_token 响应必须手动构造，不能依赖框架自动 JSON 化
AuthorizationServer::respondToAccessTokenRequest 返回的是一个 ResponseInterface（PSR-7），但它的 body 是原始 JSON 字符串，且字段名、嵌套结构、是否含 refresh_token 全由你控制。很多开发者卡在这步，返回空响应或 500，其实只是没调用 $response->getBody()->write(...)。
关键操作顺序：
- 创建 PSR-7 Response 对象（如用
nyholm/psr7） - 调用
$server->respondToAccessTokenRequest($request, $response) - 从
$response->getBody()->getContents()读出 JSON，或直接输出 - 确保响应头包含
Content-Type: application/json
漏掉任一环都会导致前端收不到 access_token 字段。
Laravel 用户别直接装 laravel/passport
如果你已在用 Laravel，看到 laravel/passport 就想顺手装上——先停一下。passport 底层确实用了 league/oauth2-server，但它强绑定了 Eloquent、硬编码了 migration 和中间件逻辑。一旦你需要自定义 client 认证方式（比如 JWT client_assertion）、或对接非 Eloquent 的用户系统（如 LDAP + 自定义 token 表），Passport 的抽象层反而会成为障碍。
更轻量的做法是：
- 只
composer require league/oauth2-server - 在
App\Providers\RouteServiceProvider中注册 OAuth 路由（/oauth/token等） - 用 Laravel 的
Request和Response适配 PSR-7（通过symfony/psr-http-message-bridge）
这样既享受 Laravel 的生命周期管理，又保留对 OAuth 流程的完全掌控。
真正麻烦的从来不是 composer install 这一行命令，而是每个 Repository 里那几行 SQL 怎么写才既安全又高效——特别是 scope 权限校验和 refresh_token 的单次使用校验。
