LaravelDocs（中文）

Starter Kits

Laravel Starter Kits 為使用 React、Vue 或 Livewire 前端建置應用程式提供了一個強大的起點。

Starter Kits

簡介 (Introduction)

為了讓你在建立新的 Laravel 應用程式時有一個良好的開端,我們很高興提供應用程式起始套件 (Application Starter Kits)。這些起始套件提供了建立下一個 Laravel 應用程式所需的路由、控制器和視圖,包括註冊和認證應用程式使用者所需的功能。這些起始套件使用 Laravel Fortify 來提供認證功能。

雖然你可以自由使用這些起始套件,但它們並非必需的。你可以透過簡單地安裝全新的 Laravel 來從頭開始建立自己的應用程式。無論如何,我們相信你都會建立出很棒的東西!

使用起始套件建立應用程式 (Creating an Application Using a Starter Kit)

要使用我們的起始套件之一建立新的 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 開發伺服器後,你的應用程式將可以在網頁瀏覽器中透過 http://localhost:8000 訪問。

可用的起始套件 (Available Starter Kits)

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 元件庫。

起始套件自訂 (Starter Kit Customization)

React 自訂 (React)

我們的 React 起始套件使用 Inertia 2、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 可用的佈局 (React Available Layouts)

React 起始套件包含兩種不同的主要佈局供你選擇:「側邊欄 (sidebar)」佈局和「標題 (header)」佈局。側邊欄佈局是預設的,但你可以透過修改應用程式的 resources/js/layouts/app-layout.tsx 檔案頂部匯入的佈局來切換到標題佈局:

import AppLayoutTemplate from '@/layouts/app/app-sidebar-layout';
import AppLayoutTemplate from '@/layouts/app/app-header-layout';

React 側邊欄變體 (React Sidebar Variants)

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

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

React 認證頁面佈局變體 (React Authentication Page Layout Variants)

React 起始套件中包含的認證頁面,如登入頁面和註冊頁面,也提供三種不同的佈局變體:「simple」、「card」和「split」。

要更改你的認證佈局,請修改應用程式的 resources/js/layouts/auth-layout.tsx 檔案頂部匯入的佈局:

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

Vue 自訂 (Vue)

我們的 Vue 起始套件使用 Inertia 2、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 可用的佈局 (Vue Available Layouts)

Vue 起始套件包含兩種不同的主要佈局供你選擇:「側邊欄 (sidebar)」佈局和「標題 (header)」佈局。側邊欄佈局是預設的,但你可以透過修改應用程式的 resources/js/layouts/AppLayout.vue 檔案頂部匯入的佈局來切換到標題佈局:

import AppLayout from '@/layouts/app/AppSidebarLayout.vue';
import AppLayout from '@/layouts/app/AppHeaderLayout.vue';

Vue 側邊欄變體 (Vue Sidebar Variants)

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

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

Vue 認證頁面佈局變體 (Vue Authentication Page Layout Variants)

Vue 起始套件中包含的認證頁面,如登入頁面和註冊頁面,也提供三種不同的佈局變體:「simple」、「card」和「split」。

要更改你的認證佈局,請修改應用程式的 resources/js/layouts/AuthLayout.vue 檔案頂部匯入的佈局:

import AuthLayout from '@/layouts/auth/AuthSimpleLayout.vue';
import AuthLayout from '@/layouts/auth/AuthSplitLayout.vue';

Livewire 自訂 (Livewire)

我們的 Livewire 起始套件使用 Livewire 3、Tailwind 和 Flux UI 建立。與我們所有的起始套件一樣,所有後端和前端程式碼都存在於你的應用程式中,允許完全自訂。

Livewire 和 Volt

大部分前端程式碼位於 resources/views 目錄中。你可以自由修改任何程式碼來自訂應用程式的外觀和行為:

resources/views
├── components             # 可重用的 Livewire 元件
├── flux                   # 自訂的 Flux 元件
├── livewire               # Livewire 頁面
├── partials               # 可重用的 Blade 部分
├── dashboard.blade.php    # 已認證使用者儀表板
├── welcome.blade.php      # 訪客使用者歡迎頁面

傳統 Livewire 元件 (Traditional Livewire Components)

前端程式碼位於 resources/views 目錄中,而 app/Livewire 目錄包含 Livewire 元件的相應後端邏輯。

Livewire 可用的佈局 (Livewire Available Layouts)

Livewire 起始套件包含兩種不同的主要佈局供你選擇:「側邊欄 (sidebar)」佈局和「標題 (header)」佈局。側邊欄佈局是預設的,但你可以透過修改應用程式的 resources/views/components/layouts/app.blade.php 檔案使用的佈局來切換到標題佈局。此外,你應該將 container 屬性加入到主 Flux 元件:

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

Livewire 認證頁面佈局變體 (Livewire Authentication Page Layout Variants)

Livewire 起始套件中包含的認證頁面,如登入頁面和註冊頁面,也提供三種不同的佈局變體:「simple」、「card」和「split」。

要更改你的認證佈局,請修改應用程式的 resources/views/components/layouts/auth.blade.php 檔案使用的佈局:

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

認證 (Authentication)

所有起始套件都使用 Laravel Fortify 來處理認證。Fortify 提供了登入、註冊、密碼重設、電子郵件驗證等的路由、控制器和邏輯。

Fortify 會根據你應用程式的 config/fortify.php 配置檔案中啟用的功能自動註冊以下認證路由:

