起步套件

简介

为帮助你更快构建新的 Laravel 应用，我们提供了应用起步套件。这些起步套件包含注册与认证用户所需的路由、控制器与视图。起步套件使用 Laravel Fortify 提供认证。

欢迎使用这些起步套件，但并非必需。你也可以直接安装全新的 Laravel，从零开始构建应用。无论哪种方式，我们相信你会做出出色的作品！

使用起步套件创建应用

要使用我们的起步套件创建新 Laravel 应用，应先安装 PHP 与 Laravel CLI 工具。若已安装 PHP 与 Composer，可通过 Composer 安装 Laravel 安装器 CLI：

shell

composer global require laravel/installer

然后使用 Laravel 安装器 CLI 创建新应用。安装器会提示你选择偏好的起步套件：

shell

laravel new my-app

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

shell

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

启动 Laravel 开发服务器后，可在浏览器访问 http://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 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 3、React 19、Tailwind 4 与 shadcn/ui 构建。与所有起步套件一样，前后端代码都在你的应用内，可完全定制。

大部分前端代码位于 resources/js 目录。你可随意修改任意代码以定制应用外观与行为：

text

resources/js/
├── components/    # Reusable React components
├── hooks/         # React hooks
├── layouts/       # Application layouts
├── lib/           # Utility functions and configuration
├── pages/         # Page components
└── types/         # TypeScript definitions

要发布额外的 shadcn 组件，先找到要发布的组件，然后使用 npx 发布：

shell

npx shadcn@latest add switch

本例中，该命令会将 Switch 组件发布到 resources/js/components/ui/switch.tsx。发布后即可在任意页面中使用：

jsx

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

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

export default MyPage;

可用布局

React 起步套件包含两种主要布局可选：「sidebar」布局与「header」布局。默认是 sidebar 布局，可通过修改应用 resources/js/layouts/app-layout.tsx 文件顶部导入的布局切换为 header 布局：

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

侧边栏布局包含三种变体：默认 sidebar 变体、「inset」变体与「floating」变体。可通过修改 resources/js/components/app-sidebar.tsx 组件选择最喜欢的变体：

text

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

认证页面布局变体

React 起步套件包含的认证页面（如登录页与注册页）也提供三种布局变体：「simple」、「card」与「split」。

要更改认证布局，请修改应用 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 目录。你可随意修改任意代码以定制应用外观与行为：

text

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

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

shell

npx shadcn-svelte@latest add switch

本例中，该命令会将 Switch 组件发布到 resources/js/components/ui/switch/switch.svelte。发布后即可在任意页面中使用：

svelte

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

<div>
    <Switch />
</div>

可用布局

Svelte 起步套件包含两种主要布局可选：「sidebar」布局与「header」布局。默认是 sidebar 布局，可通过修改应用 resources/js/layouts/AppLayout.svelte 文件顶部导入的布局切换为 header 布局：

import AppLayout from '@/layouts/app/AppSidebarLayout.svelte'; // [tl! remove]
import AppLayout from '@/layouts/app/AppHeaderLayout.svelte'; // [tl! add]

侧边栏布局包含三种变体：默认 sidebar 变体、「inset」变体与「floating」变体。可通过修改 resources/js/components/AppSidebar.svelte 组件选择最喜欢的变体：

text

<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 目录。你可随意修改任意代码以定制应用外观与行为：

text

resources/js/
├── components/    # Reusable Vue components
├── composables/   # Vue composables / hooks
├── layouts/       # Application layouts
├── lib/           # Utility functions and configuration
├── pages/         # Page components
└── types/         # TypeScript definitions

要发布额外的 shadcn-vue 组件，先找到要发布的组件，然后使用 npx 发布：

shell

npx shadcn-vue@latest add switch

本例中，该命令会将 Switch 组件发布到 resources/js/components/ui/Switch.vue。发布后即可在任意页面中使用：

vue

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

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

可用布局

