LaravelJetstream怎么用_LaravelJetstream全栈认证方案【推荐】

Jetstream 装完就能直接用了吗？答案是否定的。它并非一个开箱即用的黑盒，恰恰相反，你需要手动确认配置、执行迁移，并深刻理解它和 Sanctum 之间的耦合关系。否则，很可能登录页正常， API 认证却在后台静默失败。

我先说几个容易踩坑的点：

jetstream:install 命令执行后，必须立刻跑 migrate

无论你执行的是 php artisan jetstream:install livewire 还是 Inertia 版本，Jetstream 都只帮你生成代码和配置文件，并不会自动执行数据库变更。它依赖的那些表——比如 teams、user_teams、personal_access_tokens——都不会自己冒出来。

• 如果漏掉了 php artisan migrate，注册时就会直接抛出 SQLSTATE[42S02]: Base table or view not found 错误。
• 如果已经运行过迁移但没清缓存，旧 migration 缓存可能导致字段缺失，比如 two_factor_secret 字段为空。
• Livewire 版本还需要确保 npm install && npm run build 成功，否则 resources/js/Pages/Auth/Login.vue（Inertia）或 resources/views/auth/login.blade.php（Livewire）里的组件根本无法渲染。

config/jetstream.php 里的 features 必须显式开启

Jetstream 默认只启用最简单的认证（注册/登录）。双因素认证、团队功能、API Token 这些，全靠 config/jetstream.php 中的 'features' 数组来开关。你不配，就等于没开，前端按钮和后端逻辑都不会加载。

• 不加 Features::twoFactorAuthentication()，用户界面就看不到“启用双重验证”按钮，two_factor_secret 字段也不会被写入。
• 不加 Features::teams()，哪怕数据库里已经有了 teams 表，TeamController 的路由和权限策略也不会注册。
• 修改之后，务必运行 php artisan config:clear，否则缓存会导致新配置无法生效。

API 认证依赖 Sanctum，但 Jetstream 不会自动发布 Sanctum 配置

Jetstream 内置了 Sanctum 支持，但只负责安装包和注册服务提供者，不会发布 config/sanctum.php。这意味着，跨域请求（比如 Vue 前端调用 /api/user）大概率会返回 401，而且错误信息极其模糊，让人摸不着头脑。

• 必须手动执行 php artisan vendor:publish --provider="Lara vel\Sanctum\SanctumServiceProvider"。
• 检查 .env 中的 SANCTUM_STATEFUL_DOMAINS 是否包含了你的前端域名（例如 localhost:5173 或 myapp.test）。
• Inertia 用户还要确认 app/Http/Middleware/HandleInertiaRequests.php 里是否已经在 share() 方法中添加了 'X-XSRF-TOKEN'，否则 XSRF 校验会失败。

二因素认证启用后，密码确认中间件会拦截敏感操作

当你启用了 Features::twoFactorAuthentication()，所有涉及密钥变更的操作——比如禁用 2FA 或重置恢复码——都会触发 ConfirmsPassword 中间件。它不会弹个提示框，而是直接跳转到 /user/confirm-password 页面，等着用户重新输入密码。

• 这个页面默认是存在的，但如果你删除了 resources/views/auth/confirm-password.blade.php，或者覆盖了 ConfirmablePasswordResponse，就会直接 404。
• Livewire 版本中，ConfirmablePasswordResponse 类位于 vendor/lara vel/jetstream/src/Actions/ConfirmablePasswordResponse.php，千万别误删。
• 如果只是开发环境想跳过确认，可以临时注释掉 app/Providers/JetstreamServiceProvider.php 中对 ConfirmsPassword 的注册。

最后，还有一个容易被忽略的细节：Jetstream 的团队功能与 Sanctum 的 API token 权限模型是解耦的。你开了 Features::teams()，并不代表 API token 会自动绑定到当前团队。你需要在 App\Models\Token 或中间件中自己做 scope 过滤，否则一个 token 可能跨团队读写数据。这才是关键所在。