Laravel怎么安装Passport OAuth2鉴权_Laravel标准OAuth接口开发与令牌管理【详解】

laravel Passport 需先配置 app_KEY、确保 users 表存在且数据库连通、匹配 Laravel 与 Passport 版本，再执行 migrate 和 passport:install；AuthServiceProvider 中需调用 Passport::routes()，并配置 auth.php 的 api guard 为 passport。

直接装 laravel/passport 不等于能用 OAuth2——它默认依赖 Laravel 自带的用户模型和数据库结构，且必须在已配置好 APP_KEY 和数据库迁移的前提下初始化，否则运行 php artisan passport:install 会报 class 'LaravelPassportPassport' not found 或 SQLSTATE[42S02]: Base table or view not found。

安装前必须确认的三件事

Passport 不是开箱即用的“插件”，它是深度耦合 Laravel 认证体系的扩展包：

• APP_KEY 已生成（php artisan key:generate），否则加密令牌失败
• 数据库已可连接，且 users 表存在（Passport 会向该表加 Tokenable_type 和 tokenable_id 字段）
• Laravel 版本匹配：v10+ 需用 Passport v12+；v9 对应 v11；不匹配会导致 Call to undefined method LaravelPassportPassport::routes()

标准安装与基础路由注册

执行命令顺序不能错，且 php artisan migrate 必须在 passport:install 前完成：

composer require laravel/passport php artisan migrate php artisan passport:install

然后在 AuthServiceProvider@boot() 中注册路由（注意不是 routes/web.php）：

use LaravelPassportPassport;  public function boot() {     $this->registerPolicies();      Passport::routes(); // 这行必须有，否则 /oauth/token 等接口 404 }

最后在 config/auth.php 的 guards.api 下把 driver 改为 passport，否则中间件 auth:api 不识别 Bearer Token。

客户端创建与令牌获取常见卡点

开发时最常卡在「能注册客户端但拿不到 access_token」，原因多为：

• 请求 /oauth/token 时用了 application/x-www-form-urlencoded，但没设 Content-Type: application/x-www-form-urlencoded 头（postman 默认不带）
• 传参用 jsON body（如 {"grant_type":"password",...}），但 Passport 只认表单编码参数
• password 授权模式需先调用 php artisan passport:client --password 创建密码型客户端，普通 --client 不支持
• 用户未实现 HasApiTokens trait，或没在 User 模型中调用 use HasApiTokens;

刷新令牌与作用域控制的实际写法

Passport 默认返回 refresh_token，但不会自动续期——你得自己存、自己传、自己换。关键点：

• 刷新请求必须用原 refresh_token + client_id + client_secret，缺一不可
• 作用域（scopes）不是靠中间件自动过滤，而是要在控制器里显式校验：$request->user()->tokenCan('edit-posts')
• 定义 scope 要在 AuthServiceProvider@boot() 中调用 Passport::tokensCan([...])，否则 scope:xxx 参数会被忽略
• 前端若用 axios，记得设 withCredentials: true 才能携带 cookie（仅限 cookie-based session 场景，Bearer Token 不需要）

复杂点在于：Passport 的 Personal access Token 和 Client Credentials 模式共享同一套密钥，但权限模型完全不同；一旦混用，容易出现 token 有权限却无法访问资源的情况——这时候别急着重装，先查 oauth_access_tokens 表里的 scopes 字段是否为空字符串或 json 格式错误。