Passport 需先执行数据库迁移再安装，否则 /oauth/token 会因表缺失报错；必须配置完整路由、正确客户端类型、权限合规的密钥文件，并确保 User 模型继承 Authenticatable 且启用对应 guard。
Passport 不是“装完就能登录”的认证组件，它本质是 OAuth2 服务端实现，必须先建表、配路由、设守卫，否则 /oauth/token 肯定 500 或 401。
数据库迁移没跑，/oauth/token 必然报 SQLSTATE[42S02]
这是最常卡住人的第一步：只执行了 php artisan passport:install，却漏掉 php artisan migrate。Passport 的 oauth_clients、oauth_access_tokens 等 5 张表不会自动创建，后续所有 token 请求都会因表不存在而崩。
- 务必先确认
php artisan migrate成功执行（包括 Passport 自带的 migration） - 若已误装过 Passport，别用
migrate:fresh——它会清空用户数据；改用php artisan migrate:rollback --step=1回滚 Passport 迁移，再重新migrate - 运行
php artisan passport:install前，确保storage/oauth-private.key可被 Web 用户（如www-data）读取，权限应为-rw-r--r--
Passport::routes() 配不全，/oauth/token 就是 404
默认 Passport::routes() 只注册部分端点，漏掉关键路由会导致请求直接 404，且错误不提示具体缺哪条。
- 在
app/Providers/AuthServiceProvider.php的boot()方法中，必须显式启用所需路由类型： -
$router->forAccessTokens()—— 密码模式必需（移动端、管理后台登录） -
$router->forAuthorizationCodes()—— 授权码模式必需（第三方网站接入） -
$router->forPersonalAccessTokens()—— Laravel 10+ 默认禁用，如需$user->createToken()测试，必须手动开启
密码模式拿不到 token？检查 client_id、client_secret 和 username
很多人以为 passport:install 后 POST 用户名密码就能换 token，实际不行——你得用对客户端，且字段语义不能错。
-
passport:install输出的第二组client_id/client_secret才是密码授权专用（password_client = 1），第一组是个人访问令牌用的 - POST
/oauth/token时，请求体必须含：grant_type=password、client_id、client_secret、username、password；漏任一字段或填错，直接 401 -
username字段值必须是邮箱（即使你 User 模型把$username改成phone，Passport 内置逻辑仍按 email 查） -
client_secret是服务端敏感凭据，绝不能硬编码在前端；应由后端登录接口代为调用/oauth/token并注入
$user->createToken() 报错？多半是模型没继承 Authenticatable
不是加了 HasApiTokens trait 就能用 createToken()，它底层依赖认证基础能力。
- 检查
app/Models/User.php：类声明必须是class User extends Authenticatable，不是extends Model或自定义基类 - 必须同时
use HasApiTokens和use Authenticatable（后者是父类，前者是 trait） - 如果用了多模型认证（比如
Admin和User分离），每个需 API 认证的模型都得单独配这两项 - 配置
config/auth.php中guards.api.driver为passport，否则中间件auth:api不会走 Passport 验证流程
真正容易被忽略的是密钥文件权限和客户端类型匹配——哪怕表建好了、路由也开了，只要 storage/oauth-private.key 权限不对，或者 POST 时用了个人访问客户端的 client_id 去走密码模式，/oauth/token 就会静默失败，错误信息还不明确。
