認證入門

什麼是認證

認證（Authentication）是確認發起存取的使用者「是誰」的機制。在 Web 應用程式中，會透過登入表單接收電子郵件與密碼，若正確則將使用者資訊儲存到 Session。後續請求會參照該 Session 來識別使用者。 Laravel 的認證功能由「Guard」與「Provider」兩個概念組成。

Guard：定義每個請求如何驗證使用者。預設是 session guard，使用 Session 與 Cookie 來管理狀態。
Provider：定義如何從資料庫取得使用者。預設使用 Eloquent。

認證的設定檔為 config/auth.php。預設設定即可對應大多數 Web 應用程式。

透過啟動套件加入認證

在 Laravel 中，只要在使用 laravel new 建立應用程式時選擇啟動套件，就能自動建構登入、註冊、密碼重設等認證功能。這是最推薦的方式。

建立應用程式

使用 Laravel 安裝器建立應用程式。過程中會出現選擇啟動套件的提示。

laravel new my-app

啟動套件可從 React、Vue、Livewire、Svelte 中選擇。請依團隊的技術堆疊挑選。

安裝前端相依套件

cd my-app
npm install && npm run build

準備資料庫

確認 .env 檔案的資料庫設定後，執行 migration。

php artisan migrate

會套用包含 users 表的初始 migration。

啟動開發伺服器

composer run dev

在瀏覽器開啟 http://localhost:8000，導覽列會顯示「Register」與「Log in」連結。可以造訪 /register 註冊使用者試試看。

使用啟動套件後，以下功能可立即使用：

功能	URL
使用者註冊	`/register`
登入	`/login`
密碼重設	`/forgot-password`
電子郵件驗證	`/email/verify`
個人資料編輯	`/settings/profile`

啟動套件產生的程式碼（Controller、Route、View）全部都存在於你自己的應用程式內，可以自由修改與客製化。

可用的啟動套件

React

可建構使用 React 19、TypeScript、Tailwind、shadcn/ui 的現代 SPA。透過 Inertia，能在保有伺服器端路由的同時使用 React 前端。

Vue

採用 Vue Composition API、TypeScript、Tailwind、shadcn-vue。與 React 同樣使用 Inertia 與伺服器端連動。

Livewire

使用僅靠 PHP 即可建構動態 UI 的 Livewire。最適合以 Blade 模板為主的團隊，或希望不使用 JavaScript 框架的場合。內含 Flux UI 元件庫。

Svelte

使用 Svelte 5、TypeScript、Tailwind、shadcn-svelte。可與 Inertia 搭配建構現代 SPA。

認證 Facade

使用 Auth Facade 可取得目前已認證的使用者資訊，或確認認證狀態。

取得已認證的使用者

use Illuminate\Support\Facades\Auth;

// 取得目前的使用者
$user = Auth::user();

// 只取得使用者 ID
$id = Auth::id();

在 Controller 中也可以從 Request 物件取得使用者。

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;

class DashboardController extends Controller
{
    public function index(Request $request)
    {
        $user = $request->user();

        return view('dashboard', ['user' => $user]);
    }
}

確認認證狀態

Auth::check() 會以 true / false 回傳使用者是否已登入。

use Illuminate\Support\Facades\Auth;

if (Auth::check()) {
    // 已登入
} else {
    // 未登入
}

在 Blade 模板中使用 @auth 與 @guest 指令會很方便。

@auth
    <p>您好，{{ Auth::user()->name }}</p>
    <a href="/logout">登出</a>
@endauth

@guest
    <a href="/login">登入</a>
    <a href="/register">註冊</a>
@endguest

保護路由

要建立只有已登入使用者能存取的路由，可以使用 auth middleware。

// routes/web.php

// 只有已認證使用者可存取
Route::get('/dashboard', function () {
    return view('dashboard');
})->middleware('auth');

未認證的使用者嘗試存取時，會自動被導向 /login。若要一次保護多條路由，可使用群組。

