跳轉至內容

入門套件

簡介

為了讓您在構建新的 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-app
2npm install && npm run build
3composer 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 components
3├── hooks/ # React hooks
4├── layouts/ # Application layouts
5├── lib/ # Utility functions and configuration
6├── pages/ # Page components
7└── 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 components
3├── layouts/ # Application layouts
4├── lib/ # Utility functions and configuration and Svelte rune modules
5├── pages/ # Page components
6└── 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 components
3├── composables/ # Vue composables / hooks
4├── layouts/ # Application layouts
5├── lib/ # Utility functions and configuration
6├── pages/ # Page components
7└── 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/views
2├── components # Reusable components
3├── flux # Customized Flux components
4├── layouts # Application layouts
5├── pages # Livewire pages
6├── partials # Reusable Blade partials
7├── dashboard.blade.php # Authenticated user dashboard
8├── 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() 以停用公共註冊。

當使用 ReactSvelteVue 入門套件時,您還需要在前端程式碼中刪除所有對已停用功能路由的引用。例如,如果您停用了電子郵件驗證,則應刪除 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_IDWORKOS_API_KEYWORKOS_REDIRECT_URL 環境變數。這些變數應與 WorkOS 儀表板為您應用程式提供的值匹配。

1WORKOS_CLIENT_ID=your-client-id
2WORKOS_API_KEY=your-api-key
3WORKOS_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 檔案,以更改預設電子郵件模板的外觀和樣式。