入门套件

简介

为了帮助你快速开始构建新的 Laravel 应用程序，我们很高兴提供应用程序入门套件。这些入门套件为你构建下一个 Laravel 应用程序提供了一个良好的起点，包含注册和认证应用程序用户所需的路由、控制器和视图。入门套件使用 Laravel Fortify 提供认证功能。

虽然欢迎你使用这些入门套件，但它们并非必需。你完全可以通过安装一个全新的 Laravel 副本从零开始构建自己的应用程序。无论哪种方式，我们相信你都会构建出优秀的产品！

使用入门套件创建应用程序

要使用我们的入门套件创建新的 Laravel 应用程序，你应该首先安装 PHP 和 Laravel CLI 工具。如果你已经安装了 PHP 和 Composer，可以通过 Composer 安装 Laravel 安装器 CLI 工具：

shell

composer global require laravel/installer

然后，使用 Laravel 安装器 CLI 创建一个新的 Laravel 应用程序。Laravel 安装器会提示你选择首选的入门套件：

shell

laravel new my-app

创建 Laravel 应用程序后，你只需通过 NPM 安装其前端依赖并启动 Laravel 开发服务器：

shell

cd my-app
npm install && npm run build
composer run dev

启动 Laravel 开发服务器后，你的应用程序将在浏览器中通过 http://localhost:8000 访问。

可用的入门套件

React

我们的 React 入门套件为使用 Inertia 构建带有 React 前端的 Laravel 应用程序提供了一个强大的、现代化的起点。

Inertia 允许你使用经典的服务端路由和控制器构建现代的单页 React 应用程序。这让你可以享受 React 的前端能力，同时结合 Laravel 令人难以置信的后端生产力和 Vite 的极速编译。

React 入门套件使用了 React 19、TypeScript、Tailwind 和 shadcn/ui 组件库。

Svelte

我们的 Svelte 入门套件为使用 Inertia 构建带有 Svelte 前端的 Laravel 应用程序提供了一个强大的、现代化的起点。

Inertia 允许你使用经典的服务端路由和控制器构建现代的单页 Svelte 应用程序。这让你可以享受 Svelte 的前端能力，同时结合 Laravel 令人难以置信的后端生产力和 Vite 的极速编译。

Svelte 入门套件使用了 Svelte 5、TypeScript、Tailwind 和 shadcn-svelte 组件库。

Vue

我们的 Vue 入门套件为使用 Inertia 构建带有 Vue 前端的 Laravel 应用程序提供了一个很好的起点。

Inertia 允许你使用经典的服务端路由和控制器构建现代的单页 Vue 应用程序。这让你可以享受 Vue 的前端能力，同时结合 Laravel 令人难以置信的后端生产力和 Vite 的极速编译。

Vue 入门套件使用了 Vue Composition API、TypeScript、Tailwind 和 shadcn-vue 组件库。

Livewire

我们的 Livewire 入门套件为使用 Laravel Livewire 前端构建 Laravel 应用程序提供了完美的起点。

Livewire 是一种仅使用 PHP 构建动态、响应式前端 UI 的强大方式。它非常适合主要使用 Blade 模板并正在寻找 JavaScript 驱动的 SPA 框架（如 React、Svelte 和 Vue）的更简单替代方案的团队。

Livewire 入门套件使用了 Livewire、Tailwind 和 Flux UI 组件库。

入门套件自定义

React

我们的 React 入门套件使用 Inertia 2、React 19、Tailwind 4 和 shadcn/ui 构建。与所有入门套件一样，所有后端和前端代码都存在于你的应用程序中，允许你进行完全自定义。

大部分前端代码位于 resources/js 目录中。你可以自由修改任何代码来自定义应用程序的外观和行为：

text

resources/js/
├── components/    # 可复用的 React 组件
├── hooks/         # React hooks
├── layouts/       # 应用程序布局
├── lib/           # 工具函数和配置
├── pages/         # 页面组件
└── types/         # TypeScript 类型定义

要发布额外的 shadcn 组件，首先找到你想要发布的组件。然后，使用 npx 发布组件：

shell

npx shadcn@latest add switch

在这个例子中，该命令会将 Switch 组件发布到 resources/js/components/ui/switch.tsx。组件发布后，你可以在任何页面中使用它：

jsx

import { Switch } from "@/components/ui/switch"

const MyPage = () => {
  return (
    <div>
      <Switch />
    </div>
  );
};

export default MyPage;

可用布局

