Composer安装Laravel Passport前必须检查PHP版本（≥8.0）、ext-json/ext-openssl/ext-pdo扩展，并匹配Passport版本（Laravel 9.x用v10，10+用v11）；确认AuthServiceProvider已注册，关闭代码格式化工具，配置国内镜像源。
直接装不上，大概率是 PHP 版本或扩展没对齐，不是命令写错了。
Composer 安装 Laravel Passport 前必须检查的三件事
Passport 依赖 ext-json、ext-openssl 和 ext-pdo，且最低要求 PHP 8.0（Laravel 10+ 对应的 Passport v11+）。用 php -v 和 php -m | grep -E "json|openssl|pdo" 确认。如果 Laravel 是 9.x，得用 Passport v10，它才支持 PHP 7.4；装错版本会报 Root composer.json requires laravel/passport ^11, found laravel/passport[v10.0.0, ..., v10.4.2] but these were not loaded 这类冲突错误。
- 运行
composer require laravel/passport前，先确认config/app.php里App\Providers\AuthServiceProvider::class已注册 - 如果项目启用了 Laravel Pint 或 PHP-CS-Fixer，建议先临时关掉，避免安装过程中因格式化中断导致
vendor/残留 - 国内环境记得配好镜像源：
composer config -g repo.packagist composer https://packagist.phpcomposer.com（或使用阿里云源）
安装后必须立刻执行的迁移和密钥生成
Passport 不只是加个包，它要建 5 张表（oauth_auth_codes、oauth_access_tokens 等），且需要加密密钥。漏掉任何一步，后续调用 Passport::routes() 会抛 Class 'Laravel\Passport\Passport' not found 或路由 404。
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
- 运行
php artisan migrate—— 注意不是php artisan passport:install优先 - 再运行
php artisan passport:install，它会生成加密密钥并创建 Personal Access Client 和 Password Grant Client - 如果提示
The stream or file "/path/storage/logs/laravel.log" could not be opened，说明 storage 权限不对，用chmod -R 775 storage bootstrap/cache修复
为什么 RouteServiceProvider 中必须手动加载 Passport 路由
Laravel 8+ 默认把 API 路由放在 routes/api.php，但 Passport 的 Passport::routes() 不自动挂载到该文件——它只注册路由定义，不指定中间件或前缀。如果你没在 app/Providers/RouteServiceProvider.php 的 mapApiRoutes() 里显式调用它，所有 /oauth/token 请求都会 404。
- 在
mapApiRoutes()方法末尾加一行：Passport::routes(); - 确保该方法中
Route::middleware('api')包裹了这些路由；否则client_credentials流程可能因缺少中间件而返回空响应 - 别在
web路由组里调用Passport::routes()，否则 CSRF 验证会拦截 POST 到/oauth/token的请求
最常被跳过的其实是 APP_KEY 和 Passport 密钥的分离管理：.env 里的 APP_KEY 用于 session 加密，而 php artisan passport:keys 生成的是 RSA 密钥对（storage/oauth-private.key 和 storage/oauth-public.key），两者不能混用，也不能用同一个密钥反复生成——换环境部署时，务必同步私钥文件，否则已颁发的 access_token 全部失效。
