Passport配置关键在正确初始化密钥和客户端：必须先执行php artisan migrate创建oauth_clients等表，再运行passport:install生成可读权限的密钥文件，User模型需继承Authenticatable并使用HasApiTokens，密码授权还需单独创建password类型客户端。
Passport 配置不是“装完就能用”，关键在 passport:install 之后是否正确初始化密钥和客户端，否则所有令牌生成、验证都会失败。
运行 php artisan passport:install 前必须确认迁移已执行
Passport 的 oauth_clients、oauth_access_tokens 等表依赖数据库迁移。如果跳过 php artisan migrate 就直接运行 passport:install，命令会静默成功，但后续创建客户端或颁发 token 时抛出 SQLSTATE[42S02]: Base table or view not found 错误。
- 务必先执行
php artisan migrate（不是migrate:fresh，除非你清楚后果） - 若已安装过 Passport 并想重置，应先
php artisan migrate:rollback --step=1回滚最后一批迁移，再重新 migrate - 使用
Passport::ignoreMigrations()后，必须手动发布并检查迁移文件：php artisan vendor:publish --tag=passport-migrations
passport:install 生成的密钥必须可读且权限正确
passport:install 会在 storage/ 下生成 oauth-private.key 和 oauth-public.key。如果 Web 服务器用户（如 www-data）无权读取这两个文件，调用 Passport::tokenResponse() 或验证 token 时会报 file_get_contents(): failed to open stream: Permission denied。
- 检查文件权限：
ls -l storage/oauth-*.key，确保属组可读（如-rw-r--r--） - 不要把密钥文件提交到 Git（已在
.gitignore中默认忽略，但需确认） - 生产环境部署时，若使用容器或部署脚本，需显式
chown或chmod这两个文件
User 模型必须 use HasApiTokens，且不能遗漏 Authenticatable
仅添加 HasApiTokens trait 不足以启用 Passport 认证——该 trait 依赖模型具备 Laravel 认证基础能力。常见错误是自定义 User 模型时继承了 Model 而非 Authenticatable，导致 $user->createToken() 报 Call to undefined method createToken()。
- 确认
User类继承自Illuminate\Foundation\Auth\User（即Authenticatable） - 必须同时 use
Laravel\Passport\HasApiTokens，顺序无关，但缺一不可 - 如果用了多模型认证（如 Admin/User 分离），每个需 API 认证的模型都得单独配置
密码授权（Password Grant）客户端需手动创建并保存 client_id/client_secret
Passport 默认只创建一个用于私人访问令牌（Personal Access Token）的客户端，而密码授权（password grant_type）需要额外注册专用客户端。漏掉这步会导致 POST /oauth/token 时返回 {"error":"invalid_client","message":"Client authentication failed"}。
- 运行
php artisan passport:client --password创建密码授权客户端 - 命令输出的
client_id和client_secret必须存入前端或调用方配置，不可丢弃 - 该客户端不会出现在
oauth_clients表的 “personal access” 类型中，类型字段为password
密钥文件路径、数据库表结构、客户端类型、模型继承链——这四个点任一出错，都会让 Passport 在 token 颁发或验证环节静默失败或报错模糊。调试时优先检查它们，比翻日志更快。
