入门套件

• 简介
• 使用入门套件创建应用
• 可用的入门套件
  • React
  • Svelte
  • Vue
  • Livewire
• 自定义入门套件
  • React
  • Svelte
  • Vue
  • Livewire
• 认证
  • 启用和禁用功能
  • 自定义用户创建与密码重置
  • 双因素认证
  • 频率限制
• 团队协作
• WorkOS AuthKit 认证
• Inertia SSR
• 社区维护的入门套件
• 常见问题解答

简介

为了助你更快地开启新的 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 开发服务器后，你的应用便可以在浏览器中通过 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 模板的团队，且希望寻找一种比 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 文件顶部导入的布局来切换为顶部导航布局：

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

侧边栏变体

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

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

认证页面布局变体

React 入门套件包含的认证页面（如登录页面和注册页面）同样提供三种不同的布局变体：「简约」、「卡片」和「分栏」。

要更改认证布局，修改应用 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 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 文件顶部导入的布局来切换为顶部导航布局：

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 组件来选择你最喜欢的变体：

<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 3、Vue 3 Composition API、Tailwind 和 shadcn-vue 构建。与我们所有的启动套件一样，所有后端和前端代码都包含在你的应用程序中，因此你可以进行完全自定义。

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

resources/js/
├── components/    # 可复用的 Vue 组件
├── composables/   # Vue composables / hooks
├── 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 文件顶部导入的布局来切换到页眉布局：

import AppLayout from '@/layouts/app/AppSidebarLayout.vue'; // [tl! 移除]
import AppLayout from '@/layouts/app/AppHeaderLayout.vue'; // [tl! 增加]

侧边栏变体

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

<Sidebar collapsible="icon" variant="sidebar"> [tl! 移除]
<Sidebar collapsible="icon" variant="inset"> [tl! 增加]

认证页面布局变体

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

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

import AuthLayout from '@/layouts/auth/AuthSimpleLayout.vue'; // [tl! 移除]
import AuthLayout from '@/layouts/auth/AuthSplitLayout.vue'; // [tl! 增加]

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 启动套件提供两种不同的主要布局供你选择："sidebar" 侧边栏布局和 "header" 顶部栏布局。

默认使用侧边栏布局，但你可以通过修改应用程序的 resources/views/layouts/app.blade.php 文件中使用的布局来切换为顶部栏布局。

此外，你还应该为主要的 Flux 组件添加 container 属性：

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

认证页面布局变体

Livewire 启动套件中包含的认证页面，例如登录页面和注册页面，同样提供三种不同的布局变体："simple"、"card" 和 "split"。

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

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

身份认证

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

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

可以使用 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 来实现类型安全的路由。Wayfinder 会在构建时生成路由定义。如果你的代码引用了已经不存在的路由，应用程序将无法成功构建。

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

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

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

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 的请求频率限制行为：

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 启动套件也可以在生成时启用团队支持。

启用团队功能后，每个用户都可以属于一个或多个团队，并且会有一个当前团队。用户注册时，系统会自动为新用户创建一个个人团队。启动套件还包含团队管理页面，可用于创建团队、切换团队、邀请成员以及更新团队信息。
当某个路由限定在当前团队范围内时，当前团队的 slug 会包含在 URL 中。例如，仪表盘路由会变为 /{current_team}/dashboard，而团队管理页面则会使用类似 settings/teams/{team} 的路由。
在使用 {current_team} 和 {team} 路由参数时，启动套件会自动确保当前已认证用户属于所请求的团队，然后才允许访问该路由。
为了更方便地生成包含团队上下文的 URL，启动套件会为已认证用户的当前团队注册 URL 默认值。这样，在调用 route('dashboard') 等辅助函数时，就会自动包含当前团队的 slug。
当用户登录、注册或切换团队时，启动套件会更新当前团队，并刷新这些 URL 默认值，从而确保生成的链接始终使用正确的团队上下文。
在创建或重命名团队时，启动套件还会阻止用户使用可能导致不安全或路由冲突的保留名称。
例如，与 settings、login 或 dashboard 等路由前缀冲突的名称将无法使用。

WorkOS AuthKit 身份认证

默认情况下，React、Svelte、Vue 和 Livewire 启动套件均使用 Laravel 内置的身份验证系统来提供登录、注册、密码重置、电子邮件验证等功能。此外，我们还为每个启动套件提供了由 WorkOS AuthKit 驱动的版本，该版本提供：

使用 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 安装程序创建新的 Laravel 应用程序时，你可以将 Packagist 上任何由社区维护的启动套件通过 --using 参数指定：

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 文件，以更改默认电子邮件模板的外观和样式。

本译文仅用于学习和交流目的，转载请务必注明文章译者、出处、和本文链接
我们的翻译工作遵照 CC 协议，如果我们的工作有侵犯到您的权益，请及时联系我们。

原文地址：https://learnku.com/docs/laravel/13.x/st...

译文地址：https://learnku.com/docs/laravel/13.x/st...