React 入门套件包含两种不同的主要布局供你选择："sidebar"（侧边栏）布局和 "header"（顶部导航）布局。侧边栏布局是默认布局，但你可以通过修改应用程序 resources/js/layouts/app-layout.tsx 文件顶部导入的布局来切换到顶部导航布局：

import AppLayoutTemplate from '@/layouts/app/app-sidebar-layout'; // [tl! remove]
import AppLayoutTemplate from '@/layouts/app/app-header-layout'; // [tl! add]

侧边栏布局包含三种不同的变体：默认侧边栏变体、"inset"（嵌入式）变体和 "floating"（浮动式）变体。你可以通过修改 resources/js/components/app-sidebar.tsx 组件来选择你最喜欢的变体：

text

<Sidebar collapsible="icon" variant="sidebar"> [tl! remove]
<Sidebar collapsible="icon" variant="inset"> [tl! add]

认证页面布局变体

React 入门套件附带的认证页面（如登录页面和注册页面）也提供三种不同的布局变体："simple"（简洁）、"card"（卡片）和 "split"（分割）。

要更改认证布局，请修改应用程序 resources/js/layouts/auth-layout.tsx 文件顶部导入的布局：

import AuthLayoutTemplate from '@/layouts/auth/auth-simple-layout'; // [tl! remove]
import AuthLayoutTemplate from '@/layouts/auth/auth-split-layout'; // [tl! add]

Svelte

我们的 Svelte 入门套件使用 Inertia 2、Svelte 5、Tailwind 和 shadcn-svelte 构建。与所有入门套件一样，所有后端和前端代码都存在于你的应用程序中，允许你进行完全自定义。

大部分前端代码位于 resources/js 目录中。你可以自由修改任何代码来自定义应用程序的外观和行为：

text

resources/js/
├── components/    # 可复用的 Svelte 组件
├── layouts/       # 应用程序布局
├── lib/           # 工具函数、配置和 Svelte rune 模块
├── pages/         # 页面组件
└── types/         # TypeScript 类型定义

要发布额外的 shadcn-svelte 组件，首先找到你想要发布的组件。然后，使用 npx 发布组件：

shell

npx shadcn-svelte@latest add switch

在这个例子中，该命令会将 Switch 组件发布到 resources/js/components/ui/switch/switch.svelte。组件发布后，你可以在任何页面中使用它：

svelte

<script lang="ts">
    import { Switch } from '@/components/ui/switch'
</script>

<div>
    <Switch />
</div>

可用布局

Svelte 入门套件包含两种不同的主要布局供你选择："sidebar"（侧边栏）布局和 "header"（顶部导航）布局。侧边栏布局是默认布局，但你可以通过修改应用程序 resources/js/layouts/AppLayout.svelte 文件顶部导入的布局来切换到顶部导航布局：

import AppLayout from '@/layouts/app/AppSidebarLayout.svelte'; // [tl! remove]
import AppLayout from '@/layouts/app/AppHeaderLayout.svelte'; // [tl! add]

侧边栏布局包含三种不同的变体：默认侧边栏变体、"inset"（嵌入式）变体和 "floating"（浮动式）变体。你可以通过修改 resources/js/components/AppSidebar.svelte 组件来选择你最喜欢的变体：

text

<Sidebar collapsible="icon" variant="sidebar"> [tl! remove]
<Sidebar collapsible="icon" variant="inset"> [tl! add]

认证页面布局变体

Svelte 入门套件附带的认证页面（如登录页面和注册页面）也提供三种不同的布局变体："simple"（简洁）、"card"（卡片）和 "split"（分割）。

要更改认证布局，请修改应用程序 resources/js/layouts/AuthLayout.svelte 文件顶部导入的布局：

import AuthLayout from '@/layouts/auth/AuthSimpleLayout.svelte'; // [tl! remove]
import AuthLayout from '@/layouts/auth/AuthSplitLayout.svelte'; // [tl! add]

Vue

我们的 Vue 入门套件使用 Inertia 2、Vue 3 Composition API、Tailwind 和 shadcn-vue 构建。与所有入门套件一样，所有后端和前端代码都存在于你的应用程序中，允许你进行完全自定义。

大部分前端代码位于 resources/js 目录中。你可以自由修改任何代码来自定义应用程序的外观和行为：

text

resources/js/
├── components/    # 可复用的 Vue 组件
├── composables/   # Vue composables / hooks
├── layouts/       # 应用程序布局
├── lib/           # 工具函数和配置
├── pages/         # 页面组件
└── types/         # TypeScript 类型定义