MethodURI用途
GET/login顯示登入表單
POST/login處理登入請求
POST/logout登出使用者
GET/register顯示註冊表單
POST/register處理註冊請求
GET/forgot-password顯示忘記密碼表單
POST/forgot-password發送密碼重設連結
GET/reset-password/{token}顯示密碼重設表單
POST/reset-password處理密碼重設
GET/email/verify顯示電子郵件驗證通知
GET/email/verify/{id}/{hash}驗證電子郵件地址
POST/email/verification-notification重新發送驗證郵件
GET/user/confirm-password顯示密碼確認表單
POST/user/confirm-password處理密碼確認
GET/two-factor-challenge顯示雙因素認證挑戰
POST/two-factor-challenge處理雙因素認證挑戰

可以使用 php artisan route:list Artisan 命令來顯示應用程式中的所有路由。

啟用和停用功能 (Enabling and Disabling Features)

你可以在應用程式的 config/fortify.php 配置檔案中控制啟用哪些 Fortify 功能:

use Laravel\Fortify\Features;

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

如果你想停用某個功能,只需註解或從 features 陣列中移除該功能項目。例如,移除 Features::registration() 以停用公開註冊。

自訂使用者建立和密碼重設 (Customizing User Creation and Password Reset)

當使用者註冊或重設密碼時,Fortify 會呼叫位於應用程式的 app/Actions/Fortify 目錄中的 action 類別:

  • CreateNewUser.php - 建立新使用者
  • ResetUserPassword.php - 重設使用者密碼
  • PasswordValidationRules.php - 密碼驗證規則

例如,要自訂應用程式的註冊邏輯,你應該編輯 CreateNewUser action:

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'],
        'password' => $this->passwordRules(),
    ])->validate();

    return User::create([
        'name' => $input['name'],
        'email' => $input['email'],
        'phone' => $input['phone'],
        'password' => Hash::make($input['password']),
    ]);
}

雙因素認證 (Two-Factor Authentication)

起始套件包含內建的雙因素認證 (2FA),允許使用者使用任何 TOTP 相容的驗證器應用程式來保護他們的帳戶。2FA 預設透過應用程式的 config/fortify.php 配置檔案中的 Features::twoFactorAuthentication() 啟用。

confirm 選項要求使用者在 2FA 完全啟用之前驗證代碼,而 confirmPassword 選項在啟用或停用 2FA 之前需要密碼確認。有關更多詳細資訊,請參閱 Fortify 的雙因素認證文件。

速率限制 (Rate Limiting)

速率限制可防止暴力破解和重複登入嘗試使你的認證端點不堪重負。你可以在應用程式的 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());
});

WorkOS AuthKit 認證 (WorkOS AuthKit Authentication)

預設情況下,React、Vue 和 Livewire 起始套件都使用 Laravel 的內建認證系統來提供登入、註冊、密碼重設、電子郵件驗證等功能。此外,我們還提供每個起始套件的 WorkOS AuthKit 驅動變體,它提供:

  • 社交認證 (Google、Microsoft、GitHub 和 Apple)
  • Passkey 認證
  • 基於電子郵件的「Magic Auth」
  • SSO

使用 WorkOS 作為你的認證提供者需要 WorkOS 帳戶。WorkOS 為每月活躍使用者數達 100 萬的應用程式提供免費認證。

要使用 WorkOS AuthKit 作為應用程式的認證提供者,請在透過 laravel new 建立新的起始套件驅動應用程式時選擇 WorkOS 選項。

配置你的 WorkOS 起始套件 (Configuring Your WorkOS Starter Kit)

使用 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 認證方法 (Configuring AuthKit Authentication Methods)

使用 WorkOS 驅動的起始套件時,我們建議你在應用程式的 WorkOS AuthKit 配置設定中停用「電子郵件 + 密碼 (Email + Password)」認證,允許使用者僅透過社交認證提供者、passkeys、「Magic Auth」和 SSO 進行認證。這允許你的應用程式完全避免處理使用者密碼。

配置 AuthKit 工作階段逾時 (Configuring AuthKit Session Timeouts)

此外,我們建議你將 WorkOS AuthKit 工作階段不活動逾時配置為與你的 Laravel 應用程式配置的工作階段逾時閾值相符,通常是兩個小時。

Inertia SSR

React 和 Vue 起始套件與 Inertia 的伺服器端渲染功能相容。要為你的應用程式建立 Inertia SSR 相容的套件,請執行 build:ssr 命令:

npm run build:ssr

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

composer dev:ssr

社群維護的起始套件 (Community Maintained Starter Kits)

使用 Laravel 安裝器建立新 Laravel 應用程式時,你可以將 Packagist 上提供的任何社群維護的起始套件提供給 --using 標誌:

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

建立起始套件 (Creating Starter Kits)

為了確保你的起始套件可供其他人使用,你需要將其發布到 Packagist。你的起始套件應該在其 .env.example 檔案中定義其所需的環境變數,並且任何必要的安裝後命令都應該列在起始套件的 composer.json 檔案的 post-create-project-cmd 陣列中。

常見問題 (Frequently Asked Questions)

如何升級? (How do I upgrade?)

每個起始套件都為你的下一個應用程式提供了一個堅實的起點。擁有程式碼的完全所有權,你可以調整、自訂和建立完全符合你願景的應用程式。然而,不需要更新起始套件本身。

如何啟用電子郵件驗證? (How do I enable email verification?)

可以透過取消註解 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');
});

使用起始套件的 WorkOS 變體時不需要電子郵件驗證。

如何修改預設電子郵件模板? (How do I modify the default email template?)

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

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

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