Vue 起步套件包含两种主要布局可选：「sidebar」布局与「header」布局。默认是 sidebar 布局，可通过修改应用 resources/js/layouts/AppLayout.vue 文件顶部导入的布局切换为 header 布局：

import AppLayout from '@/layouts/app/AppSidebarLayout.vue'; // [tl! remove]
import AppLayout from '@/layouts/app/AppHeaderLayout.vue'; // [tl! add]

侧边栏布局包含三种变体：默认 sidebar 变体、「inset」变体与「floating」变体。可通过修改 resources/js/components/AppSidebar.vue 组件选择最喜欢的变体：

text

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

认证页面布局变体

Vue 起步套件包含的认证页面（如登录页与注册页）也提供三种布局变体：「simple」、「card」与「split」。

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

import AuthLayout from '@/layouts/auth/AuthSimpleLayout.vue'; // [tl! remove]
import AuthLayout from '@/layouts/auth/AuthSplitLayout.vue'; // [tl! add]

Livewire

我们的 Livewire 起步套件基于 Livewire 4、Tailwind 与 Flux UI 构建。与所有起步套件一样，前后端代码都在你的应用内，可完全定制。

大部分前端代码位于 resources/views 目录。你可随意修改任意代码以定制应用外观与行为：

text

resources/views
├── components            # Reusable components
├── flux                  # Customized Flux components
├── layouts               # Application layouts
├── pages                 # Livewire pages
├── partials              # Reusable Blade partials
├── dashboard.blade.php   # Authenticated user dashboard
├── welcome.blade.php     # Guest user welcome page

可用布局

Livewire 起步套件包含两种主要布局可选：「sidebar」布局与「header」布局。默认是 sidebar 布局，可通过修改应用 resources/views/layouts/app.blade.php 使用的布局切换为 header 布局。此外，应为主要的 Flux 组件添加 container 属性：

blade

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

认证页面布局变体

Livewire 起步套件包含的认证页面（如登录页与注册页）也提供三种布局变体：「simple」、「card」与「split」。

要更改认证布局，请修改应用 resources/views/layouts/auth.blade.php 使用的布局：

blade

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

认证

所有起步套件都使用 Laravel Fortify 处理认证。Fortify 提供登录、注册、密码重置、邮箱验证等所需的路由、控制器与逻辑。

Fortify 会根据应用 config/fortify.php 中启用的功能自动注册下列认证路由：

Route	Method	Description
`/login`	`GET`	Display login form
`/login`	`POST`	Authenticate user
`/logout`	`POST`	Log user out
`/register`	`GET`	Display registration form
`/register`	`POST`	Create new user
`/forgot-password`	`GET`	Display password reset request form
`/forgot-password`	`POST`	Send password reset link
`/reset-password/{token}`	`GET`	Display password reset form
`/reset-password`	`POST`	Update password
`/email/verify`	`GET`	Display email verification notice
`/email/verify/{id}/{hash}`	`GET`	Verify email address
`/email/verification-notification`	`POST`	Resend verification email
`/user/confirm-password`	`GET`	Display password confirmation form
`/user/confirm-password`	`POST`	Confirm password
`/two-factor-challenge`	`GET`	Display 2FA challenge form
`/two-factor-challenge`	`POST`	Verify 2FA code

可使用 php artisan route:list Artisan 命令显示应用中的所有路由。

启用与禁用功能

可在应用的 config/fortify.php 配置文件中控制启用哪些 Fortify 功能：

php

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 目录中的 action 类：

File	Description
`CreateNewUser.php`	Validates and creates new users
`ResetUserPassword.php`	Validates and updates user passwords
`PasswordValidationRules.php`	Defines password validation rules

例如，要定制应用的注册逻辑，应编辑 CreateNewUser action：

php

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 的认证器应用保护账户。默认通过应用 config/fortify.php 中的 Features::twoFactorAuthentication() 启用 2FA。

