Jetstream 是 Laravel 官方为 SPA+API 场景设计的认证与团队管理骨架，需配合前端构建和数据库迁移；安装报错主因是 PHP/Node.js 版本不达标，须核对版本并执行 migrate、key:generate 和 npm build。
Jetstream 不是“装上就能用”的通用脚手架，它是 Laravel 官方为现代 SPA（Inertia 或 Livewire）+ API-first 场景设计的完整认证与团队管理骨架，必须配合前端构建流程和数据库迁移才能跑起来。
Jetstream 安装命令为什么总报错？
最常见错误是直接运行 laravel new project --jet 却没确认 PHP 和 Node.js 版本是否达标。Laravel 11 的 Jetstream 要求 PHP ≥ 8.2、Node.js ≥ 18.17；而 Laravel 10 的 Jetstream 则要求 Node.js ≥ 16.14。如果版本不匹配，npm install 会卡在 @inertiajs/vue3 或 laravel-vite-plugin 安装阶段，终端报错类似 error @inertiajs/vue3@1.0.14: The engine "node" is incompatible with this module。
实操建议：
- 先运行
php -v和node -v核对版本，Mac/Linux 用户注意which php和which node是否指向你预期的二进制文件 - 不要跳过
--git参数：Jetstream 初始化后会自动提交初始 commit，方便你后续回滚或对比改动 - 若用国内网络，安装前加镜像参数更稳：
laravel new blog --jet --repository=https://mirrors.aliyun.com/composer/
Jetstream 选 Inertia 还是 Livewire？
这不是性能或功能的优劣问题，而是开发范式的选择：Inertia 需要你写 Vue/React 组件 + Laravel 控制器返回 Inertia 响应；Livewire 则允许你在 Blade 模板里用 x-data、wire:model 直接绑定 PHP 属性——后者更适合快速原型，前者更适合长期维护的中大型 SPA。
关键差异点：
Laravel Cloud（cloud.laravel.com）。此技能用于处理所有 Laravel Cloud 请求，包括搜索和读取数据。只要任务涉及 Laravel Cloud，即使用此技能。
- Inertia 项目生成后，
resources/js/Pages下全是 .vue 文件，路由由routes/web.php中的Inertia::render()驱动；Livewire 项目则保留传统 Blade 视图，组件类在app/Livewire，通过 - Livewire 默认启用服务端渲染（SSR），但需额外配置
APP_URL和SESSION_DRIVER=database才能避免跨请求状态丢失；Inertia 默认走 XHR，对 CSRF token 和 session 管理更严格，VerifyCsrfToken中间件不能被绕过 - 两者都默认启用邮箱验证和两步验证（2FA），但 Livewire 的 2FA 表单是纯 Blade + AJAX，Inertia 的则是 Vue 组件调用
$inertia.post()
Jetstream 安装后为什么 /login 打不开？
不是路由没注册，而是数据库还没建、迁移没跑、密钥没生成。Jetstream 依赖 teams、users、password_reset_tokens 等多张表，且所有认证逻辑都基于 App\Models\User 实现了 MustVerifyEmail 和 TwoFactorAuthenticatable trait，一旦 php artisan migrate 失败，中间件就会抛出 Illuminate\Database\QueryException。
排查步骤：
- 检查
.env中DB_CONNECTION是否设为sqlite或mysql，SQLite 用户务必确认database/database.sqlite文件存在且可写 - 运行
php artisan migrate:fresh --seed（Jetstream 自带DatabaseSeeder会创建 demo team 和 user） - 确认
APP_KEY已生成：php artisan key:generate，否则加密 session 会失败，登录页加载时可能静默 500 - 如果用了 Inertia，别忘了编译前端：
npm install && npm run build（Laravel 11 默认用 Vite，不是 Mix）
Jetstream 和 Breeze 能共存吗？
不能。Jetstream 是独立的脚手架包，它会覆盖 auth 相关的路由、控制器、视图和模型方法；Breeze 同样提供 RegisterController、LoginRequest 等，二者冲突。如果你已装了 Breeze 又想切 Jetstream，必须手动清理：
- 删掉
app/Http/Controllers/Auth/下全部文件（Breeze 生成的） - 删掉
resources/views/auth/和resources/views/layouts/（Jetstream 有自己的布局） - 运行
composer remove laravel/breeze，再执行php artisan jetstream:install inertia（或livewire） - 注意
config/fortify.php和config/jetstream.php是两套配置，Jetstream 会自动发布后者，但 Fortify 的配置不会自动清除，建议检查并删除冗余项
真正容易被忽略的是团队功能权限模型——Jetstream 默认开启团队成员邀请、角色分配（admin/member）、团队个人资料隔离，这些逻辑深度耦合在 App\Providers\JetstreamServiceProvider 里，改认证流程前，先看懂 canAccessTeam 和 teamBelongsToUser 这两个 Gate 定义。
