入门套件
简介
为了让您在构建新的 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-app2npm install && npm run build3composer 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 components3├── hooks/ # React hooks4├── layouts/ # Application layouts5├── lib/ # Utility functions and configuration6├── pages/ # Page components7└── 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 components3├── layouts/ # Application layouts4├── lib/ # Utility functions and configuration and Svelte rune modules5├── pages/ # Page components6└── 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 components3├── composables/ # Vue composables / hooks4├── layouts/ # Application layouts5├── lib/ # Utility functions and configuration6├── pages/ # Page components7└── 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/views2├── components # Reusable components3├── flux # Customized Flux components4├── layouts # Application layouts5├── pages # Livewire pages6├── partials # Reusable Blade partials7├── dashboard.blade.php # Authenticated user dashboard8├── 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() 以禁用公共注册。
当使用 React、Svelte 或 Vue 入门套件时,您还需要在前端代码中删除所有对已禁用功能路由的引用。例如,如果您禁用了电子邮件验证,则应删除 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_ID、WORKOS_API_KEY 和 WORKOS_REDIRECT_URL 环境变量。这些变量应与 WorkOS 仪表板为您应用程序提供的值匹配。
1WORKOS_CLIENT_ID=your-client-id2WORKOS_API_KEY=your-api-key3WORKOS_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 文件,以更改默认电子邮件模板的外观和样式。