> ## 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 的方法。

## 什么是启动套件

启动套件是 Laravel 官方为应用起点准备的脚手架。
它能一次性搭建登录、注册、密码重置、邮箱验证等认证功能以及对应的 UI。

在使用 `laravel new` 创建应用时选择启动套件，就会自动生成认证相关的路由、控制器、视图与前端代码。
生成的所有代码都存在于你自己的应用中，可以自由定制。

<Warning>
  Laravel 13 已废弃传统的 **Breeze** 与 **Jetstream**。
  新项目请使用下方介绍的启动套件。
  现有的使用 Breeze / Jetstream 的项目仍能继续运行，但新开发不再推荐。
</Warning>

## 可用的启动套件

Laravel 13 提供了以下 4 种启动套件。

<CardGroup cols={2}>
  <Card title="React" icon="react">
    使用 React 19、TypeScript、Tailwind 4、[shadcn/ui](https://ui.shadcn.com) 的现代化 SPA。
    通过 [Inertia.js](https://inertiajs.com) 可以在保持服务端路由的同时使用 React。
  </Card>

  <Card title="Vue" icon="vuejs">
    采用 Vue 3 Composition API、TypeScript、Tailwind 与 [shadcn-vue](https://www.shadcn-vue.com/)。
    与 React 相同，也通过 Inertia.js 与服务端连接。
  </Card>

  <Card title="Livewire" icon="bolt">
    使用 [Livewire](https://livewire.laravel.com)，只用 PHP 就可以构建动态 UI。
    最适合以 Blade 模板为主的团队，或希望不使用 JavaScript 框架的场景。使用 [Flux UI](https://fluxui.dev)。
  </Card>

  <Card title="Svelte" icon="s">
    基于 Svelte 5、TypeScript、Tailwind 与 [shadcn-svelte](https://www.shadcn-svelte.com/) 的 SPA。
    结合 Inertia.js 可构建现代化前端。
  </Card>
</CardGroup>

### 应该选哪一个

| 启动套件     | 适合的团队                       |
| -------- | --------------------------- |
| React    | 熟悉 React 生态与 TypeScript 的团队 |
| Vue      | 有 Vue 或 Nuxt 经验的团队          |
| Livewire | 以 PHP 与 Blade 为中心开发的团队      |
| Svelte   | 有 Svelte / SvelteKit 经验的团队  |

<Tip>
  无论选择哪一个，认证功能都完全相同。请选择团队最熟悉的前端技术。
</Tip>

<Info>
  想全面了解 Blade、Livewire、Inertia、独立 SPA 的差异，可以先阅读[前端](/zh/frontend)。
</Info>

## 安装方法

启动套件在创建项目时选择。执行 `laravel new` 时会有交互式提示。

<Steps>
  <Step title="安装 Laravel 安装器">
    如果尚未安装，通过 Composer 获取 Laravel 安装器。

    ```bash theme={null}
    composer global require laravel/installer
    ```
  </Step>

  <Step title="创建新应用">
    执行 `laravel new` 命令。会出现包含启动套件选择的交互式提示。

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

    在提示中选择 **React**、**Vue**、**Livewire**、**Svelte** 中的一种。
    还可选择使用标准 Laravel 认证或 WorkOS AuthKit。
  </Step>

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

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

    ```bash theme={null}
    php artisan migrate
    ```
  </Step>

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

    访问 `http://localhost:8000`，导航栏会显示「Register」「Log in」链接。
  </Step>
</Steps>

启动套件安装后可立即使用以下认证功能：

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

## 定制启动套件

生成的代码都在你自己的应用中，可以自由修改。
前端代码大多位于 `resources/js`（Livewire 由于是 Blade，位于 `resources/views`）。

### 切换布局

每个启动套件都提供了「侧边栏」和「顶部栏」两种布局。默认使用侧边栏布局。

<Tabs>
  <Tab title="React">
    编辑 `resources/js/layouts/app-layout.tsx`。

    ```tsx theme={null}
    // 侧边栏布局（默认）
    import AppLayoutTemplate from '@/layouts/app/app-sidebar-layout';

    // 切换到顶部栏布局
    import AppLayoutTemplate from '@/layouts/app/app-header-layout';
    ```
  </Tab>

  <Tab title="Vue">
    编辑 `resources/js/layouts/AppLayout.vue`。

    ```js theme={null}
    // 侧边栏布局（默认）
    import AppLayout from '@/layouts/app/AppSidebarLayout.vue';

    // 切换到顶部栏布局
    import AppLayout from '@/layouts/app/AppHeaderLayout.vue';
    ```
  </Tab>

  <Tab title="Livewire">
    编辑 `resources/views/layouts/app.blade.php`。

    ```blade theme={null}
    {{-- 切换到顶部栏布局 --}}
    <x-layouts::app.header>
        <flux:main container>
            {{ $slot }}
        </flux:main>
    </x-layouts::app.header>
    ```
  </Tab>

  <Tab title="Svelte">
    编辑 `resources/js/layouts/AppLayout.svelte`。

    ```js theme={null}
    // 侧边栏布局（默认）
    import AppLayout from '@/layouts/app/AppSidebarLayout.svelte';

    // 切换到顶部栏布局
    import AppLayout from '@/layouts/app/AppHeaderLayout.svelte';
    ```
  </Tab>
</Tabs>

### 修改认证页面布局

登录、注册页也可以从「simple」「card」「split」三种布局中选择。

<Tabs>
  <Tab title="React">
    编辑 `resources/js/layouts/auth-layout.tsx`。

    ```tsx theme={null}
    // 简约布局（默认）
    import AuthLayoutTemplate from '@/layouts/auth/auth-simple-layout';

    // 切换到分栏布局
    import AuthLayoutTemplate from '@/layouts/auth/auth-split-layout';
    ```
  </Tab>

  <Tab title="Vue">
    编辑 `resources/js/layouts/AuthLayout.vue`。

    ```js theme={null}
    import AuthLayout from '@/layouts/auth/AuthSimpleLayout.vue';

    // 切换到分栏布局
    import AuthLayout from '@/layouts/auth/AuthSplitLayout.vue';
    ```
  </Tab>

  <Tab title="Livewire">
    编辑 `resources/views/layouts/auth.blade.php`。

    ```blade theme={null}
    <x-layouts::auth.split>
        {{ $slot }}
    </x-layouts::auth.split>
    ```
  </Tab>

  <Tab title="Svelte">
    编辑 `resources/js/layouts/AuthLayout.svelte`。

    ```js theme={null}
    import AuthLayout from '@/layouts/auth/AuthSimpleLayout.svelte';

    // 切换到分栏布局
    import AuthLayout from '@/layouts/auth/AuthSplitLayout.svelte';
    ```
  </Tab>
</Tabs>

### 定制注册逻辑

启动套件使用 `app/Actions/Fortify` 目录下的 Action 类处理用户注册与密码重置等。
例如要在注册时添加手机号字段，请编辑 `CreateNewUser.php`。

```php theme={null}
public function create(array $input): User
{
    Validator::make($input, [
        'name' => ['required', 'string', 'max:255'],
        'email' => ['required', 'email', 'max:255', 'unique:users'],
        'phone' => ['required', 'string', 'max:20'],
        'password' => $this->passwordRules(),
    ])->validate();

    return User::create([
        'name' => $input['name'],
        'email' => $input['email'],
        'phone' => $input['phone'],
        'password' => Hash::make($input['password']),
    ]);
}
```

## WorkOS AuthKit 认证

在执行 `laravel new` 时也可以选择 **WorkOS AuthKit** 作为认证提供方。
使用 WorkOS AuthKit 会新增以下功能：

* 社交登录（Google、Microsoft、GitHub、Apple）
* Passkey 认证
* 邮件 Magic Auth
* SSO（单点登录）

<Info>
  使用 WorkOS AuthKit 需要 WorkOS 账户。月活跃用户 100 万以内免费。
</Info>

若选择 WorkOS，在 `.env` 中设置以下环境变量：

```ini theme={null}
WORKOS_CLIENT_ID=your-client-id
WORKOS_API_KEY=your-api-key
WORKOS_REDIRECT_URL="${APP_URL}/authenticate"
```

## 注意事项

<Warning>
  启动套件在**创建项目时**选择。
  无法后加到已有项目中。
  若已有项目需要认证 UI，请新建项目时选择启动套件，或手动实现认证功能。
</Warning>

## 下一步

<Card title="认证入门" icon="lock" href="/zh/authentication">
  进一步了解 `Auth` 门面用法、路由保护等 Laravel 认证功能。
</Card>


## Related topics

- [Laravel Maestro — 启动套件开发的编排器](/zh/blog/maestro-introduction.md)
- [Laravel Chisel — 启动套件的安装后脚本库](/zh/blog/chisel-introduction.md)
- [Laravel 11 升级到 12 指南](/zh/blog/upgrade-11-to-12.md)
- [安装](/zh/installation.md)
- [认证入门](/zh/authentication.md)