跳转至内容

入门套件

简介

为了让您在构建新的 Laravel 应用程序时有一个良好的开端,我们很高兴提供 应用程序入门套件。这些入门套件为您构建下一个 Laravel 应用程序提供了一个起点,并包含了注册和验证应用程序用户所需的路由、控制器和视图。这些入门套件使用 Laravel Fortify 来提供身份验证。

虽然欢迎您使用这些入门套件,但它们并非强制要求。您可以随时通过安装全新的 Laravel 来从零开始构建自己的应用程序。无论哪种方式,我们相信您都会创造出色的作品!

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

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

1composer global require laravel/installer

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

1laravel new my-app

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

1cd my-app
2npm install && npm run build
3composer run dev

一旦启动了 Laravel 开发服务器,您就可以在浏览器中通过 https://: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 模板且正在寻找比 React、Svelte 和 Vue 等 JavaScript 驱动的 SPA 框架更简单替代方案的团队。

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

入门套件自定义

React

我们的 React 入门套件采用 Inertia 2、React 19、Tailwind 4 和 shadcn/ui 构建。与我们所有的入门套件一样,所有的后端和前端代码都存在于您的应用程序中,以便进行全面自定义。

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

1resources/js/
2├── components/ # Reusable React components
3├── hooks/ # React hooks
4├── layouts/ # Application layouts
5├── lib/ # Utility functions and configuration
6├── pages/ # Page components
7└── types/ # TypeScript definitions

要发布额外的 shadcn 组件,请先 找到您要发布的组件。然后,使用 npx 发布该组件:

1npx shadcn@latest add switch

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

1import { Switch } from "@/components/ui/switch"
2 
3const MyPage = () => {
4 return (
5 <div>
6 <Switch />
7 </div>
8 );
9};
10 
11export default MyPage;

可用布局

React 入门套件包含两种主要布局供您选择:侧边栏(sidebar)布局和页眉(header)布局。侧边栏布局是默认设置,但您可以通过修改应用程序 resources/js/layouts/app-layout.tsx 文件顶部导入的布局来切换到页眉布局。

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

侧边栏变体

侧边栏布局包括三种不同的变体:默认侧边栏变体、"inset" 变体和 "floating" 变体。您可以通过修改 resources/js/components/app-sidebar.tsx 组件来选择最喜欢的变体。

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

身份验证页面布局变体

React 入门套件附带的身份验证页面(例如登录页面和注册页面)也提供三种不同的布局变体:"simple"、"card" 和 "split"。

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

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

Svelte

我们的 Svelte 入门套件采用 Inertia 2、Svelte 5、Tailwind 和 shadcn-svelte 构建。与我们所有的入门套件一样,所有的后端和前端代码都存在于您的应用程序中,以便进行全面自定义。

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

1resources/js/
2├── components/ # Reusable Svelte components
3├── layouts/ # Application layouts
4├── lib/ # Utility functions and configuration and Svelte rune modules
5├── pages/ # Page components
6└── types/ # TypeScript definitions

要发布额外的 shadcn-svelte 组件,请先 找到您要发布的组件。然后,使用 npx 发布该组件:

1npx shadcn-svelte@latest add switch

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

1<script lang="ts">
2 import { Switch } from '@/components/ui/switch'
3</script>
4 
5<div>
6 <Switch />
7</div>

可用布局

Svelte 入门套件包含两种主要布局供您选择:侧边栏(sidebar)布局和页眉(header)布局。侧边栏布局是默认设置,但您可以通过修改应用程序 resources/js/layouts/AppLayout.svelte 文件顶部导入的布局来切换到页眉布局。

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

侧边栏变体

侧边栏布局包括三种不同的变体:默认侧边栏变体、"inset" 变体和 "floating" 变体。您可以通过修改 resources/js/components/AppSidebar.svelte 组件来选择最喜欢的变体。

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

身份验证页面布局变体

Svelte 入门套件附带的身份验证页面(例如登录页面和注册页面)也提供三种不同的布局变体:"simple"、"card" 和 "split"。

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

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

Vue

我们的 Vue 入门套件采用 Inertia 2、Vue 3 Composition API、Tailwind 和 shadcn-vue 构建。与我们所有的入门套件一样,所有的后端和前端代码都存在于您的应用程序中,以便进行全面自定义。

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

1resources/js/
2├── components/ # Reusable Vue components
3├── composables/ # Vue composables / hooks
4├── layouts/ # Application layouts
5├── lib/ # Utility functions and configuration
6├── pages/ # Page components
7└── types/ # TypeScript definitions

要发布额外的 shadcn-vue 组件,请先 找到您要发布的组件。然后,使用 npx 发布该组件:

1npx shadcn-vue@latest add switch

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

1<script setup lang="ts">
2import { Switch } from '@/components/ui/switch'
3</script>
4 
5<template>
6 <div>
7 <Switch />
8 </div>
9</template>

可用布局

Vue 入门套件包含两种主要布局供您选择:侧边栏(sidebar)布局和页眉(header)布局。侧边栏布局是默认设置,但您可以通过修改应用程序 resources/js/layouts/AppLayout.vue 文件顶部导入的布局来切换到页眉布局。

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

侧边栏变体

侧边栏布局包括三种不同的变体:默认侧边栏变体、"inset" 变体和 "floating" 变体。您可以通过修改 resources/js/components/AppSidebar.vue 组件来选择最喜欢的变体。

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

身份验证页面布局变体

Vue 入门套件附带的身份验证页面(例如登录页面和注册页面)也提供三种不同的布局变体:"simple"、"card" 和 "split"。

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

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

Livewire

