Laravel Passport需四步方可启用：环境就绪（APP_KEY生成、users表存在、版本匹配）、php artisan migrate建表、passport:install生成密钥与客户端、手动配置User模型trait、AuthServiceProvider中Passport::routes()及auth.php中api guard设为passport。
直接装 laravel/passport 不等于能用 OAuth2——它必须和 Laravel 认证体系深度配合，缺一环就会卡在 404、500 或 Class not found。核心是四步：环境就绪 → 数据库建表 → 密钥与客户端生成 → 路由与守卫配置。
安装前必须确认的三件事
Passport 不是独立插件，它依赖 Laravel 基础设施：
-
APP_KEY 已生成：运行
php artisan key:generate，否则令牌加密失败 -
users 表存在且数据库连通：Passport 会向该表添加
tokenable_type和tokenable_id字段，迁移前必须能查到 users -
Laravel 与 Passport 版本匹配：Laravel v10+ 对应 Passport v12+；v9 对应 v11；版本不匹配会报
Call to undefined method Passport::routes()
标准安装与迁移顺序不能错
命令必须严格按顺序执行，跳步或颠倒会导致后续全部失败：
- 执行
composer require laravel/passport - 立即运行
php artisan migrate（不是migrate:fresh，除非你清楚后果） - 再运行
php artisan passport:install—— 它会生成oauth-private.key和oauth-public.key，并创建 Personal Access Client 和 Password Grant Client，终端输出的client_id和client_secret务必保存
关键配置项必须手动补全
光跑命令不够，以下三处漏掉任何一项都会导致鉴权失效：
-
User 模型要加 trait：确保
App\Models\User（或App\User）继承Authenticatable，并使用HasApiTokens -
注册 Passport 路由：在
app/Providers/AuthServiceProvider.php的boot()方法里调用Passport::routes()，不是写在routes/web.php或api.php -
切换 API 认证驱动：修改
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 只认表单参数 - 密码模式必须先创建专用客户端：运行
php artisan passport:client --password，普通--client不支持该模式 - 用户名字段默认是
email，不是username；若改过登录字段，需同步调整验证逻辑
