入门套件

简介
使用入门套件创建应用程序
可用的入门套件
入门套件自定义
认证
WorkOS AuthKit 认证
Inertia SSR
社区维护的入门套件
常见问题解答

简介

为了帮助你快速开始构建新的 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 组合式 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 钩子
├── 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 入门套件包含两种不同的主要布局供你选择：“侧边栏”布局和“头部”布局。侧边栏布局是默认的，但你可以通过修改应用程序的 resources/js/layouts/app-layout.tsx 文件顶部导入的布局来切换到头部布局：

import AppLayoutTemplate from '@/layouts/app/app-sidebar-layout';  
import AppLayoutTemplate from '@/layouts/app/app-header-layout';

侧边栏变体

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

text

<Sidebar collapsible="icon" variant="sidebar">
<Sidebar collapsible="icon" variant="inset">

认证页面布局变体

React 入门套件中包含的认证页面，如登录页面和注册页面，也提供了三种不同的布局变体：“简单”、“卡片”和“分割”。

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

import AuthLayoutTemplate from '@/layouts/auth/auth-simple-layout';  
import AuthLayoutTemplate from '@/layouts/auth/auth-split-layout';

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 入门套件包含两种不同的主要布局供你选择：“侧边栏”布局和“头部”布局。侧边栏布局是默认的，但你可以通过修改应用程序的 resources/js/layouts/AppLayout.svelte 文件顶部导入的布局来切换到头部布局：

import AppLayout from '@/layouts/app/AppSidebarLayout.svelte';  
import AppLayout from '@/layouts/app/AppHeaderLayout.svelte';

侧边栏变体

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

text

<Sidebar collapsible="icon" variant="sidebar">
<Sidebar collapsible="icon" variant="inset">

认证页面布局变体

Svelte 入门套件中包含的认证页面，如登录页面和注册页面，也提供了三种不同的布局变体：“简单”、“卡片”和“分割”。

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

import AuthLayout from '@/layouts/auth/AuthSimpleLayout.svelte';  
import AuthLayout from '@/layouts/auth/AuthSplitLayout.svelte';

Vue

我们的 Vue 入门套件基于 Inertia 2、Vue 3 组合式 API、Tailwind 和 shadcn-vue 构建。与我们所有的入门套件一样，所有的后端和前端代码都存在于你的应用程序中，以实现完全自定义。

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

text

resources/js/
├── components/    # 可复用的 Vue 组件
├── composables/   # Vue 组合式函数 / 钩子
├── 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 入门套件包含两种不同的主要布局供你选择：“侧边栏”布局和“头部”布局。侧边栏布局是默认的，但你可以通过修改应用程序的 resources/js/layouts/AppLayout.vue 文件顶部导入的布局来切换到头部布局：

import AppLayout from '@/layouts/app/AppSidebarLayout.vue';  
import AppLayout from '@/layouts/app/AppHeaderLayout.vue';

侧边栏变体

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

text

<Sidebar collapsible="icon" variant="sidebar">
<Sidebar collapsible="icon" variant="inset">

认证页面布局变体

Vue 入门套件中包含的认证页面，如登录页面和注册页面，也提供了三种不同的布局变体：“简单”、“卡片”和“分割”。

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

import AuthLayout from '@/layouts/auth/AuthSimpleLayout.vue';  
import AuthLayout from '@/layouts/auth/AuthSplitLayout.vue';

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 入门套件包含两种不同的主要布局供你选择：“侧边栏”布局和“头部”布局。侧边栏布局是默认的，但你可以通过修改应用程序的 resources/views/layouts/app.blade.php 文件使用的布局来切换到头部布局。此外，你应该向主要的 Flux 组件添加 container 属性：

blade

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

认证页面布局变体

Livewire 入门套件中包含的认证页面，如登录页面和注册页面，也提供了三种不同的布局变体：“简单”、“卡片”和“分割”。

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

blade

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

认证

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

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

路由	方法	描述
`/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 目录中的操作类：

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

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

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

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

双因素认证

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

confirm 选项要求用户在完全启用双因素认证之前验证一个代码，而 confirmPassword 要求在启用或禁用双因素认证之前确认密码。更多详情，请参阅 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 认证
基于电子邮件的“魔法认证”
单点登录 (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 配置设置中禁用“电子邮件 + 密码”认证，允许用户仅通过社交认证提供商、passkey、“魔法认证”和 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 应用程序时，你可以将 Packagist 上可用的任何社区维护的入门套件提供给 --using 标志：

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 中间件添加到这些路由：

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

社区维护的入门套件

创建入门套件

常见问题解答

如何升级？

如何启用邮箱验证？

如何修改默认邮件模板？