> ## 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 認證 scaffold 的既有專案，說明僅將認證後端遷移到 Fortify 的步驟。

## 為什麼要從 `laravel/ui` 遷移

`laravel/ui` 在 Laravel 13 仍可運作。實際上 `laravel/ui` 最新版本就包含 Laravel 13 compatibility。

不過現行的官方 starter kit 是以 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` 中綁定 view。\
如果要直接使用既有的 `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 的 endpoint（例如：`/login`、`/register`、`/forgot-password`）。大多是用 `route('login')` 或 `route('register')` 這類 route name 指定，因此需要修正的地方應該不多。只有 `route(verification.resend')` 在 Fortify 是 `route('verification.send')`，需要修正。

`auth/passwords/reset.balde.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>

## 遷移後的優點

進行此遷移後，你的應用會更接近現行 starter kit 的 Fortify 基礎。\
其結果是未來將更容易啟用 2FA 或 Passkeys。

<Card title="Laravel Fortify 與 Starter Kit" icon="shield-check" href="/zh-TW/advanced/fortify">
  想深入了解 Fortify 的內部設計、啟用 2FA、Passkeys，請參考這頁。
</Card>

## 參考連結

* [Laravel Fortify Repository](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

- [從 Laravel 8 升級到 9](/zh-TW/blog/upgrade-8-to-9.md)
- [從 Laravel 9 升級到 10](/zh-TW/blog/upgrade-9-to-10.md)
- [從 Laravel 11 升級到 12 指南](/zh-TW/blog/upgrade-11-to-12.md)
- [從舊結構到新結構的遷移指南](/zh-TW/advanced/app-structure-migration.md)
- [從 Laravel 10 升級到 11](/zh-TW/blog/upgrade-10-to-11.md)