Route::middleware('auth')->group(function () {
    Route::get('/dashboard', [DashboardController::class, 'index']);
    Route::get('/profile', [ProfileController::class, 'show']);
    Route::get('/settings', [SettingsController::class, 'index']);
});

若忘記加上 auth middleware，未登入的使用者就會能夠存取。需要保護的路由請務必套用。

訪客專用路由

要將已登入的使用者重新導向，可使用 guest middleware。將其套用在登入或註冊頁面，即可把已登入的使用者轉送至儀表板。

Route::middleware('guest')->group(function () {
    Route::get('/login', [AuthController::class, 'showLogin']);
    Route::get('/register', [AuthController::class, 'showRegister']);
});

手動認證

若不使用啟動套件而想手動實作登入處理，可使用 Auth::attempt()。

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Illuminate\Http\RedirectResponse;
use Illuminate\Support\Facades\Auth;

class LoginController extends Controller
{
    public function login(Request $request): RedirectResponse
    {
        $credentials = $request->validate([
            'email' => ['required', 'email'],
            'password' => ['required'],
        ]);

        if (Auth::attempt($credentials)) {
            // 認證成功 — 重新產生 Session 以防止 CSRF 攻擊
            $request->session()->regenerate();

            return redirect()->intended('/dashboard');
        }

        // 認證失敗
        return back()->withErrors([
            'email' => '電子郵件或密碼不正確。',
        ])->onlyInput('email');
    }
}

在 Auth::attempt() 的第 1 個參數傳入認證資訊陣列。密碼會自動與雜湊值比對，因此請直接傳入明文。若要實作「保持登入狀態」功能，於第 2 個參數傳入 true。

// 使用「保持登入狀態」核取方塊的值
Auth::attempt($credentials, $request->boolean('remember'));

即使自行實作手動認證，也建議參考啟動套件的程式碼。可將其當作安全實作的範本。

登出

要讓使用者登出，呼叫 Auth::logout()。最佳做法是同時使 Session 失效並重新產生 CSRF Token。

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Illuminate\Http\RedirectResponse;
use Illuminate\Support\Facades\Auth;

class LogoutController extends Controller
{
    public function logout(Request $request): RedirectResponse
    {
        Auth::logout();

        // 使 Session 失效
        $request->session()->invalidate();

        // 重新產生 CSRF Token
        $request->session()->regenerateToken();

        return redirect('/');
    }
}

路由請使用 POST 方法。

Route::post('/logout', [LogoutController::class, 'logout'])->middleware('auth');

在 Blade 模板中使用表單送出 POST 請求。

<form method="POST" action="/logout">
    @csrf
    <button type="submit">登出</button>
</form>

總結

想要做的事	方法
快速加入認證功能	啟動套件（`laravel new`）
取得目前的使用者	`Auth::user()` / `$request->user()`
確認登入狀態	`Auth::check()`
保護路由	`->middleware('auth')`
手動登入	`Auth::attempt($credentials)`
登出	`Auth::logout()`

下一步

Middleware

詳細了解 auth middleware 的機制與自訂 middleware 的建立方式。

開始使用

基礎

請求處理

資料庫

認證

輔助工具與外部通訊

測試與部署

AI 開發輔助

什麼是認證

透過啟動套件加入認證

可用的啟動套件

React

Vue

Livewire

Svelte

認證 Facade

取得已認證的使用者

確認認證狀態

保護路由

訪客專用路由

手動認證

登出

總結

下一步

Middleware

​什麼是認證

​透過啟動套件加入認證

​可用的啟動套件

​React

​Vue

​Livewire

​Svelte

​認證 Facade

​取得已認證的使用者

​確認認證狀態

​保護路由

​訪客專用路由

​手動認證

​登出

​總結

​下一步

Middleware

什麼是認證

透過啟動套件加入認證

可用的啟動套件

React

Vue

Livewire

Svelte

認證 Facade

取得已認證的使用者

確認認證狀態

保護路由

訪客專用路由

手動認證

登出

總結

下一步