要发布额外的 shadcn-vue 组件，首先找到你想要发布的组件。然后，使用 npx 发布组件：

shell

npx shadcn-vue@latest add switch

在这个例子中，该命令会将 Switch 组件发布到 resources/js/components/ui/Switch.vue。组件发布后，你可以在任何页面中使用它：

vue

<script setup lang="ts">
import { Switch } from '@/components/ui/switch'
</script>

<template>
    <div>
        <Switch />
    </div>
</template>

可用布局

Vue 入门套件包含两种不同的主要布局供你选择："sidebar"（侧边栏）布局和 "header"（顶部导航）布局。侧边栏布局是默认布局，但你可以通过修改应用程序 resources/js/layouts/AppLayout.vue 文件顶部导入的布局来切换到顶部导航布局：

import AppLayout from '@/layouts/app/AppSidebarLayout.vue'; // [tl! remove]
import AppLayout from '@/layouts/app/AppHeaderLayout.vue'; // [tl! add]

侧边栏布局包含三种不同的变体：默认侧边栏变体、"inset"（嵌入式）变体和 "floating"（浮动式）变体。你可以通过修改 resources/js/components/AppSidebar.vue 组件来选择你最喜欢的变体：

text

<Sidebar collapsible="icon" variant="sidebar"> [tl! remove]
<Sidebar collapsible="icon" variant="inset"> [tl! add]

认证页面布局变体

Vue 入门套件附带的认证页面（如登录页面和注册页面）也提供三种不同的布局变体："simple"（简洁）、"card"（卡片）和 "split"（分割）。

要更改认证布局，请修改应用程序 resources/js/layouts/AuthLayout.vue 文件顶部导入的布局：

import AuthLayout from '@/layouts/auth/AuthSimpleLayout.vue'; // [tl! remove]
import AuthLayout from '@/layouts/auth/AuthSplitLayout.vue'; // [tl! add]

Livewire

我们的 Livewire 入门套件使用 Livewire 4、Tailwind 和 Flux UI 构建。与所有入门套件一样，所有后端和前端代码都存在于你的应用程序中，允许你进行完全自定义。

大部分前端代码位于 resources/views 目录中。你可以自由修改任何代码来自定义应用程序的外观和行为：

text

resources/views
├── components            # 可复用组件
├── flux                  # 自定义的 Flux 组件
├── layouts               # 应用程序布局
├── pages                 # Livewire 页面
├── partials              # 可复用的 Blade 片段
├── dashboard.blade.php   # 已认证用户仪表盘
├── welcome.blade.php     # 访客欢迎页面

可用布局

Livewire 入门套件包含两种不同的主要布局供你选择："sidebar"（侧边栏）布局和 "header"（顶部导航）布局。侧边栏布局是默认布局，但你可以通过修改应用程序 resources/views/layouts/app.blade.php 文件使用的布局来切换到顶部导航布局。此外，你应该在主 Flux 组件上添加 container 属性：

blade

<x-layouts::app.header>
    <flux:main container>
        {{ $slot }}
    </flux:main>
</x-layouts::app.header>

认证页面布局变体

Livewire 入门套件附带的认证页面（如登录页面和注册页面）也提供三种不同的布局变体："simple"（简洁）、"card"（卡片）和 "split"（分割）。

要更改认证布局，请修改应用程序 resources/views/layouts/auth.blade.php 文件使用的布局：

blade

<x-layouts::auth.split>
    {{ $slot }}
</x-layouts::auth.split>

认证

所有入门套件都使用 Laravel Fortify 来处理认证。Fortify 提供了登录、注册、密码重置、邮箱验证等功能所需的路由、控制器和逻辑。

Fortify 会根据应用程序 config/fortify.php 配置文件中启用的功能，自动注册以下认证路由：

路由	方法	描述
`/login`	`GET`	显示登录表单
`/login`	`POST`	认证用户
`/logout`	`POST`	注销用户
`/register`	`GET`	显示注册表单
`/register`	`POST`	创建新用户
`/forgot-password`	`GET`	显示密码重置请求表单
`/forgot-password`	`POST`	发送密码重置链接
`/reset-password/{token}`	`GET`	显示密码重置表单
`/reset-password`	`POST`	更新密码
`/email/verify`	`GET`	显示邮箱验证通知
`/email/verify/{id}/{hash}`	`GET`	验证邮箱地址
`/email/verification-notification`	`POST`	重新发送验证邮件
`/user/confirm-password`	`GET`	显示密码确认表单
`/user/confirm-password`	`POST`	确认密码
`/two-factor-challenge`	`GET`	显示双因素认证挑战表单
`/two-factor-challenge`	`POST`	验证双因素认证代码

