入门套件-Laravel 文档-果果开发

简介

为了帮助你快速上手构建新的 Laravel 应用程序，我们很高兴提供应用程序入门套件。这些入门套件能让你在构建下一个 Laravel 应用程序时抢占先机，其中包含用于注册和验证应用程序用户所需的路由、控制器和视图。这些入门套件使用Laravel Fortify来提供身份验证功能。

虽然欢迎你使用这些入门套件，但它们并非必需。你也可以只安装一份全新的 Laravel，从零开始构建自己的应用程序。无论如何，我们相信你一定能打造出出色的作品！

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

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

composer global require laravel/installer

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

laravel new my-app

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

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

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

可用的入门套件

React

我们的 React 入门套件为构建采用 React 前端（使用 Inertia）的 Laravel 应用程序提供了坚实、现代的起点。

借助 Inertia，你可以使用经典的服务器端路由和控制器构建现代的单页 React 应用程序。这能让你兼具 React 的前端能力、Laravel 惊人的后端生产力以及超快的 Vite 编译速度。

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

Svelte

我们的 Svelte 入门套件为构建采用 Svelte 前端（使用 Inertia）的 Laravel 应用程序提供了坚实、现代的起点。

借助 Inertia，你可以使用经典的服务器端路由和控制器构建现代的单页 Svelte 应用程序。这能让你兼具 Svelte 的前端能力、Laravel 惊人的后端生产力以及超快的 Vite 编译速度。

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

Vue

我们的 Vue 入门套件为构建采用 Vue 前端（使用 Inertia）的 Laravel 应用程序提供了极佳的起点。

借助 Inertia，你可以使用经典的服务器端路由和控制器构建现代的单页 Vue 应用程序。这能让你兼具 Vue 的前端能力、Laravel 惊人的后端生产力以及超快的 Vite 编译速度。

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

Livewire

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

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

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

入门套件自定义

React

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

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

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

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

npx shadcn@latest add switch

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

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

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

export default MyPage;

可用布局

React 入门套件包含两种可供你选择的主要布局：一种是“侧边栏”布局，另一种是“页眉”布局。侧边栏布局为默认布局，你可以通过修改应用程序 resources/js/layouts/app-layout.tsx 文件顶部导入的布局，切换到页眉布局：

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

侧边栏变体

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

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

身份验证页面布局变体

React 入门套件中包含的身份验证页面（例如登录页面和注册页面）也提供三种不同的布局变体：“简约”、“卡片”和“分屏”。

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

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

Svelte

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

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

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

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

npx shadcn-svelte@latest add switch

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

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

<div>
    <Switch />
</div>

可用布局

Svelte 入门套件包含两种可供你选择的主要布局：一种是“侧边栏”布局，另一种是“页眉”布局。侧边栏布局为默认布局，你可以通过修改应用程序 resources/js/layouts/AppLayout.svelte 文件顶部导入的布局，切换到页眉布局：

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

侧边栏变体

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

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

身份验证页面布局变体

Svelte 启动套件中包含的身份验证页面（如登录页面和注册页面）也提供三种不同的布局变体：“简洁”、“卡片”和“分屏”。

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

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

Vue

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

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

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

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

npx shadcn-vue@latest add switch

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

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

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

可用布局

Vue 启动套件包含两种不同的主要布局供你选择：“侧边栏”布局和“页眉”布局。侧边栏布局为默认布局，但你可以通过修改应用程序 resources/js/layouts/AppLayout.vue 文件顶部导入的布局，切换到页眉布局：

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

侧边栏变体

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

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

身份验证页面布局变体

Vue 启动套件中包含的身份验证页面（如登录页面和注册页面）也提供三种不同的布局变体：“简洁”、“卡片”和“分屏”。

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

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

Livewire

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

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

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 属性：

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

身份验证页面布局变体

Livewire 启动套件中包含的身份验证页面（如登录页面和注册页面）也提供三种不同的布局变体：“简洁”、“卡片”和“分屏”。

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

<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 功能：

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 动作：


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() 默认启用 2FA。

confirm 选项要求用户在 2FA 完全启用前验证验证码，confirmPassword 选项则要求在启用或禁用 2FA 前确认密码。如需了解详情，请参阅Fortify 的双因素认证文档。

速率限制

速率限制可防止暴力破解及重复登录尝试对认证端点造成过载。可在应用的 FortifyServiceProvider 中自定义 Fortify 的速率限制行为：

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

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

团队

React、Svelte、Vue 和 Livewire 入门套件也可生成支持团队功能的版本。启用团队功能后，每个用户属于一个或多个团队，且有一个当前团队。注册时，新用户会自动获得一个个人团队。入门套件还包含用于创建团队、切换团队、邀请成员和更新团队详情的团队管理界面。

当路由限定在当前团队时，URL 会包含当前团队的标识。例如，仪表板路由变为 /{current_team}/dashboard，团队管理页面使用 settings/teams/{team} 等路由。使用 {current_team} 和 {team} 路由参数时，入门套件会先自动确保已认证用户属于请求的团队，才允许访问该路由。

为更方便地生成支持团队功能的 URL，入门套件为已认证用户的当前团队注册了 URL 默认值。这使得调用 route('dashboard') 等辅助函数时，会自动包含当前团队的标识。用户登录、注册或切换团队时，入门套件会更新当前团队并刷新这些 URL 默认值，确保生成的链接始终使用正确的团队上下文。

创建或重命名团队时，入门套件还会阻止用户选择可能导致不安全或冲突路由段的保留名称。例如，不能使用与 settings、login 或 dashboard 等路由前缀冲突的名称。

WorkOS AuthKit 认证

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

社交认证（Google、Microsoft、GitHub 和 Apple）
通行密钥认证
基于邮箱的“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 控制台中为应用提供的值一致：

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 配置设置中禁用“邮箱 + 密码”认证，仅允许用户通过社交认证提供商、通行密钥、“Magic Auth”和 SSO 进行认证。这样可让应用完全无需处理用户密码。

配置 AuthKit 会话超时

此外，建议将 WorkOS AuthKit 的会话不活动超时时间配置为与 Laravel 应用配置的会话超时阈值一致，通常为两小时。

Inertia SSR

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

npm run build:ssr

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

composer dev:ssr

社区维护的入门套件

使用 Laravel 安装器创建新应用时，可通过 --using 标志指定 Packagist 上任何由社区维护的入门套件：

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

创建入门套件

若要让其他用户可使用你的入门套件，需将其发布到Packagist。入门套件应在 .env.example 文件中定义所需的环境变量，并将所有必要的安装后命令列在入门套件 composer.json 文件的 post-create-project-cmd 数组中。

常见问题

如何升级？

每个入门套件都能为开发下一个应用提供坚实的起点。你拥有代码的全部所有权，可按自己的设想调整、自定义并构建应用。但无需更新入门套件本身。

如何启用邮箱验证？

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

<?php

namespace App\Models;

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

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

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

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

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

如何修改默认邮件模板？

您可能需要自定义默认邮件模板，使其更符合您应用的品牌风格。若要修改此模板，您应使用以下命令将邮件视图发布到您的应用中：

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

这将在 resources/views/vendor/mail 目录中生成若干文件。您可以修改其中任意文件，以及 resources/views/vendor/mail/themes/default.css 文件，从而更改默认邮件模板的外观与样式。