我们的 Livewire 入门套件采用 Livewire 4、Tailwind 和 Flux UI 构建。与我们所有的入门套件一样,所有的后端和前端代码都存在于您的应用程序中,以便进行全面自定义。

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

1resources/views
2├── components # Reusable components
3├── flux # Customized Flux components
4├── layouts # Application layouts
5├── pages # Livewire pages
6├── partials # Reusable Blade partials
7├── dashboard.blade.php # Authenticated user dashboard
8├── welcome.blade.php # Guest user welcome page

可用布局

Livewire 入门套件包含两种主要布局供您选择:侧边栏(sidebar)布局和页眉(header)布局。侧边栏布局是默认设置,但您可以通过修改应用程序 resources/views/layouts/app.blade.php 文件使用的布局来切换到页眉布局。此外,您还应该在主要的 Flux 组件中添加 container 属性。

1<x-layouts::app.header>
2 <flux:main container>
3 {{ $slot }}
4 </flux:main>
5</x-layouts::app.header>

身份验证页面布局变体

Livewire 入门套件附带的身份验证页面(例如登录页面和注册页面)也提供三种不同的布局变体:"simple"、"card" 和 "split"。

要更改您的身份验证布局,请修改应用程序 resources/views/layouts/auth.blade.php 文件使用的布局。

1<x-layouts::auth.split>
2 {{ $slot }}
3</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 显示 2FA 验证挑战表单
/two-factor-challenge POST 验证 2FA 代码

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

启用和禁用功能

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

1use Laravel\Fortify\Features;
2 
3'features' => [
4 Features::registration(),
5 Features::resetPasswords(),
6 Features::emailVerification(),
7 Features::twoFactorAuthentication([
8 'confirm' => true,
9 'confirmPassword' => true,
10 ]),
11],

要禁用某项功能,只需注释掉或从 features 数组中删除该功能条目即可。例如,删除 Features::registration() 以禁用公共注册。

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

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

当用户注册或重置密码时,Fortify 会调用位于应用程序 app/Actions/Fortify 目录中的操作类:

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

例如,要自定义应用程序的注册逻辑,您应该编辑 CreateNewUser 操作。

1public function create(array $input): User
2{
3 Validator::make($input, [
4 'name' => ['required', 'string', 'max:255'],
5 'email' => ['required', 'email', 'max:255', 'unique:users'],
6 'phone' => ['required', 'string', 'max:20'],
7 'password' => $this->passwordRules(),
8 ])->validate();
9 
10 return User::create([
11 'name' => $input['name'],
12 'email' => $input['email'],
13 'phone' => $input['phone'],
14 'password' => Hash::make($input['password']),
15 ]);
16}

双重身份验证

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

confirm 选项要求用户在完全启用 2FA 之前验证代码,而 confirmPassword 要求在启用或禁用 2FA 之前确认密码。有关更多详细信息,请参阅 Fortify 的双重身份验证文档

速率限制

速率限制(Rate limiting)可以防止暴力破解和重复的登录尝试使您的身份验证端点不堪重负。您可以在应用程序的 FortifyServiceProvider 中自定义 Fortify 的速率限制行为。

1use Illuminate\Support\Facades\RateLimiter;
2use Illuminate\Cache\RateLimiting\Limit;
3 
4RateLimiter::for('login', function ($request) {
5 return Limit::perMinute(5)->by($request->email.$request->ip());
6});

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_IDWORKOS_API_KEYWORKOS_REDIRECT_URL 环境变量。这些变量应与 WorkOS 仪表板为您应用程序提供的值匹配。

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

此外,您还应该在 WorkOS 仪表板中配置应用程序主页 URL。此 URL 是用户从您的应用程序注销后将被重定向到的地址。

配置 AuthKit 身份验证方法

当使用 WorkOS 驱动的入门套件时,我们建议您在应用程序的 WorkOS AuthKit 配置设置中禁用“电子邮件 + 密码”身份验证,仅允许用户通过社交身份验证提供商、通行密钥、“魔法登录”和 SSO 进行身份验证。这使您的应用程序能够完全避免处理用户密码。

配置 AuthKit 会话超时

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

Inertia SSR

React、Svelte 和 Vue 入门套件与 Inertia 的 服务器端渲染 (SSR) 功能兼容。要为您的应用程序构建 Inertia SSR 兼容的包,请运行 build:ssr 命令:

1npm run build:ssr

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

1composer dev:ssr

社区维护的入门套件

当使用 Laravel 安装程序创建新的 Laravel 应用程序时,您可以将 Packagist 上提供的任何社区维护的入门套件传递给 --using 标志。

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

创建入门套件

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

常见问题解答

我该如何升级?

每个入门套件都为您下一个应用程序提供了一个坚实的起点。拥有代码的完全所有权,您可以按照自己的设想调整、自定义和构建您的应用程序。但是,无需更新入门套件本身。

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

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

1<?php
2 
3namespace App\Models;
4 
5use Illuminate\Contracts\Auth\MustVerifyEmail;
6// ...
7 
8class User extends Authenticatable implements MustVerifyEmail
9{
10 // ...
11}

注册后,用户将收到一封验证邮件。要限制对某些路由的访问,直到用户的电子邮件地址经过验证,请将 verified 中间件添加到这些路由中。

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

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

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

您可能希望自定义默认的电子邮件模板,以使其更符合您应用程序的品牌形象。要修改此模板,您应该使用以下命令将邮件视图发布到您的应用程序中:

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

这将会在 resources/views/vendor/mail 中生成几个文件。您可以修改这些文件中的任何一个,以及 resources/views/vendor/mail/themes/default.css 文件,以更改默认电子邮件模板的外观和样式。