Laravel 12.x 中文文档

简体中文

English

简体中文

English

主题

启动套件 ​

介绍 ​

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

虽然您可以使用这些启动套件，但它们并不是必需的。您可以通过简单地安装一个新的 Laravel 副本来从头开始构建自己的应用程序。无论哪种方式，我们都知道您会构建出很棒的东西！

使用启动套件创建应用程序 ​

要使用我们的启动套件之一创建新的 Laravel 应用程序，您应该首先安装 PHP 和 Laravel CLI 工具。如果您已经安装了 PHP 和 Composer，您可以通过 Composer 安装 Laravel 安装程序 CLI 工具：

shell
composer global require laravel/installer

然后，使用 Laravel 安装程序 CLI 创建一个新的 Laravel 应用程序。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 构建动态、响应式前端 UI 的强大方式。对于主要使用 Blade 模板并寻找比 React 和 Vue 等 JavaScript 驱动的 SPA 框架更简单的替代方案的团队来说，它是一个很好的选择。

Livewire 启动套件使用 Livewire、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';  
import AppLayoutTemplate from '@/layouts/app/app-header-layout';

侧边栏变体 ​

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

text
<Sidebar collapsible="icon" variant="sidebar">
<Sidebar collapsible="icon" variant="inset">

认证页面布局变体 ​

React 启动套件中包含的认证页面，如登录页面和注册页面，也提供三种不同的布局变体：“简单”、“卡片”和“分割”。

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

js
import AuthLayoutTemplate from '@/layouts/auth/auth-simple-layout';  
import AuthLayoutTemplate from '@/layouts/auth/auth-split-layout';

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';  
import AppLayout from '@/layouts/app/AppHeaderLayout.vue';

侧边栏变体 ​

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

txt
<Sidebar collapsible="icon" variant="sidebar">
<Sidebar collapsible="icon" variant="inset">

认证页面布局变体 ​

Vue 启动套件中包含的认证页面，如登录页面和注册页面，也提供三种不同的布局变体：“简单”、“卡片”和“分割”。

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

js
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 目录中。您可以自由修改任何代码以定制应用程序的外观和行为：

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

传统 Livewire 组件 ​

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

可用布局 ​

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

shell
npm run build:ssr

为了方便起见，还提供了一个 composer dev:ssr 命令。此命令将在为您的应用程序构建 SSR 兼容包后启动 Laravel 开发服务器和 Inertia SSR 服务器，允许您使用 Inertia 的服务器端渲染引擎在本地测试您的应用程序：

shell
composer dev:ssr

社区维护的入门套件 ​

在使用 Laravel 安装器创建新的 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');
});

NOTE

使用 WorkOS 变体的启动套件时不需要电子邮件验证。

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

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

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

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

版权所有 © 2024-2025 laravel.wiki