Laravel Breeze 要求 Laravel 9.0+（推荐10.x/11.x）且 PHP ≥ 8.1，不兼容 Laravel 8.x 和 Jetstream；安装后需手动处理数据库迁移、字段扩展、路由跳转及认证方式适配。
确认 Laravel 版本与 PHP 环境是否兼容 Breeze
Breeze 要求 Laravel 9.0+（推荐 10.x 或 11.x），且 PHP ≥ 8.1。运行 php -v 和 php artisan --version 确认。若项目是 Laravel 8.x，不能直接安装 Breeze 2.x —— 官方已停止对 8.x 的 Breeze 支持，强行安装会触发 illuminate/support 版本冲突或 Class "Laravel\Jetstream\Jetstream" not found 类似错误。
- 已用 Jetstream 的项目：Breeze 不兼容 Jetstream，必须先彻底卸载 Jetstream（删配置、迁移、视图、服务提供者）
- 已有自定义认证逻辑的项目：Breeze 会覆盖
app/Http/Controllers/Auth和routes/auth.php，建议先备份这些文件 - 使用 MySQL 以外的数据库（如 PostgreSQL）：Breeze 默认迁移适配 MySQL，需手动修改
create_users_table迁移中的$table->string('email')->unique()为$table->string('email', 255)->unique()，否则 PostgreSQL 报index row size exceeds maximum
执行 Breeze 安装命令并生成基础结构
在项目根目录下运行：
composer require laravel/breeze --dev php artisan breeze:install
该命令默认启用 Blade + Inertia（Vue）双模板，但你可加参数指定：
-
php artisan breeze:install blade：只生成 Blade 视图（最轻量，适合传统 SSR） -
php artisan breeze:install react：生成 React + Inertia 模板（需额外npm install和npm run build） -
php artisan breeze:install --dark：自动注入深色模式支持（修改resources/css/app.css并添加 JS 切换逻辑）
注意：php artisan breeze:install 不会自动运行迁移。执行 php artisan migrate 前，检查生成的迁移文件是否与现有表结构冲突（例如已有 users 表且含 email_verified_at 字段，Breeze 迁移会重复添加）。
定制登录/注册字段与验证规则
Breeze 默认只校验 name、email、password。如需添加「手机号」字段，分三步改：
- 在
database/migrations/*_create_users_table.php中添加：$table->string('phone')->unique()->nullable(); - 在
app/Models/User.php的$fillable数组加入'phone' - 修改
app/Http/Requests/Auth/RegisterRequest.php的rules()方法，加入：'phone' => ['required', 'string', 'regex:/^1[3-9]\d{9}$/', 'unique:users'],
注意：Blade 模板中对应字段需手动补全（resources/views/auth/register.blade.php），Inertia/React 模板则需同步更新组件的 data 和表单绑定。Breeze 不提供字段自动注入机制，所有新增字段都需手工同步模型、请求、迁移、视图四端。
绕过默认重定向，接入现有路由逻辑
Breeze 登录成功后默认跳转到 /dashboard，注册后跳 /login。若你的项目已有 /home 或 /admin 作为首页，不要改 RedirectIfAuthenticated 中间件——它只控制未登录时的跳转。
- 登录后跳转由
app/Http/Controllers/Auth/AuthenticatedSessionController.php的store方法返回值决定，修改其return redirect()->intended('your-custom-path'); - 注册后跳转在
RegisteredUserController.php的store方法末尾，改为return redirect()->route('login')->with('status', 'User registered!'); - 密码重置成功后跳转在
NewPasswordController.php的store方法，同样可替换redirect()->route('login')
关键点：Breeze 所有控制器方法都用了 use Illuminate\Http\RedirectResponse;，返回的是 RedirectResponse 实例，不是字符串路径，别误写成 return 'home'; —— 这会导致 HTTP 200 返回纯文本，而非重定向。
最后提醒：Breeze 的 auth 中间件组（web + auth）默认启用 session 驱动。如果你用 API 认证（Sanctum token），Breeze 的 Blade 路由不适用，应改用 Sanctum 的 API 认证流程，而非强行复用 Breeze 的登录页。