可以使用 php artisan route:list Artisan 命令来显示应用程序中的所有路由。

启用和禁用功能

你可以在应用程序的 config/fortify.php 配置文件中控制启用哪些 Fortify 功能：

php

use Laravel\Fortify\Features;

'features' => [
    Features::registration(),
    Features::resetPasswords(),
    Features::emailVerification(),
    Features::twoFactorAuthentication([
        'confirm' => true,
        'confirmPassword' => true,
    ]),
],

要禁用某个功能，请注释掉或从 features 数组中移除该功能条目。例如，移除 Features::registration() 可以禁用公开注册。

当使用 React、Svelte 或 Vue 入门套件时，你还需要在前端代码中移除对已禁用功能路由的所有引用。例如，如果你禁用了邮箱验证，则应从 React、Svelte 或 Vue 组件中移除对 verification 路由的导入和引用。这是必要的，因为这些入门套件使用 Wayfinder 进行类型安全路由，它在构建时生成路由定义。如果你引用了不再存在的路由，你的应用程序将无法构建。

自定义用户创建和密码重置

当用户注册或重置密码时，Fortify 会调用位于应用程序 app/Actions/Fortify 目录中的 action 类：

文件	描述
`CreateNewUser.php`	验证并创建新用户
`ResetUserPassword.php`	验证并更新用户密码
`PasswordValidationRules.php`	定义密码验证规则

例如，要自定义应用程序的注册逻辑，你应该编辑 CreateNewUser action：

php

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'], // [tl! add]
        'password' => $this->passwordRules(),
    ])->validate();

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

双因素认证

入门套件内置了双因素认证（2FA），允许用户使用任何兼容 TOTP 的身份验证器应用程序来保护其账户。2FA 默认通过应用程序 config/fortify.php 配置文件中的 Features::twoFactorAuthentication() 启用。

confirm 选项要求用户在 2FA 完全启用之前验证一个代码，而 confirmPassword 选项要求在启用或禁用 2FA 之前确认密码。更多详情，请参阅 Fortify 的双因素认证文档。

频率限制

频率限制可以防止暴力破解和重复登录尝试使你的认证端点不堪重负。你可以在应用程序的 FortifyServiceProvider 中自定义 Fortify 的频率限制行为：

php

use Illuminate\Support\Facades\RateLimiter;
use Illuminate\Cache\RateLimiting\Limit;

RateLimiter::for('login', function ($request) {
    return Limit::perMinute(5)->by($request->email.$request->ip());
});

WorkOS AuthKit 认证

默认情况下，React、Svelte、Vue 和 Livewire 入门套件都使用 Laravel 内置的认证系统来提供登录、注册、密码重置、邮箱验证等功能。此外，我们还为每个入门套件提供了由 WorkOS AuthKit 驱动的变体，提供以下功能：

社交认证（Google、Microsoft、GitHub 和 Apple）
Passkey 认证
基于邮件的 "Magic Auth"
SSO

使用 WorkOS 作为认证提供者需要一个 WorkOS 账户。WorkOS 为月活跃用户不超过 100 万的应用程序提供免费认证。

要使用 WorkOS AuthKit 作为应用程序的认证提供者，请在通过 laravel new 创建基于入门套件的新应用程序时选择 WorkOS 选项。

配置你的 WorkOS 入门套件

使用 WorkOS 驱动的入门套件创建新应用程序后，你应该在应用程序的 .env 文件中设置 WORKOS_CLIENT_ID、WORKOS_API_KEY 和 WORKOS_REDIRECT_URL 环境变量。这些变量应与 WorkOS 仪表盘中为你的应用程序提供的值匹配：

ini

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

此外，你应该在 WorkOS 仪表盘中配置应用程序主页 URL。该 URL 是用户注销应用程序后被重定向的地址。

配置 AuthKit 认证方法

使用 WorkOS 驱动的入门套件时，我们建议你在应用程序的 WorkOS AuthKit 配置设置中禁用 "Email + Password" 认证，仅允许用户通过社交认证提供者、passkeys、"Magic Auth" 和 SSO 进行认证。这样可以让你的应用程序完全避免处理用户密码。

配置 AuthKit 会话超时

