入門套件
簡介
為了讓您在構建新的 Laravel 應用程式時有一個良好的開端,我們很高興提供 應用程式入門套件。這些入門套件為您構建下一個 Laravel 應用程式提供了一個起點,幷包含了註冊和驗證應用程式使用者所需的路由、控制器和檢視。這些入門套件使用 Laravel Fortify 來提供身份驗證。
雖然歡迎您使用這些入門套件,但它們並非強制要求。您可以隨時透過安裝全新的 Laravel 來從零開始構建自己的應用程式。無論哪種方式,我們相信您都會創造出色的作品!
使用入門套件建立應用程式
要使用我們的入門套件建立新的 Laravel 應用程式,您應該首先 安裝 PHP 和 Laravel CLI 工具。如果您已經安裝了 PHP 和 Composer,可以透過 Composer 安裝 Laravel 安裝程式 CLI 工具:
1composer global require laravel/installer
然後,使用 Laravel 安裝程式 CLI 建立一個新的 Laravel 應用程式。Laravel 安裝程式會提示您選擇首選的入門套件:
1laravel new my-app
建立 Laravel 應用程式後,您只需透過 NPM 安裝其前端依賴項並啟動 Laravel 開發伺服器即可:
1cd my-app2npm install && npm run build3composer run dev
一旦啟動了 Laravel 開發伺服器,您就可以在瀏覽器中透過 https://: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 2、React 19、Tailwind 4 和 shadcn/ui 構建。與我們所有的入門套件一樣,所有的後端和前端程式碼都存在於您的應用程式中,以便進行全面自定義。
大部分前端程式碼位於 resources/js 目錄中。您可以隨意修改任何程式碼以自定義應用程式的外觀和行為。
1resources/js/2├── components/ # Reusable React components3├── hooks/ # React hooks4├── layouts/ # Application layouts5├── lib/ # Utility functions and configuration6├── pages/ # Page components7└── types/ # TypeScript definitions
要釋出額外的 shadcn 元件,請先 找到您要釋出的元件。然後,使用 npx 釋出該元件:
1npx shadcn@latest add switch
在此示例中,該命令會將 Switch 元件釋出到 resources/js/components/ui/switch.tsx。元件釋出後,您就可以在任何頁面中使用它了。
1import { Switch } from "@/components/ui/switch" 2 3const MyPage = () => { 4 return ( 5 <div> 6 <Switch /> 7 </div> 8 ); 9};10 11export default MyPage;
可用佈局
React 入門套件包含兩種主要佈局供您選擇:側邊欄(sidebar)佈局和頁首(header)佈局。側邊欄佈局是預設設定,但您可以透過修改應用程式 resources/js/layouts/app-layout.tsx 檔案頂部匯入的佈局來切換到頁首佈局。
1import AppLayoutTemplate from '@/layouts/app/app-sidebar-layout'; 2import AppLayoutTemplate from '@/layouts/app/app-header-layout';
側邊欄變體
側邊欄佈局包括三種不同的變體:預設側邊欄變體、"inset" 變體和 "floating" 變體。您可以透過修改 resources/js/components/app-sidebar.tsx 元件來選擇最喜歡的變體。
1<Sidebar collapsible="icon" variant="sidebar"> 2<Sidebar collapsible="icon" variant="inset">
身份驗證頁面佈局變體
React 入門套件附帶的身份驗證頁面(例如登入頁面和註冊頁面)也提供三種不同的佈局變體:"simple"、"card" 和 "split"。
要更改您的身份驗證佈局,請修改應用程式 resources/js/layouts/auth-layout.tsx 檔案頂部匯入的佈局。
1import AuthLayoutTemplate from '@/layouts/auth/auth-simple-layout'; 2import AuthLayoutTemplate from '@/layouts/auth/auth-split-layout';
Svelte
我們的 Svelte 入門套件採用 Inertia 2、Svelte 5、Tailwind 和 shadcn-svelte 構建。與我們所有的入門套件一樣,所有的後端和前端程式碼都存在於您的應用程式中,以便進行全面自定義。
大部分前端程式碼位於 resources/js 目錄中。您可以隨意修改任何程式碼以自定義應用程式的外觀和行為。
1resources/js/2├── components/ # Reusable Svelte components3├── layouts/ # Application layouts4├── lib/ # Utility functions and configuration and Svelte rune modules5├── pages/ # Page components6└── types/ # TypeScript definitions
要釋出額外的 shadcn-svelte 元件,請先 找到您要釋出的元件。然後,使用 npx 釋出該元件:
1npx shadcn-svelte@latest add switch
在此示例中,該命令會將 Switch 元件釋出到 resources/js/components/ui/switch/switch.svelte。元件釋出後,您就可以在任何頁面中使用它了。
1<script lang="ts">2 import { Switch } from '@/components/ui/switch'3</script>4 5<div>6 <Switch />7</div>
可用佈局
Svelte 入門套件包含兩種主要佈局供您選擇:側邊欄(sidebar)佈局和頁首(header)佈局。側邊欄佈局是預設設定,但您可以透過修改應用程式 resources/js/layouts/AppLayout.svelte 檔案頂部匯入的佈局來切換到頁首佈局。
1import AppLayout from '@/layouts/app/AppSidebarLayout.svelte'; 2import AppLayout from '@/layouts/app/AppHeaderLayout.svelte';
側邊欄變體
側邊欄佈局包括三種不同的變體:預設側邊欄變體、"inset" 變體和 "floating" 變體。您可以透過修改 resources/js/components/AppSidebar.svelte 元件來選擇最喜歡的變體。
1<Sidebar collapsible="icon" variant="sidebar"> 2<Sidebar collapsible="icon" variant="inset">
身份驗證頁面佈局變體
Svelte 入門套件附帶的身份驗證頁面(例如登入頁面和註冊頁面)也提供三種不同的佈局變體:"simple"、"card" 和 "split"。
要更改您的身份驗證佈局,請修改應用程式 resources/js/layouts/AuthLayout.svelte 檔案頂部匯入的佈局。
1import AuthLayout from '@/layouts/auth/AuthSimpleLayout.svelte'; 2import AuthLayout from '@/layouts/auth/AuthSplitLayout.svelte';
Vue
我們的 Vue 入門套件採用 Inertia 2、Vue 3 Composition API、Tailwind 和 shadcn-vue 構建。與我們所有的入門套件一樣,所有的後端和前端程式碼都存在於您的應用程式中,以便進行全面自定義。
大部分前端程式碼位於 resources/js 目錄中。您可以隨意修改任何程式碼以自定義應用程式的外觀和行為。
1resources/js/2├── components/ # Reusable Vue components3├── composables/ # Vue composables / hooks4├── layouts/ # Application layouts5├── lib/ # Utility functions and configuration6├── pages/ # Page components7└── types/ # TypeScript definitions
要釋出額外的 shadcn-vue 元件,請先 找到您要釋出的元件。然後,使用 npx 釋出該元件:
1npx shadcn-vue@latest add switch
在此示例中,該命令會將 Switch 元件釋出到 resources/js/components/ui/Switch.vue。元件釋出後,您就可以在任何頁面中使用它了。
1<script setup lang="ts">2import { Switch } from '@/components/ui/switch'3</script>4 5<template>6 <div>7 <Switch />8 </div>9</template>
可用佈局
Vue 入門套件包含兩種主要佈局供您選擇:側邊欄(sidebar)佈局和頁首(header)佈局。側邊欄佈局是預設設定,但您可以透過修改應用程式 resources/js/layouts/AppLayout.vue 檔案頂部匯入的佈局來切換到頁首佈局。
1import AppLayout from '@/layouts/app/AppSidebarLayout.vue'; 2import AppLayout from '@/layouts/app/AppHeaderLayout.vue';
側邊欄變體
側邊欄佈局包括三種不同的變體:預設側邊欄變體、"inset" 變體和 "floating" 變體。您可以透過修改 resources/js/components/AppSidebar.vue 元件來選擇最喜歡的變體。
1<Sidebar collapsible="icon" variant="sidebar"> 2<Sidebar collapsible="icon" variant="inset">
身份驗證頁面佈局變體
Vue 入門套件附帶的身份驗證頁面(例如登入頁面和註冊頁面)也提供三種不同的佈局變體:"simple"、"card" 和 "split"。
要更改您的身份驗證佈局,請修改應用程式 resources/js/layouts/AuthLayout.vue 檔案頂部匯入的佈局。
1import AuthLayout from '@/layouts/auth/AuthSimpleLayout.vue'; 2import AuthLayout from '@/layouts/auth/AuthSplitLayout.vue';
Livewire
我們的 Livewire 入門套件採用 Livewire 4、Tailwind 和 Flux UI 構建。與我們所有的入門套件一樣,所有的後端和前端程式碼都存在於您的應用程式中,以便進行全面自定義。
大部分前端程式碼位於 resources/views 目錄中。您可以隨意修改任何程式碼以自定義應用程式的外觀和行為。
1resources/views2├── components # Reusable components3├── flux # Customized Flux components4├── layouts # Application layouts5├── pages # Livewire pages6├── partials # Reusable Blade partials7├── dashboard.blade.php # Authenticated user dashboard8├── welcome.blade.php # Guest user welcome page
可用佈局
Livewire 入門套件包含兩種主要佈局供您選擇:側邊欄(sidebar)佈局和頁首(header)佈局。側邊欄佈局是預設設定,但您可以透過修改應用程式 resources/views/layouts/app.blade.php 檔案使用的佈局來切換到頁首佈局。此外,您還應該在主要的 Flux 元件中新增 container 屬性。
1<x-layouts::app.header>2 <flux:main container>3 {{ $slot }}4 </flux:main>5</x-layouts::app.header>
身份驗證頁面佈局變體
Livewire 入門套件附帶的身份驗證頁面(例如登入頁面和註冊頁面)也提供三種不同的佈局變體:"simple"、"card" 和 "split"。
要更改您的身份驗證佈局,請修改應用程式 resources/views/layouts/auth.blade.php 檔案使用的佈局。
1<x-layouts::auth.split>2 {{ $slot }}3</x-layouts::auth.split>
認證
所有的入門套件都使用 Laravel Fortify 來處理身份驗證。Fortify 為登入、註冊、密碼重置、電子郵件驗證等提供路由、控制器和邏輯。
Fortify 會根據您應用程式 config/fortify.php 配置檔案中啟用的功能,自動註冊以下身份驗證路由:
| 路由 | 方法 | 描述 |
|---|---|---|
/login |
GET |
顯示登入表單 |
/login |
POST |
驗證使用者身份 |
/logout |
POST |
使用者登出 |
/register |
GET |
顯示登錄檔單 |
/register |
POST |
建立新使用者 |
/forgot-password |
GET |
顯示密碼重置請求表單 |
/forgot-password |
POST |
傳送密碼重置連結 |
/reset-password/{token} |
GET |
顯示密碼重置表單 |
/reset-password |
POST |
更新密碼 |
/email/verify |
GET |
顯示電子郵件驗證通知 |
/email/verify/{id}/{hash} |
GET |
驗證電子郵件地址 |
/email/verification-notification |
POST |
重新發送驗證郵件 |
/user/confirm-password |
GET |
顯示密碼確認表單 |
/user/confirm-password |
POST |
確認密碼 |
/two-factor-challenge |
GET |
顯示 2FA 驗證挑戰表單 |
/two-factor-challenge |
POST |
驗證 2FA 程式碼 |
可以使用 php artisan route:list Artisan 命令檢視應用程式中的所有路由。
啟用和停用功能
您可以在應用程式的 config/fortify.php 配置檔案中控制啟用哪些 Fortify 功能。
1use Laravel\Fortify\Features; 2 3'features' => [ 4 Features::registration(), 5 Features::resetPasswords(), 6 Features::emailVerification(), 7 Features::twoFactorAuthentication([ 8 'confirm' => true, 9 'confirmPassword' => true,10 ]),11],
要停用某項功能,只需註釋掉或從 features 陣列中刪除該功能條目即可。例如,刪除 Features::registration() 以停用公共註冊。
當使用 React、Svelte 或 Vue 入門套件時,您還需要在前端程式碼中刪除所有對已停用功能路由的引用。例如,如果您停用了電子郵件驗證,則應刪除 React、Svelte 或 Vue 元件中對 verification 路由的匯入和引用。這是必要的,因為這些入門套件使用 Wayfinder 進行型別安全的路由,它會在構建時生成路由定義。如果您引用了不再存在的路由,您的應用程式將無法構建。
自定義使用者建立與密碼重置
當用戶註冊或重置密碼時,Fortify 會呼叫位於應用程式 app/Actions/Fortify 目錄中的操作類:
| 檔案 | 描述 |
|---|---|
CreateNewUser.php |
驗證並建立新使用者 |
ResetUserPassword.php |
驗證並更新使用者密碼 |
PasswordValidationRules.php |
定義密碼驗證規則 |
例如,要自定義應用程式的註冊邏輯,您應該編輯 CreateNewUser 操作。
1public function create(array $input): User 2{ 3 Validator::make($input, [ 4 'name' => ['required', 'string', 'max:255'], 5 'email' => ['required', 'email', 'max:255', 'unique:users'], 6 'phone' => ['required', 'string', 'max:20'], 7 'password' => $this->passwordRules(), 8 ])->validate(); 9 10 return User::create([11 'name' => $input['name'],12 'email' => $input['email'],13 'phone' => $input['phone'], 14 'password' => Hash::make($input['password']),15 ]);16}
雙重身份驗證
入門套件包含內建的雙重身份驗證 (2FA),允許使用者使用任何相容 TOTP 的身份驗證器應用程式保護其帳戶。2FA 預設透過應用程式 config/fortify.php 配置檔案中的 Features::twoFactorAuthentication() 啟用。
confirm 選項要求使用者在完全啟用 2FA 之前驗證程式碼,而 confirmPassword 要求在啟用或停用 2FA 之前確認密碼。有關更多詳細資訊,請參閱 Fortify 的雙重身份驗證文件。
速率限制
速率限制(Rate limiting)可以防止暴力破解和重複的登入嘗試使您的身份驗證端點不堪重負。您可以在應用程式的 FortifyServiceProvider 中自定義 Fortify 的速率限制行為。
1use Illuminate\Support\Facades\RateLimiter;2use Illuminate\Cache\RateLimiting\Limit;3 4RateLimiter::for('login', function ($request) {5 return Limit::perMinute(5)->by($request->email.$request->ip());6});
WorkOS AuthKit 身份驗證
預設情況下,React、Svelte、Vue 和 Livewire 入門套件都利用 Laravel 的內建身份驗證系統來提供登入、註冊、密碼重置、電子郵件驗證等功能。此外,我們還為每個入門套件提供了一個由 WorkOS AuthKit 驅動的變體,它提供:
- 社交身份驗證(Google、Microsoft、GitHub 和 Apple)
- 通行金鑰(Passkey)身份驗證
- 基於電子郵件的“魔法登入”(Magic Auth)
- SSO
使用 WorkOS 作為您的身份驗證提供商 需要一個 WorkOS 帳戶。WorkOS 為每月活躍使用者數不超過 100 萬的應用程式提供免費的身份驗證服務。
要使用 WorkOS AuthKit 作為您的應用程式身份驗證提供商,請在透過 laravel new 建立新的入門套件驅動的應用程式時選擇 WorkOS 選項。
配置您的 WorkOS 入門套件
在使用 WorkOS 驅動的入門套件建立新應用程式後,您應該在應用程式的 .env 檔案中設定 WORKOS_CLIENT_ID、WORKOS_API_KEY 和 WORKOS_REDIRECT_URL 環境變數。這些變數應與 WorkOS 儀表板為您應用程式提供的值匹配。
1WORKOS_CLIENT_ID=your-client-id2WORKOS_API_KEY=your-api-key3WORKOS_REDIRECT_URL="${APP_URL}/authenticate"
此外,您還應該在 WorkOS 儀表板中配置應用程式主頁 URL。此 URL 是使用者從您的應用程式登出後將被重定向到的地址。
配置 AuthKit 身份驗證方法
當使用 WorkOS 驅動的入門套件時,我們建議您在應用程式的 WorkOS AuthKit 配置設定中停用“電子郵件 + 密碼”身份驗證,僅允許使用者透過社交身份驗證提供商、通行金鑰、“魔法登入”和 SSO 進行身份驗證。這使您的應用程式能夠完全避免處理使用者密碼。
配置 AuthKit 會話超時
此外,我們建議您配置 WorkOS AuthKit 會話不活動超時,以匹配您的 Laravel 應用程式配置的會話超時閾值(通常為兩小時)。
Inertia SSR
React、Svelte 和 Vue 入門套件與 Inertia 的 伺服器端渲染 (SSR) 功能相容。要為您的應用程式構建 Inertia SSR 相容的包,請執行 build:ssr 命令:
1npm run build:ssr
為了方便起見,還提供了一個 composer dev:ssr 命令。該命令將在為您的應用程式構建 SSR 相容包後啟動 Laravel 開發伺服器和 Inertia SSR 伺服器,允許您使用 Inertia 的伺服器端渲染引擎在本地測試您的應用程式。
1composer dev:ssr
社群維護的入門套件
當使用 Laravel 安裝程式建立新的 Laravel 應用程式時,您可以將 Packagist 上提供的任何社群維護的入門套件傳遞給 --using 標誌。
1laravel new my-app --using=example/starter-kit
建立入門套件
為了確保您的入門套件可供他人使用,您需要將其釋出到 Packagist。您的入門套件應在其 .env.example 檔案中定義所需的環境變數,並且任何必要的安裝後命令都應列在入門套件 composer.json 檔案的 post-create-project-cmd 陣列中。
常見問題解答
我該如何升級?
每個入門套件都為您下一個應用程式提供了一個堅實的起點。擁有程式碼的完全所有權,您可以按照自己的設想調整、自定義和構建您的應用程式。但是,無需更新入門套件本身。
我該如何啟用電子郵件驗證?
可以透過取消註釋 App/Models/User.php 模型中的 MustVerifyEmail 匯入並確保模型實現了 MustVerifyEmail 介面來新增電子郵件驗證。
1<?php 2 3namespace App\Models; 4 5use Illuminate\Contracts\Auth\MustVerifyEmail; 6// ... 7 8class User extends Authenticatable implements MustVerifyEmail 9{10 // ...11}
註冊後,使用者將收到一封驗證郵件。要限制對某些路由的訪問,直到使用者的電子郵件地址經過驗證,請將 verified 中介軟體新增到這些路由中。
1Route::middleware(['auth', 'verified'])->group(function () {2 Route::get('dashboard', function () {3 return Inertia::render('dashboard');4 })->name('dashboard');5});
使用 WorkOS 變體的入門套件時,不需要電子郵件驗證。
我該如何修改預設的電子郵件模板?
您可能希望自定義預設的電子郵件模板,以使其更符合您應用程式的品牌形象。要修改此模板,您應該使用以下命令將郵件檢視釋出到您的應用程式中:
1php artisan vendor:publish --tag=laravel-mail
這將會在 resources/views/vendor/mail 中生成幾個檔案。您可以修改這些檔案中的任何一個,以及 resources/views/vendor/mail/themes/default.css 檔案,以更改預設電子郵件模板的外觀和樣式。