> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# 从 laravel/ui 迁移到 Fortify 的指南

> 面向使用 laravel/ui 认证脚手架的既有项目,只把认证后端迁移到 Fortify 的操作步骤。

## 为什么要从 `laravel/ui` 迁移

`laravel/ui` 在 Laravel 13 上仍能运行。`laravel/ui` 的最新版本也确实包含了 Laravel 13 的兼容性。

不过,现在官方的启动套件都是基于 Fortify 的。如果一直保持 `laravel/ui`,你会逐渐偏离官方“当前姿势”。
如果你想保留现有的 Bootstrap + Blade 结构,同时提升未来的可维护性,把认证后端换成 Fortify 是一个有效的做法。

## 迁移的整体思路

这次迁移**只替换认证后端**,UI 不做大规模翻新。

* 用 Fortify 提供认证路由和处理
* 保留现有的 Bootstrap + Blade 模板
* 只在必要处调整表单的 `action` 或输入字段名

<Info>
  Fortify 是 headless 的认证后端。Fortify 本身不提供 UI,因此现有的 Blade 可以照旧使用。
</Info>

## Fortify 的安装步骤

<Steps>
  <Step title="添加 Fortify 包">
    ```bash theme={null}
    composer require laravel/fortify
    ```
  </Step>

  <Step title="发布 Fortify 的资源">
    ```bash theme={null}
    php artisan fortify:install
    ```
  </Step>

  <Step title="执行迁移">
    ```bash theme={null}
    php artisan migrate
    ```
  </Step>

  <Step title="删除 `laravel/ui` 添加的 Auth 路由">
    删除 `routes/web.php` 中的 `Auth::routes();` 或 `Auth::routes([...])`。Fortify 会提供 `/login`、`/register`、`/forgot-password` 等路由,需要避免重复。
  </Step>
</Steps>

## 配置 `FortifyServiceProvider`

在通过 `php artisan fortify:install` 生成的 `app/Providers/FortifyServiceProvider.php` 中把视图挂上。
如果继续复用现有的 `resources/views/auth`,以下这些设置就是迁移的关键。

```php theme={null}
use Laravel\Fortify\Fortify;

public function boot(): void
{
    Fortify::viewPrefix('auth.');
    Fortify::requestPasswordResetLinkView('auth.passwords.email');
    Fortify::resetPasswordView('auth.passwords.reset');
    Fortify::confirmPasswordView('auth.passwords.confirm');
    Fortify::verifyEmailView('auth.verify');
}
```

## Blade 模板的最小改动

迁移后请检查现有 Blade 里的以下几点。

* 表单的 `action` 是否指向 Fortify 的端点(如 `/login`、`/register`、`/forgot-password`)。大部分位置使用的是 `route('login')` 或 `route('register')` 这类命名路由,基本不需要改。但 `route('verification.resend')` 在 Fortify 中是 `route('verification.send')`,这里需要改。

`auth/passwords/reset.blade.php` 需要改两处。

```
<input type="hidden" name="token" value="{{ $token }}">
```

↓

```
<input type="hidden" name="token" value="{{ $request->route('token') }}">
```

```
{{ $email ?? old('email') }}
```

↓

```
{{ old('email', $request->email) }}
```

## 关闭不需要的功能

`laravel/ui` 里没有的功能就用不上,可以在 `config/fortify.php` 里关掉。想启用时准备好新的 view 文件即可。

```php theme={null}
    'features' => [
        Features::registration(),
        Features::resetPasswords(),
        // Features::emailVerification(),
        // Features::updateProfileInformation(),
        // Features::updatePasswords(),
        // Features::twoFactorAuthentication([
        //     'confirm' => true,
        //     'confirmPassword' => true,
            // 'window' => 0,
        // ]),
        // Features::passkeys([
        //     'confirmPassword' => true,
        // ]),
    ],
```

## 上线前的自检清单

迁移完成后,至少要确认以下几项。

<Steps>
  <Step title="确认登录 / 登出">
    用已有用户登录,确认 session 保持正常。
  </Step>

  <Step title="确认注册">
    确认新用户注册能通过,并跳转到预期页面。
  </Step>

  <Step title="确认密码重置">
    从重置邮件发送、带 token 的链接到密码重设完成,把整个流程走一遍。
  </Step>
</Steps>

## 迁移后的收益

完成这次迁移后,你的应用会更贴近现行启动套件中基于 Fortify 的做法。
将来要启用 2FA 或 passkey 会更加轻松。

<Card title="Laravel Fortify 与启动套件" icon="shield-check" href="/zh/advanced/fortify">
  如果你想进一步了解 Fortify 的内部设计、开启 2FA 或 passkey,请查看这一页。
</Card>

## 参考链接

* [Laravel Fortify 仓库](https://github.com/laravel/fortify)
* [Laravel 13.x Fortify 文档](https://github.com/laravel/docs/blob/13.x/fortify.md)
* [React Starter Kit 的 FortifyServiceProvider](https://github.com/laravel/react-starter-kit/blob/main/app/Providers/FortifyServiceProvider.php)


## Related topics

- [旧结构到新结构的迁移指南](/zh/advanced/app-structure-migration.md)
- [Laravel 8 升级到 9](/zh/blog/upgrade-8-to-9.md)
- [Laravel 9 升级到 10](/zh/blog/upgrade-9-to-10.md)
- [Laravel 11 之后新应用结构 FAQ](/zh/advanced/app-structure-faq.md)
- [Laravel 12 升级到 13 指南](/zh/blog/upgrade-12-to-13.md)