起步套件

Laravel 提供了起步套件，帮你快速搭好应用骨架——注册、登录、密码重置等认证功能开箱即用，路由、控制器、视图都给你备好了。起步套件底层用的是 Laravel Fortify 做认证。

当然，起步套件只是帮你省事，不是必须的。你完全可以从一个空白 Laravel 开始自己搭。

建项目

先确保你装好了 PHP 和 Laravel CLI 工具（没装的话看安装指南）。如果已有 PHP 和 Composer，用 Composer 装一下 Laravel 安装器：

composer global require laravel/installer

跑 laravel new 建项目，安装器会让你选起步套件：

laravel new my-app

项目建好后，装前端依赖、构建前端资源，再启动开发服务器：

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

开发服务器跑起来后，浏览器打开 http://localhost:8000 就能看到你的应用了。

四个起步套件

React

React 起步套件用 Inertia 把 Laravel 后端和 React 前端连起来。Inertia 让你用传统服务端路由和控制器写现代单页应用——既有 React 的前端能力，又有 Laravel 的后端效率和 Vite 的极速编译。技术栈：React 19、TypeScript、Tailwind、shadcn/ui 组件库。

Svelte

Svelte 起步套件同样基于 Inertia，用 Svelte 做前端。技术栈：Svelte 5、TypeScript、Tailwind、shadcn-svelte 组件库。

Vue

Vue 起步套件也是 Inertia 驱动。技术栈：Vue Composition API、TypeScript、Tailwind、shadcn-vue 组件库。

Livewire

Livewire 起步套件不走 Inertia，而是用 Laravel Livewire 纯 PHP 写动态交互界面。如果你的团队习惯 Blade 模板、不想碰 React / Svelte / Vue 这类 JS 框架，Livewire 是个好选择。技术栈：Livewire、Tailwind、Flux UI 组件库。

定制起步套件

所有起步套件的前后端代码都在你的应用里，想怎么改就怎么改。下面按套件分别说明。

React 定制

React 起步套件基于 Inertia 3、React 19、Tailwind 4 和 shadcn/ui。前端代码主要在 resources/js 目录：

resources/js/
├── components/    # 可复用的 React 组件
├── hooks/         # React hooks
├── layouts/       # 应用布局
├── lib/           # 工具函数和配置
├── pages/         # 页面组件
└── types/         # TypeScript 类型定义

要加 shadcn/ui 组件，先去 shadcn/ui 官网找到你要的组件，然后用 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 布局切换

React 起步套件有两种主布局：侧边栏（sidebar，默认）和顶部导航栏（header）。要切换的话，改 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]

React 侧边栏变体

侧边栏还有三种变体：默认（sidebar）、内嵌（inset）、浮动（floating），改 resources/js/components/app-sidebar.tsx 的 variant 属性：

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

resources/js/
├── components/    # 可复用的 Svelte 组件
├── layouts/       # 应用布局
├── lib/           # 工具函数、配置和 Svelte rune 模块
├── pages/         # 页面组件
└── types/         # TypeScript 类型定义

添加 shadcn-svelte 组件——先去 shadcn-svelte 官网找到组件，然后：

npx shadcn-svelte@latest add 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]

Svelte 侧边栏变体

侧边栏变体（默认、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 组件——先去 shadcn-vue 官网找到组件，然后：

npx shadcn-vue@latest add 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! remove]
import AppLayout from '@/layouts/app/AppHeaderLayout.vue'; // [tl! add]

Vue 侧边栏变体

侧边栏变体（默认、inset、floating）改 resources/js/components/AppSidebar.vue：

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

resources/views
├── components            # 可复用组件
├── flux                  # 定制化的 Flux 组件
├── layouts               # 应用布局
├── pages                 # Livewire 页面
├── partials              # 可复用的 Blade 局部模板
├── dashboard.blade.php   # 已认证用户的仪表盘
├── welcome.blade.php     # 访客欢迎页

Livewire 布局切换

两种主布局：侧边栏（默认）和顶部导航栏。切换到顶部导航栏要改 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 命令可以查看应用里所有路由。

开关功能

在 config/fortify.php 的 features 数组里控制哪些功能开着：

use Laravel\Fortify\Features;

'features' => [
    Features::registration(),
    Features::resetPasswords(),
    Features::emailVerification(),
    Features::twoFactorAuthentication([
        'confirm' => true,
        'confirmPassword' => true,
    ]),
],

要关掉某个功能，把对应那行注释掉或删掉就行。比如删掉 Features::registration() 就关闭了公开注册。

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

用户注册或重置密码时，Fortify 会调用 app/Actions/Fortify 目录下的 action 类：

比如要改注册逻辑，编辑 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'], // [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 验证器应用（如 Google Authenticator、Authy 等）。在 config/fortify.php 里 Features::twoFactorAuthentication() 默认就是开着的。其中 confirm 选项要求用户在启用 2FA 前先验证一次验证码；confirmPassword 要求开关 2FA 时输入密码确认。详见 Fortify 两步验证文档。

速率限制

速率限制防止暴力破解和频繁登录尝试。在 FortifyServiceProvider 里自定义：

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} 这类路由。起步套件会自动校验当前用户是否属于请求的团队，不属于就不让访问。

起步套件还为已认证用户的当前团队注册了 URL 默认值，所以 route('dashboard') 这类调用会自动带上当前团队的 slug。用户登录、注册或切换团队时，当前团队和 URL 默认值都会同步更新。

创建或重命名团队时，起步套件会阻止使用可能和路由前缀冲突的保留名称——比如 settings、login、dashboard 这些名字不能当团队名。

WorkOS AuthKit 认证

除了 Laravel 内置认证，起步套件还提供了 WorkOS AuthKit 版本，额外支持：

• 社交登录（Google、Microsoft、GitHub、Apple）
• 通行密钥（Passkey）认证
• 基于邮箱的「Magic Auth」魔术链接
• SSO 单点登录

使用 WorkOS 需要注册 WorkOS 账号，100 万月活以下免费。在 laravel new 创建应用时选 WorkOS 选项就行。

配置 WorkOS 起步套件

创建好 WorkOS 版应用后，在 .env 文件里配置这三个环境变量，值从 WorkOS 应用面板里拿：

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

另外在 WorkOS 面板里配好应用首页 URL——用户退出登录后会被跳转到这个地址。

配置 AuthKit 认证方式

建议在 WorkOS AuthKit 设置里关掉「Email + Password」认证，只保留社交登录、通行密钥、Magic Auth 和 SSO。这样你的应用就完全不用处理用户密码了。

配置 AuthKit 会话超时

建议把 WorkOS AuthKit 的会话不活动超时时间调成跟你 Laravel 应用一致，通常是两小时。

Inertia SSR

React、Svelte 和 Vue 起步套件都支持 Inertia 的服务端渲染。构建 SSR 包：

npm run build:ssr

还有个更方便的 composer dev:ssr 命令——它会先构建 SSR 包，然后同时启动 Laravel 开发服务器和 Inertia SSR 服务器，让你在本地用 SSR 测试：

composer dev:ssr

社区维护的起步套件

用 laravel new 建应用时，--using 参数可以指定任何发布在 Packagist 上的社区起步套件：

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 目录下会生成一堆文件。改 HTML 模板或 resources/views/vendor/mail/themes/default.css 样式文件就能调整邮件的外观。