此外，我们建议你将 WorkOS AuthKit 的会话不活动超时配置为与 Laravel 应用程序配置的会话超时阈值（通常为两小时）相匹配。

Inertia SSR

React、Svelte 和 Vue 入门套件兼容 Inertia 的服务端渲染功能。要为你的应用程序构建兼容 Inertia SSR 的打包文件，请运行 build:ssr 命令：

shell

npm run build:ssr

为了方便，还提供了 composer dev:ssr 命令。该命令会在构建 SSR 兼容的打包文件后启动 Laravel 开发服务器和 Inertia SSR 服务器，允许你使用 Inertia 的服务端渲染引擎在本地测试应用程序：

shell

composer dev:ssr

社区维护的入门套件

使用 Laravel 安装器创建新的 Laravel 应用程序时，你可以通过 --using 标志提供任何在 Packagist 上可用的社区维护入门套件：

shell

laravel new my-app --using=example/starter-kit

创建入门套件

为了确保你的入门套件可供他人使用，你需要将其发布到 Packagist。你的入门套件应在其 .env.example 文件中定义所需的环境变量，任何必要的安装后命令都应列在入门套件 composer.json 文件的 post-create-project-cmd 数组中。

常见问题

如何升级？

每个入门套件都为你的下一个应用程序提供了坚实的起点。由于你拥有代码的完全所有权，可以按照自己的愿景调整、自定义和构建应用程序。然而，不需要更新入门套件本身。

如何启用邮箱验证？

可以通过取消注释 App/Models/User.php 模型中的 MustVerifyEmail 导入并确保模型实现 MustVerifyEmail 接口来添加邮箱验证：

php

<?php

namespace App\Models;

use Illuminate\Contracts\Auth\MustVerifyEmail;
// ...

class User extends Authenticatable implements MustVerifyEmail
{
    // ...
}

注册后，用户将收到一封验证邮件。要在用户的邮箱地址验证之前限制对某些路由的访问，请将 verified middleware 添加到路由中：

php

Route::middleware(['auth', 'verified'])->group(function () {
    Route::get('dashboard', function () {
        return Inertia::render('dashboard');
    })->name('dashboard');
});

NOTE

使用入门套件的 WorkOS 变体时不需要邮箱验证。

如何修改默认邮件模板？

你可能希望自定义默认邮件模板以更好地与应用程序的品牌形象保持一致。要修改此模板，你应该使用以下命令将邮件视图发布到你的应用程序中：

php artisan vendor:publish --tag=laravel-mail

这将在 resources/views/vendor/mail 中生成多个文件。你可以修改这些文件以及 resources/views/vendor/mail/themes/default.css 文件来更改默认邮件模板的外观和样式。

入门套件 ​

简介 ​

使用入门套件创建应用程序 ​

可用的入门套件 ​

React ​

Svelte ​

Vue ​

Livewire ​

入门套件自定义 ​

React ​

可用布局 ​

侧边栏变体 ​

认证页面布局变体 ​

Svelte ​

可用布局 ​

侧边栏变体 ​

认证页面布局变体 ​

Vue ​

可用布局 ​

侧边栏变体 ​

认证页面布局变体 ​

Livewire ​

可用布局 ​

认证页面布局变体 ​

认证 ​

启用和禁用功能 ​

自定义用户创建和密码重置 ​

双因素认证 ​

频率限制 ​

WorkOS AuthKit 认证 ​

配置你的 WorkOS 入门套件 ​

配置 AuthKit 认证方法 ​

配置 AuthKit 会话超时 ​

Inertia SSR ​

社区维护的入门套件 ​

创建入门套件 ​

常见问题 ​

如何升级？ ​

如何启用邮箱验证？ ​

如何修改默认邮件模板？ ​

入门套件

简介

使用入门套件创建应用程序

可用的入门套件

React

Svelte

Vue

Livewire

入门套件自定义

React

可用布局

侧边栏变体

认证页面布局变体

Svelte

可用布局

侧边栏变体

认证页面布局变体

Vue

可用布局

侧边栏变体

认证页面布局变体

Livewire

可用布局

认证页面布局变体

认证

启用和禁用功能

自定义用户创建和密码重置

双因素认证

频率限制

WorkOS AuthKit 认证

配置你的 WorkOS 入门套件

配置 AuthKit 认证方法

配置 AuthKit 会话超时

Inertia SSR

社区维护的入门套件

创建入门套件

常见问题

如何升级？

如何启用邮箱验证？

如何修改默认邮件模板？