Laravel 中文文档

主题

入门套件 ​

简介 ​

为了让您在构建新的 Laravel 应用程序时抢占先机，我们欣然提供 应用程序入门套件。这些套件为您打造下一款 Laravel 杰作提供了卓越的起点，包含了注册和认证应用程序用户所需的路由、控制器和视图。

尽管我们诚挚邀请您使用这些入门套件，但它们并非强制要求。您完全可以从零开始，仅通过安装一个全新的 Laravel 来锻造您自己的应用程序。无论您选择何种方式，我们坚信您的创作将无比辉煌！

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

若要使用我们的一个入门套件创建新的 Laravel 应用程序，您需首先 安装 PHP 和 Laravel CLI 工具。若您的系统中已安装 PHP 和 Composer，您可通过 Composer 获取 Laravel 安装器 CLI 工具：

shell
composer global require laravel/installer

随后，通过 Laravel 安装器 CLI 创建一个新的 Laravel 应用程序。安装器将询问您偏好的入门套件：

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 组件库。

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 构建动态、反应式前端界面的强大方式。对于主要使用 Blade 模板并寻求比 React 和 Vue 等 JavaScript 驱动的 SPA 框架更简单替代方案的团队而言，它是理想选择。

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

入门套件定制 ​

React ​

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

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

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

若要添加额外的 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 入门套件包含两种主要布局供您选择：侧边栏布局和头部布局。默认使用侧边栏布局，但您可通过修改应用程序 resources/js/layouts/app-layout.tsx 文件顶部的导入布局切换到头部布局：

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

侧边栏变体 ​

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

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

认证页面布局变体 ​

React 入门套件中的认证页面（如登录和注册页面）也提供三种布局变体：“简单”、“卡片”和“分割”。

要更改认证布局，请修改应用程序 resources/js/layouts/auth-layout.tsx 文件顶部导入的布局：

js
import AuthLayoutTemplate from '@/layouts/auth/auth-simple-layout' // [tl! remove]
import AuthLayoutTemplate from '@/layouts/auth/auth-split-layout' // [tl! add]

Vue ​

我们的 Vue 入门套件采用 Inertia 2、Vue 3 Composition API、Tailwind 和 shadcn-vue 构建。与所有入门套件一样，后端和前端代码全部存在于您的应用程序中，允许全面定制。

前端代码主要位于 resources/js 目录中。您可自由调整任何代码以定制应用程序的外观和行为：

text
resources/js/
├── components/    # 可复用的 Vue 组件
├── composables/   # Vue 可组合函数 / 钩子
├── layouts/       # 应用程序布局
├── lib/           # 工具函数和配置
├── pages/         # 页面组件
└── types/         # TypeScript 定义

若要添加额外的 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 入门套件包含两种主要布局供您选择：侧边栏布局和头部布局。默认使用侧边栏布局，但您可通过修改应用程序 resources/js/layouts/AppLayout.vue 文件顶部的导入布局切换到头部布局：

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

侧边栏变体 ​

侧边栏布局包括三种不同变体：默认侧边栏变体、“内嵌”变体和“浮动”变体。您可通过修改 resources/js/components/AppSidebar.vue 组件选择您青睐的变体：

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

认证页面布局变体 ​

Vue 入门套件中的认证页面（如登录和注册页面）也提供三种布局变体：“简单”、“卡片”和“分割”。

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

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

Livewire ​

我们的 Livewire 入门套件采用 Livewire 3、Laravel Volt、Tailwind 和 Flux UI 构建。与所有入门套件一样，后端和前端代码全部存在于您的应用程序中，允许彻底的定制。

前端代码主要位于 resources/views 目录中。您可自由调整任何代码以定制应用程序的外观和行为：

text
resources/views
├── components            # 可复用的 Livewire 组件
├── flux                  # 定制的 Flux 组件
├── livewire              # Livewire 页面
├── partials              # 可复用的 Blade 片段
├── dashboard.blade.php   # 认证用户仪表板
├── welcome.blade.php     # 访客欢迎页面

可用的布局 ​

Livewire 入门套件包含两种主要布局供您选择：侧边栏布局和头部布局。默认使用侧边栏布局，但您可通过修改应用程序 resources/views/components/layouts/app.blade.php 文件使用的布局切换到头部布局，并为主 Flux 组件添加 container 属性：

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

认证页面布局变体 ​

Livewire 入门套件中的认证页面（如登录和注册页面）也提供三种布局变体：“简单”、“卡片”和“分割”。

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

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

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

ini
WORKOS_CLIENT_ID=您的客户端ID
WORKOS_API_KEY=您的API密钥
WORKOS_REDIRECT_URL="${APP_URL}/authenticate"

配置 AuthKit 认证方法 ​

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

配置 AuthKit 会话超时 ​

此外，我们建议您将 WorkOS AuthKit 会话非活动超时配置为与 Laravel 应用程序的会话超时阈值相匹配，通常为两小时。

常见问题解答 ​

如何升级？ ​

每个入门套件为您下一款应用程序提供了坚实的基础。拥有代码的完全所有权，您可以调整、定制并按您的设想构建应用程序。然而，无需更新入门套件本身。

如何启用电子邮件验证？ ​

可通过在 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');
});

注意：使用 WorkOS 变体的入门套件时无需电子邮件验证。

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

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

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

这将在 resources/views/vendor/mail 中生成多个文件。您可以调整这些文件以及 resources/views/vendor/mail/themes/default.css 文件，以更改默认电子邮件模板的外观。