认证入门

什么是认证

认证（Authentication）指的是确认访问用户「是谁」的机制。在 Web 应用中，通常是通过登录表单接收邮箱和密码，若匹配成功就把用户信息保存到 Session 中。之后的请求就通过该 Session 识别用户。 Laravel 的认证功能由「守卫（Guard）」和「Provider（用户提供者）」两个概念组成。

守卫：定义在每个请求中如何认证用户。默认使用 session 守卫，通过 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 中的数据库配置后运行迁移。

php artisan migrate

包含 users 表的初始迁移会被应用。

启动开发服务器

composer run dev

在浏览器中访问 http://localhost:8000，导航栏会显示「Register」与「Log in」链接。可以访问 /register 试着注册用户。

使用启动套件后，你立即拥有以下功能：

功能	URL
用户注册	`/register`
登录	`/login`
密码重置	`/forgot-password`
邮箱验证	`/email/verify`
个人资料编辑	`/settings/profile`

启动套件生成的所有代码（控制器、路由、视图）都存在于你自己的应用中，可以自由地修改和定制。

可用的启动套件

React

采用 React 19、TypeScript、Tailwind 及 shadcn/ui，可构建现代化 SPA。通过 Inertia，可以在保留服务端路由的同时使用 React 前端。

Vue

采用 Vue Composition API、TypeScript、Tailwind 与 shadcn-vue。同样使用 Inertia 与服务端连接。

Livewire

使用 Livewire，只需 PHP 就能构建动态 UI。适合以 Blade 模板为主的团队，或希望不使用 JavaScript 框架的场景。内置 Flux UI 组件库。

Svelte

采用 Svelte 5、TypeScript、Tailwind 与 shadcn-svelte。结合 Inertia 可构建现代化 SPA。

认证门面

使用 Auth 门面可以获取当前已认证用户的信息或判断认证状态。

获取已认证用户

use Illuminate\Support\Facades\Auth;

// 获取当前用户
$user = Auth::user();

// 只获取用户 ID
$id = Auth::id();

在控制器中也可以从 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 中间件。

// 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 中间件会让未登录用户也能访问。需要保护的路由请务必加上。

仅访客路由

要将已登录用户重定向到别处，可使用 guest 中间件。对登录和注册页面使用它，可以把已登录用户直接跳转到仪表盘。

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() 的第一个参数是凭据数组。密码会自动与哈希比对，因此直接传入明文即可。要实现「记住登录状态」功能，把 true 作为第二个参数传入。

// 使用「记住我」复选框的值
Auth::attempt($credentials, $request->boolean('remember'));

即使自己实现认证，也建议参考启动套件的代码——它是安全实现的好范本。

登出

要登出用户，请调用 Auth::logout()。最佳实践是同时使 Session 失效并重新生成 CSRF 令牌。

<?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 令牌
        $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()`

下一步

中间件

详细了解 auth 中间件的机制及如何编写自定义中间件。

入门

基础

请求处理

数据库

认证

辅助函数与外部通信

测试与部署

AI 开发辅助

什么是认证

通过启动套件搭建认证

可用的启动套件

React

Vue

Livewire

Svelte

认证门面

获取已认证用户

判断认证状态

路由保护

仅访客路由

手动认证

登出

小结

下一步

中间件

​什么是认证

​通过启动套件搭建认证

​可用的启动套件

​React

​Vue

​Livewire

​Svelte

​认证门面

​获取已认证用户

​判断认证状态

​路由保护

​仅访客路由

​手动认证

​登出

​小结

​下一步

中间件

什么是认证

通过启动套件搭建认证

可用的启动套件

React

Vue

Livewire

Svelte

认证门面

获取已认证用户

判断认证状态

路由保护

仅访客路由

手动认证

登出

小结

下一步