laravel passport密码模式可行但仅限第一方可信客户端，本质是带token管理的api登录接口而非标准oauth2流程；需正确配置client_id/client_secret、username字段匹配、https环境及手动启用grant_type。
直接用 Laravel Passport 的密码模式（password grant）是可行的，但前提是客户端完全可信、不暴露用户凭据到第三方，且你已明确放弃 OAuth2 的“授权委托”本意——它本质退化为一个带 token 管理的 API 登录接口，不是标准 OAuth2 流程。
为什么 password grant 在 Laravel Passport 中仍被保留
它不是推荐的通用方案，而是为第一方客户端（如你自己的管理后台、内部 App）设计的简化路径。Laravel 官方文档从 9.x 起已标注该模式“deprecated in future OAuth2 specs”，但 Passport 仍支持，因为实际项目中仍有强控制场景需要：用户输入账号密码 → 后端直连验证 → 返回 access_token。
常见错误现象包括：
-
invalid_client：请求中没传client_id或client_secret，或值错误（注意：passport:install输出的第二组 ID/secret 才是 password client） -
invalid_grant：用户名/密码错、用户未激活、username字段名不匹配（默认是email，若用username需额外配置） -
unsupported_grant_type：grant_type=password拼写错误，或没在config/auth.php中启用passwordgrant（Laravel 11 默认禁用，需手动加）
password grant 请求必须带的参数和头
这是一个标准 POST 请求，发往 /oauth/token，必须满足以下条件：
- Content-Type 必须是
application/x-www-form-urlencoded（不能是 JSON） - Body 中必须包含：
grant_type=password、client_id、client_secret、username、password - 如果启用了作用域（
scope），需显式传空字符串scope=或指定值，否则会因 scope 不匹配失败 - 不支持 bearer token 认证该接口本身——它就是用来拿 token 的
示例 cURL（替换对应值）：
curl -X POST http://your-app.test/oauth/token \ -H "Accept: application/json" \ -d "grant_type=password" \ -d "client_id=2" \ -d "client_secret=your-secret-here" \ -d "username=test@example.com" \ -d "password=secret123" \ -d "scope="
如何让 username 字段支持手机号或用户名而非仅 email
Passport 默认调用 User::where('email', $username)->first()，要改这个行为，得重写密码 grant 的验证逻辑：
- 在
AuthServiceProvider::boot()中，调用Passport::withPasswordGrantUserResolver() - 传入一个闭包，接收
$username，返回匹配的User实例（可按email、phone、username多字段查） - 别漏掉密码校验：闭包只负责找用户，后续仍走 Laravel 的
Hash::check()
代码片段：
Passport::withPasswordGrantUserResolver(function ($username) {
return User::where('email', $username)
->orWhere('phone', $username)
->orWhere('username', $username)
->first();
});
容易被忽略的兼容性与安全点
这一块最容易出线上问题：
- Laravel 11 默认关闭
passwordgrant，需在config/auth.php的guards.api下手动加'provider' => 'users'并确认providers.users.driver是eloquent - HTTPS 强制要求：生产环境未配 HTTPS 时，Passport 会静默拒绝
password请求（不报错，只返回 401） - 令牌刷新依赖
refresh_token，但它默认有效期 30 天；若前端没存好或丢了，用户就得重新输密码——这不是 bug，是设计使然 - Angular 等前端调用时，
client_secret会暴露在 JS 里，所以仅限第一方可信客户端；绝不能用于第三方集成
真正难的不是调通接口，而是判断清楚：你到底需要的是 OAuth2 授权，还是只是个带过期机制的登录 API。选错起点，后面全是补丁。
