启动套件

介绍
使用启动套件创建应用程序
可用的启动套件
启动套件定制
身份验证
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 组件库。

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 模板并寻找比 React 和 Vue 等 JavaScript 驱动的 SPA 框架更简单的替代方案的团队来说，它是一个很好的选择。

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';

Vue

我们的 Vue 启动套件是用 Inertia 2、Vue 3 Composition 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';

侧边栏变体

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

txt

<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 3、Tailwind 和 Flux UI 构建的。与我们所有的启动套件一样，所有的后端和前端代码都存在于您的应用程序中，以允许完全定制。

Livewire 和 Volt

大多数前端代码位于 resources/views 目录中。您可以自由修改任何代码以定制应用程序的外观和行为：

text

resources/views
├── components            # 可重用的 Livewire 组件
├── flux                  # 自定义 Flux 组件
├── livewire              # Livewire 页面
├── partials              # 可重用的 Blade 部分
├── dashboard.blade.php   # 认证用户仪表板
├── welcome.blade.php     # 访客欢迎页面

传统 Livewire 组件

前端代码位于 resources/views 目录中，而 app/Livewire 目录包含 Livewire 组件的相应后端逻辑。

可用布局

Livewire 启动套件包括两种不同的主要布局供您选择：一个“侧边栏”布局和一个“头部”布局。侧边栏布局是默认的，但您可以通过修改应用程序的 resources/views/components/layouts/app.blade.php 文件中使用的布局来切换到头部布局。此外，您还应该在主 Flux 组件中添加 container 属性：

blade

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

认证页面布局变体

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

要更改您的认证布局，请修改应用程序的 resources/views/components/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() 即可禁用公开注册功能。

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

当用户注册或重置密码时，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、Vue 和 Livewire 启动套件都使用 Laravel 内置的认证系统提供登录、注册、密码重置、电子邮件验证等功能。此外，我们还提供了一个由 WorkOS AuthKit 驱动的每个启动套件的变体，提供：

社交认证（Google、Microsoft、GitHub 和 Apple）
密钥认证
基于电子邮件的“魔法认证”
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 配置设置中禁用“电子邮件 + 密码”认证，允许用户仅通过社交认证提供商、密钥、“魔法认证”和 SSO 进行认证。这使您的应用程序完全避免处理用户密码。

配置 AuthKit 会话超时

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

Inertia SSR

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

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 ​

Vue ​

Livewire ​

启动套件定制 ​

React ​

可用布局 ​

侧边栏变体 ​

认证页面布局变体 ​

Vue ​

可用布局 ​

侧边栏变体 ​

认证页面布局变体 ​

Livewire ​

Livewire 和 Volt ​

传统 Livewire 组件 ​

可用布局 ​

认证页面布局变体 ​

身份验证 ​

启用和禁用功能 ​

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

双重身份验证 ​

速率限制 ​

WorkOS AuthKit 认证 ​

配置您的 WorkOS 启动套件 ​

配置 AuthKit 认证方法 ​

配置 AuthKit 会话超时 ​

Inertia SSR ​

社区维护的入门套件 ​

创建入门套件 ​

常见问题 ​

我该如何升级？ ​

我该如何启用电子邮件验证？ ​

我该如何修改默认电子邮件模板？ ​

启动套件

介绍

使用启动套件创建应用程序

可用的启动套件

React

Vue

Livewire

启动套件定制

React

可用布局

侧边栏变体

认证页面布局变体

Vue

可用布局

侧边栏变体

认证页面布局变体

Livewire

Livewire 和 Volt

传统 Livewire 组件

可用布局

认证页面布局变体

身份验证

启用和禁用功能

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

双重身份验证

速率限制

WorkOS AuthKit 认证

配置您的 WorkOS 启动套件

配置 AuthKit 认证方法

配置 AuthKit 会话超时

Inertia SSR

社区维护的入门套件

创建入门套件

常见问题

我该如何升级？

我该如何启用电子邮件验证？

我该如何修改默认电子邮件模板？