Breeze v2+仅支持Laravel 10.27+和PHP 8.1+，Laravel 9用户须锁定breeze v1.x；安装时需按需选择前端栈（Blade/Vue/React/Inertia/API）；迁移前须配置.env并执行migrate；路由依赖RouteServiceProvider加载auth.php，冲突时建议新建项目重装。
安装 Breeze 前先确认 Laravel 版本是否匹配
新版 Breeze（v2+）只支持 Laravel 10.27+ 和 PHP 8.1+，如果你用的是 Laravel 9 或更早版本，breeze:install 会报错或生成不兼容的脚手架。Laravel 9 用户必须锁定 laravel/breeze v1.x，比如运行：
composer require laravel/breeze:^1.24否则后续执行
php artisan breeze:install 时会提示 Call to undefined method Illuminate\Foundation\Application::scoped()——这是 Laravel 10 才引入的方法。
执行 breeze:install 时选对前端栈和认证类型
Breeze 默认生成 Blade + Laravel Jetstream 风格的登录页，但实际它支持多种组合：Vue、React、Inertia，甚至 API 模式。关键看你要什么：
- 纯后台管理（无 SPA）→ 直接运行
php artisan breeze:install，默认用 Blade，开箱即用 - 想用 Vue 写后台界面 → 加
--vue参数：php artisan breeze:install --vue，但要注意这会跳过 Blade 视图，且需额外跑npm install && npm run dev - 只需要 API 认证（比如对接小程序后台）→ 用
--api，它不生成任何视图，只配好 Sanctum 和基础路由
漏选参数不是大问题，但选错会导致后续要手动删文件或重装——比如误用 --react 后发现没配好 Vite，反而卡在编译环节。
迁移数据库前别忘了配置 .env 和运行 migrate
Breeze 安装完只是生成代码，用户表结构还在 database/migrations/2014_10_12_000000_create_users_table.php 里，没执行迁移就访问 /login 会抛出 SQLSTATE[42S02]: Base table or view not found: 1146 Table 'xxx.users' doesn't exist。必须按顺序做三件事：
- 检查
.env中DB_DATABASE、DB_USERNAME、DB_PASSWORD是否填对（本地常用root空密码，但 MySQL 8+ 默认禁用空密码，容易连不上） - 运行
php artisan migrate，如果报错说SQLSTATE[HY000] [1045] Access denied，大概率是数据库凭据错了 - 再跑
php artisan db:seed（可选），Breeze 不自带 seed，但你可以自己加UserSeeder快速建个管理员账号
后台路由没生效？检查 RouteServiceProvider 和中间件
Breeze 默认把所有认证相关路由注册在 routes/auth.php，但它依赖 App\Providers\RouteServiceProvider 中的 mapWebRoutes() 调用。如果你改过这个 Provider（比如为了多域名拆路由），可能漏掉 require __DIR__.'/../routes/auth.php';。另一个常见坑是：Breeze 的 /dashboard 路由加了 auth 中间件，但如果你在 app/Http/Kernel.php 里注释或挪动了 auth 的定义位置，登录后会 302 回首页而不是进 dashboard。
验证方法很简单：运行 php artisan route:list --name=login，看有没有输出；没有就说明路由根本没加载。
真正麻烦的是混合使用 Jetstream 或 Fortify 的老项目——Breeze 会跟它们冲突，删不干净 vendor 里的重复服务提供者，导致 php artisan config:clear 都救不回来。这种时候不如直接新建 Laravel 项目重装 Breeze。
