> ## 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 认证功能的基础知识。从使用启动套件搭建认证系统到获取已登录用户的方法都会讲到。

## 什么是认证

认证（Authentication）指的是确认访问用户「是谁」的机制。
在 Web 应用中，通常是通过登录表单接收邮箱和密码，若匹配成功就把用户信息保存到 Session 中。
之后的请求就通过该 Session 识别用户。

Laravel 的认证功能由「守卫（Guard）」和「Provider（用户提供者）」两个概念组成。

* **守卫**：定义在每个请求中如何认证用户。默认使用 `session` 守卫，通过 Session 与 Cookie 管理状态。
* **Provider**：定义如何从数据源中取出用户。默认使用 Eloquent。

<Info>
  认证的配置文件是 `config/auth.php`。默认设置就足以覆盖大多数 Web 应用。
</Info>

```mermaid theme={null}
flowchart TD
    A["登录请求"] --> B["守卫<br>(定义认证方式)"]
    B --> C["Provider<br>(从数据库获取用户)"]
    C --> D{"校验认证"}
    D -- "成功" --> E["将用户信息<br>保存到 Session"]
    E --> F["跳转到已认证页"]
    D -- "失败" --> G["跳转到登录页"]
```

## 通过启动套件搭建认证

在 Laravel 中，只需在通过 `laravel new` 创建应用时选择启动套件，就会自动构建登录、注册、密码重置等认证功能。这是最推荐的方式。

<Steps>
  <Step title="创建应用">
    使用 Laravel 安装器创建应用，过程中会有选择启动套件的提示。

    ```shell theme={null}
    laravel new my-app
    ```

    启动套件可以从 **React**、**Vue**、**Livewire**、**Svelte** 中选择。
    请结合团队的技术栈来选。
  </Step>

  <Step title="安装前端依赖">
    ```shell theme={null}
    cd my-app
    npm install && npm run build
    ```
  </Step>

  <Step title="准备数据库">
    确认 `.env` 中的数据库配置后运行迁移。

    ```shell theme={null}
    php artisan migrate
    ```

    包含 `users` 表的初始迁移会被应用。
  </Step>

  <Step title="启动开发服务器">
    ```shell theme={null}
    composer run dev
    ```

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

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

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

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

### 可用的启动套件

#### React

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

#### Vue

采用 Vue Composition API、TypeScript、Tailwind 与 [shadcn-vue](https://www.shadcn-vue.com/)。
同样使用 Inertia 与服务端连接。

#### Livewire

使用 [Livewire](https://livewire.laravel.com)，只需 PHP 就能构建动态 UI。
适合以 Blade 模板为主的团队，或希望不使用 JavaScript 框架的场景。
内置 [Flux UI](https://fluxui.dev) 组件库。

#### Svelte

采用 Svelte 5、TypeScript、Tailwind 与 [shadcn-svelte](https://www.shadcn-svelte.com/)。
结合 Inertia 可构建现代化 SPA。

## 认证门面

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

### 获取已认证用户

```php theme={null}
use Illuminate\Support\Facades\Auth;

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

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

在控制器中也可以从 `Request` 对象获取用户。

```php theme={null}
<?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` 返回用户是否已登录。

```php theme={null}
use Illuminate\Support\Facades\Auth;

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

在 Blade 模板中，使用 `@auth` 与 `@guest` 指令会更方便。

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

@guest
    <a href="/login">登录</a>
    <a href="/register">注册</a>
@endguest
```

## 路由保护

要创建只允许已登录用户访问的路由，请使用 `auth` 中间件。

```php theme={null}
// routes/web.php

// 仅已认证用户可访问
Route::get('/dashboard', function () {
    return view('dashboard');
})->middleware('auth');
```

未认证用户访问时会自动被重定向到 `/login`。

要一次性保护多个路由，可使用分组。

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

<Warning>
  忘加 `auth` 中间件会让未登录用户也能访问。需要保护的路由请务必加上。
</Warning>

### 仅访客路由

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

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

## 手动认证

不使用启动套件、手动实现登录时可使用 `Auth::attempt()`。

```php theme={null}
<?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` 作为第二个参数传入。

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

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

## 登出

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

```php theme={null}
<?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 方法。

```php theme={null}
Route::post('/logout', [LogoutController::class, 'logout'])->middleware('auth');
```

Blade 模板中通过表单发送 POST 请求。

```blade theme={null}
<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()`                    |

## 下一步

<Card title="中间件" icon="shield-halved" href="/zh/middleware">
  详细了解 `auth` 中间件的机制及如何编写自定义中间件。
</Card>


## Related topics

- [启动套件](/zh/starter-kits.md)
- [哈希（Hashing）](/zh/hashing.md)
- [密码重置](/zh/passwords.md)
- [测试入门](/zh/testing.md)
- [实现自定义认证 Guard](/zh/advanced/custom-auth-guard.md)