入門套件

• 簡介
• 使用入門套件建立應用程式
• 可用的入門套件
  • React
  • Svelte
  • Vue
  • Livewire
• 入門套件自訂
  • React
  • Svelte
  • Vue
  • Livewire
• 身份驗證
  • 啟用和禁用功能
  • 自訂使用者建立和密碼重設
  • 雙因素身份驗證
  • 速率限制
• 團隊
• WorkOS AuthKit 身份驗證
• Inertia SSR
• 社群維護的入門套件
• 常見問題

簡介

為了給您一個建立新 Laravel 應用程式的良好開頭，我們很高興提供應用程式入門套件。這些入門套件為您建立下一個 Laravel 應用程式提供了一個良好的開頭，並包含註冊和驗證應用程式使用者所需的路由、控制器和視圖。入門套件使用 Laravel Fortify 來提供身份驗證。

雖然歡迎使用這些入門套件，但它們並非必需。您可以透過簡單地安裝 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 元件庫。

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 目錄中。您可以自由修改任何程式碼來自訂應用程式的外觀和行為：

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'; // [tl! remove]
import AppLayoutTemplate from '@/layouts/app/app-header-layout'; // [tl! add]

側邊欄變體

側邊欄佈局包含三種不同的變體：預設側邊欄變體、「內嵌」變體和「浮動」變體。您可以透過修改 resources/js/components/app-sidebar.tsx 元件來選擇您最喜歡的變體：

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

身份驗證頁面佈局變體

React 入門套件包含的身份驗證頁面（如登入頁面和註冊頁面）也提供三種不同的佈局變體：「簡單」、「卡片」和「分割」。

要更改您的身份驗證佈局，請修改應用程式 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 元件，首先找到您要發佈的元件。然後，使用 npx 發佈元件：

npx shadcn-svelte@latest add switch

在此範例中，命令將 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]

側邊欄變體

側邊欄佈局包含三種不同的變體：預設側邊欄變體、「內嵌」變體和「浮動」變體。您可以透過修改 resources/js/components/AppSidebar.svelte 元件來選擇您最喜歡的變體：

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

身份驗證頁面佈局變體

Svelte 入門套件包含的身份驗證頁面（如登入頁面和註冊頁面）也提供三種不同的佈局變體：「簡單」、「卡片」和「分割」。

要更改您的身份驗證佈局，請修改應用程式 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 元件，首先找到您要發佈的元件。然後，使用 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 入門套件包含兩種不同的主要佈局供您選擇：「側邊欄」佈局和「頁首」佈局。側邊欄佈局是預設的，但您可以透過修改應用程式 resources/js/layouts/AppLayout.vue 檔案頂部導入的佈局來切換到頁首佈局：

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

側邊欄變體

側邊欄佈局包含三種不同的變體：預設側邊欄變體、「內嵌」變體和「浮動」變體。您可以透過修改 resources/js/components/AppSidebar.vue 元件來選擇您最喜歡的變體：

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

身份驗證頁面佈局變體

Vue 入門套件包含的身份驗證頁面（如登入頁面和註冊頁面）也提供三種不同的佈局變體：「簡單」、「卡片」和「分割」。

要更改您的身份驗證佈局，請修改應用程式 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 入門套件包含的身份驗證頁面（如登入頁面和註冊頁面）也提供三種不同的佈局變體：「簡單」、「卡片」和「分割」。

要更改您的身份驗證佈局，請修改應用程式 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 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() 以禁用公共註冊。

使用 React、Svelte 或 Vue 入門套件時，您還需要從前端程式碼中移除對已禁用功能路由的任何引用。例如，如果您禁用電子郵件驗證，您應該從 React、Svelte 或 Vue 元件中移除對 verification 路由的導入和引用。這是必要的，因為這些入門套件使用 Wayfinder 進行類型安全的路由，它在建立時生成路由定義。如果您引用了不再存在的路由，您的應用程式將無法建立。

自訂使用者建立和密碼重設

當使用者註冊或重設密碼時，Fortify 會調用位於應用程式 app/Actions/Fortify 目錄中的動作類別：

例如，要自訂應用程式的註冊邏輯，您應該編輯 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 相容的身份驗證器應用程式來保護其帳戶。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());
});

團隊

React、Svelte、Vue 和 Livewire 入門套件也可以在啟用團隊支援的情況下生成。當啟用團隊功能時，每個使用者屬於一個或多個團隊並有一個當前團隊。在註冊期間，新使用者會自動獲得一個個人團隊。入門套件還包括團隊管理畫面，用於建立團隊、在團隊之間切換、邀請成員和更新團隊詳情。

當路由作用域設定為當前團隊時，當前團隊的 slug 包含在 URL 中。例如，儀表板路由變為 /{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 驅動版本，提供：

使用 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 配置設定中禁用「電子郵件 + 密碼」身份驗證，僅允許使用者透過社交身份驗證供應商、通行證、「Magic Auth」和 SSO 進行身份驗證。這使您的應用程式可以完全避免處理使用者密碼。

配置 AuthKit Session 逾時

此外，我們建議您將 WorkOS AuthKit Session 閒置逾時設定為與 Laravel 應用程式配置的 Session 逾時閾值匹配，通常為兩小時。

Inertia SSR

React、Svelte 和 Vue 入門套件與 Inertia 的伺服器端渲染功能相容。要為您的應用程式建立 Inertia SSR 相容套件，請執行 build:ssr 命令：

npm run build:ssr

為了方便起見，還提供了 composer dev:ssr 命令。此命令將在為您的應用程式建立 SSR 相容套件後啟動 Laravel 開發伺服器和 Inertia SSR 伺服器，允許您使用 Inertia 的伺服器端渲染引擎在本機測試您的應用程式：

composer dev:ssr

社群維護的入門套件

使用 Laravel 安裝器建立新的 Laravel 應用程式時，您可以向 --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');
});

[!NOTE] 使用入門套件的 WorkOS 版本時不需要電子郵件驗證。

如何修改預設電子郵件模板？

您可能想要自訂預設電子郵件模板以更好地與應用程式的品牌保持一致。要修改此模板，您應該使用以下命令將電子郵件視圖發佈到您的應用程式：

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

這將在 resources/views/vendor/mail 中生成幾個檔案。您可以修改這些檔案中的任何一個以及 resources/views/vendor/mail/themes/default.css 檔案來更改預設電子郵件模板的外觀和外觀。