入门套件

简介

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

虽然我们欢迎您使用这些入门套件，但它们不是必需的。你也可以选择从零开始构建自己的应用，只需安装一个全新的 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 开发服务器后，您的应用程序将可以在您的 Web 浏览器中通过 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 组合式 API、TypeScript、Tailwind 和 shadcn-vue 组件库。

Livewire

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

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

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

入门套件定制

React

我们的 React 入门套件是使用 Inertia 2、React 19、Tailwind 4 和 shadcn/ui 构建的。与我们所有的入门套件一样，所有后端和前端代码都存在于您的应用程序中，以允许完全定制。

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

resources/js/
├── components/    # 可重用 React 组件
├── hooks/         # React hooks
├── 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';
+ import AppLayoutTemplate from '@/layouts/app/app-header-layout';

侧边栏变体

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

- <Sidebar collapsible="icon" variant="sidebar">
+ <Sidebar collapsible="icon" variant="inset">

身份验证页面布局变体

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

要更改您的身份验证布局，请修改应用程序 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 组合式 API、Tailwind 和 shadcn-vue 构建的。与我们所有的入门套件一样，所有后端和前端代码都存在于您的应用程序中，以允许完全定制。

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

resources/js/
├── components/    # 可重用 Vue 组件
├── composables/   # Vue 可组合/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 入门套件包含两种不同的主要布局供您选择：“侧边栏(sidebar)” 布局和 “页眉(header)” 布局。侧边栏布局是默认的，但您可以通过修改应用程序 resources/js/layouts/AppLayout.vue 文件顶部导入的布局来切换到页眉布局：

- import AppLayout from '@/layouts/app/AppSidebarLayout.vue';
+ import AppLayout from '@/layouts/app/AppHeaderLayout.vue';

侧边栏变体

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

- <Sidebar collapsible="icon" variant="sidebar">
+ <Sidebar collapsible="icon" variant="inset">

身份验证页面布局变体

Vue 入门套件中包含的身份验证页面（例如登录页面和注册页面）也提供三种不同的布局变体：“简单(simple)”、“卡片(card)” 和 “拆分(split)”。

要更改您的身份验证布局，请修改应用程序 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 目录中。您可以自由修改任何代码以自定义应用程序的外观和行为：

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

传统 Livewire 组件

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

可用布局

Livewire 入门套件包含两种不同的主要布局供您选择：“侧边栏(sidebar)” 布局和 “页眉(header)” 布局。侧边栏布局是默认的，但您可以通过修改应用程序 resources/views/components/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/components/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() 即可禁用公开注册。

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

当用户注册或重置密码时，Fortify 会调用位于你应用程序 app/Actions/Fortify 目录下的操作类（Action Classes）：

例如，要自定义应用程序的注册逻辑，你可以编辑 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 的身份验证器应用来保护账户。默认情况下，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());
});

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 仪表板中为您应用程序提供的值匹配：

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 命令：

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

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

您可能希望自定义默认电子邮件模板，使其更好地与您的应用程序品牌保持一致。要修改此模板，您应该使用以下命令将电子邮件视图发布到您的应用程序中：

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

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