confirm 选项要求用户在完全启用 2FA 前验证验证码，而 confirmPassword 要求在启用或禁用 2FA 前确认密码。更多细节见 Fortify 的双因素认证文档。

速率限制

速率限制可防止暴力破解与重复登录尝试压垮认证端点。可在应用的 FortifyServiceProvider 中定制 Fortify 的速率限制行为：

php

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 会包含当前团队的 slug。例如，仪表盘路由变为 /{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 驱动的变体，支持：

社交认证（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 控制台中为你的应用提供的值一致：

ini

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 配置中禁用「Email + Password」认证，仅允许用户通过社交认证提供商、通行密钥、「Magic Auth」与 SSO 认证。这样应用可完全避免处理用户密码。

配置 AuthKit 会话超时

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

Inertia SSR

React、Svelte 与 Vue 起步套件兼容 Inertia 的服务端渲染能力。要为应用构建兼容 Inertia SSR 的包，运行 build:ssr 命令：

shell

npm run build:ssr

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

shell

composer dev:ssr

社区维护的起步套件

使用 Laravel 安装器创建新应用时，可通过 --using 标志提供 Packagist 上任意社区维护的起步套件：

shell

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

创建起步套件

为确保他人可用你的起步套件，需将其发布到 Packagist。起步套件应在 .env.example 中定义所需环境变量，并将任何必要的安装后命令列在起步套件 composer.json 的 post-create-project-cmd 数组中。

常见问题

如何升级？

每个起步套件都为下一个应用提供坚实起点。你完全拥有代码，可按设想进行调整、定制与构建。不过，无需更新起步套件本身。

如何启用邮箱验证？

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

php

<?php

namespace App\Models;

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

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

注册后，用户将收到验证邮件。若要在用户邮箱验证前限制某些路由的访问，请为路由添加 verified 中间件：

php

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

INFO

使用起步套件的 WorkOS 变体时不需要邮箱验证。

如何修改默认邮件模板？

你可能希望定制默认邮件模板，以更好地匹配应用品牌。要修改该模板，应使用下列命令将邮件视图发布到应用：

shell

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

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

起步套件 ​

简介 ​

使用起步套件创建应用 ​

可用起步套件 ​

React ​

Svelte ​

Vue ​

Livewire ​

起步套件定制 ​

React ​

可用布局 ​

侧边栏变体 ​

认证页面布局变体 ​

Svelte ​

可用布局 ​

侧边栏变体 ​

认证页面布局变体 ​

Vue ​

可用布局 ​

侧边栏变体 ​

认证页面布局变体 ​

Livewire ​

可用布局 ​

认证页面布局变体 ​

认证 ​

启用与禁用功能 ​

定制用户创建与密码重置 ​

双因素认证 ​

速率限制 ​

团队 ​

WorkOS AuthKit 认证 ​

配置 WorkOS 起步套件 ​

配置 AuthKit 认证方式 ​

配置 AuthKit 会话超时 ​

Inertia SSR ​

社区维护的起步套件 ​

创建起步套件 ​

常见问题 ​

如何升级？ ​

如何启用邮箱验证？ ​

如何修改默认邮件模板？ ​

起步套件

简介

使用起步套件创建应用

可用起步套件

React

Svelte

Vue

Livewire

起步套件定制

React

可用布局

侧边栏变体

认证页面布局变体

Svelte

可用布局

侧边栏变体

认证页面布局变体

Vue

可用布局

侧边栏变体

认证页面布局变体

Livewire

可用布局

认证页面布局变体

认证

启用与禁用功能

定制用户创建与密码重置

双因素认证

速率限制

团队

WorkOS AuthKit 认证

配置 WorkOS 起步套件

配置 AuthKit 认证方式

配置 AuthKit 会话超时

Inertia SSR

社区维护的起步套件

创建起步套件

常见问题

如何升级？

如何启用邮箱验证？

如何修改默认邮件模板？