從舊結構到新結構的遷移指南

前言

本指南說明如何從 Laravel 10 以前的舊應用程式結構（具備 Kernel 類別及多個服務提供者的結構）遷移到 Laravel 11 以後的 Slim Application Skeleton。

官方文件並不建議進行此遷移。

Laravel 10 的舊結構在 Laravel 11 以後仍可原樣運作。截至包含 Laravel 13 的目前版本，均無終止支援的計畫。
遷移完全屬於自願，並非強制或建議。
若未深入理解舊結構與新結構的差異，強烈建議避免進行遷移。此作業適合對框架內部熟悉的開發者。
遷移前務必備份，並確認所有測試通過。

需要遷移的情境

於下列情形下可考慮進行遷移：

為方便新加入的成員對照官方文件，希望將專案結構調整為最新的標準結構
希望與 Laravel 11 以後新建立的套件或啟動套件保持整體一致性
希望減少源自舊結構的設定檔與類別，使程式碼庫更為單純

前置條件

本指南以下列狀態為前提：

Laravel 版本升級已完成（laravel/framework ^11.0 以後）
既有測試皆能通過
已理解 Laravel 11 以後的應用程式結構（請參考Laravel 11 以後的應用程式結構）

遷移範例

以 Laravel 10 + Breeze（Blade Stack）建立的專案為例，展示保留 Breeze 但僅將應用程式結構遷移至新結構的步驟。

替換 bootstrap/app.php

舊的 bootstrap/app.php 是先建立 $app 實例再註冊 Kernel 的形式。將其替換為 Application::configure() 鏈式呼叫。舊（Laravel 10）：

<?php

$app = new Illuminate\Foundation\Application(
    $_ENV['APP_BASE_PATH'] ?? dirname(__DIR__)
);

$app->singleton(
    Illuminate\Contracts\Http\Kernel::class,
    App\Http\Kernel::class
);

$app->singleton(
    Illuminate\Contracts\Console\Kernel::class,
    App\Console\Kernel::class
);

$app->singleton(
    Illuminate\Contracts\Debug\ExceptionHandler::class,
    App\Exceptions\Handler::class
);

return $app;

新（Laravel 11 以後）：

<?php

use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Exceptions;
use Illuminate\Foundation\Configuration\Middleware;

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        commands: __DIR__.'/../routes/console.php',
        health: '/up',
    )
    ->withMiddleware(function (Middleware $middleware) {
        //
    })
    ->withExceptions(function (Exceptions $exceptions) {
        //
    })->create();

withMiddleware() 與 withExceptions() 的回呼是用來移植下一步將刪除的 Kernel 檔案中的設定。先保持為空，於後續步驟中再進行加入。

刪除 HTTP Kernel（app/Http/Kernel.php）

app/Http/Kernel.php 中定義了全域中介層、中介層群組與中介層別名。舊（app/Http/Kernel.php）：

<?php

namespace App\Http;

use Illuminate\Foundation\Http\Kernel as HttpKernel;

class Kernel extends HttpKernel
{
    protected $middleware = [
        \App\Http\Middleware\TrustProxies::class,
        \Illuminate\Http\Middleware\HandleCors::class,
        \App\Http\Middleware\PreventRequestsDuringMaintenance::class,
        \Illuminate\Foundation\Http\Middleware\ValidatePostSize::class,
        \App\Http\Middleware\TrimStrings::class,
        \Illuminate\Foundation\Http\Middleware\ConvertEmptyStringsToNull::class,
    ];

    protected $middlewareGroups = [
        'web' => [
            \App\Http\Middleware\EncryptCookies::class,
            \Illuminate\Cookie\Middleware\AddQueuedCookiesToResponse::class,
            \Illuminate\Session\Middleware\StartSession::class,
            \Illuminate\View\Middleware\ShareErrorsFromSession::class,
            \App\Http\Middleware\VerifyCsrfToken::class,
            \Illuminate\Routing\Middleware\SubstituteBindings::class,
        ],
        'api' => [
            \Illuminate\Routing\Middleware\ThrottleRequests::class.':api',
            \Illuminate\Routing\Middleware\SubstituteBindings::class,
        ],
    ];

    protected $middlewareAliases = [
        'auth' => \App\Http\Middleware\Authenticate::class,
        // ...
    ];
}

Laravel 11 中，上述中介層已作為預設值內建於框架內部。若未進行任何自訂，可直接刪除 app/Http/Kernel.php。若有自訂（新增或排除自訂中介層），請先將設定移植到 bootstrap/app.php 的 withMiddleware() 中再刪除。

->withMiddleware(function (Middleware $middleware) {
    // 加入全域中介層
    $middleware->append(\App\Http\Middleware\MyCustomMiddleware::class);

    // 將中介層加入 web 群組
    $middleware->web(append: [
        \App\Http\Middleware\HandleInertiaRequests::class,
    ]);

    // 加入中介層別名
    $middleware->alias([
        'role' => \App\Http\Middleware\CheckRole::class,
    ]);
})

移植完成後，刪除 app/Http/Kernel.php。

Laravel 11 中，TrustProxies、EncryptCookies、VerifyCsrfToken 等預設中介層類別也可從 app/Http/Middleware/ 刪除。因已內建於框架端，若不需自訂，檔案本身也不再需要。

刪除 Console Kernel（app/Console/Kernel.php）

app/Console/Kernel.php 負責排程的定義與指令的自動載入。舊（app/Console/Kernel.php）：

<?php

namespace App\Console;

use Illuminate\Console\Scheduling\Schedule;
use Illuminate\Foundation\Console\Kernel as ConsoleKernel;

class Kernel extends ConsoleKernel
{
    protected function schedule(Schedule $schedule): void
    {
        // $schedule->command('inspire')->hourly();
    }

    protected function commands(): void
    {
        $this->load(__DIR__.'/Commands');
        require base_path('routes/console.php');
    }
}

指令的自動載入在 Laravel 11 以後會自動掃描 app/Console/Commands/ 目錄，因此不再需要 $this->load() 的敘述。排程的定義改遷移至 routes/console.php 或 bootstrap/app.php 的 withSchedule()。

// routes/console.php（Laravel 11 以後）
use Illuminate\Support\Facades\Schedule;

Schedule::command('emails:send')->daily();

遷移後刪除 app/Console/Kernel.php。

請勿刪除 app/Console/ 目錄內的自訂 Artisan 指令檔。指令檔應原樣保留，僅刪除 Kernel 類別檔案。

刪除例外處理器（app/Exceptions/Handler.php）

app/Exceptions/Handler.php 負責例外回報與渲染的設定。舊（app/Exceptions/Handler.php）：

<?php

namespace App\Exceptions;

use Illuminate\Foundation\Exceptions\Handler as ExceptionHandler;
use Throwable;

class Handler extends ExceptionHandler
{
    protected $dontFlash = [
        'current_password',
        'password',
        'password_confirmation',
    ];

    public function register(): void
    {
        $this->reportable(function (Throwable $e) {
            //
        });
    }
}

若有自訂，請先將其移植到 bootstrap/app.php 的 withExceptions() 再刪除。

use Throwable;
use Illuminate\Http\Request;

->withExceptions(function (Exceptions $exceptions) {
    // 自訂例外回報
    $exceptions->report(function (Throwable $e) {
        // ...
    });

    // 自訂例外渲染
    $exceptions->render(function (\App\Exceptions\InvalidOrderException $e, Request $request) {
        return response()->view('errors.invalid-order', status: 500);
    });
})

若曾在 $dontFlash 中加入自訂項目，也可以同樣的方式移植。

->withExceptions(function (Exceptions $exceptions) {
    $exceptions->dontFlash([
        'my_sensitive_field',
    ]);
})

移植完成後，刪除 app/Exceptions/Handler.php。

刪除 RouteServiceProvider 並遷移路由註冊

app/Providers/RouteServiceProvider.php 負責路由檔案的載入與速率限制的設定。舊（app/Providers/RouteServiceProvider.php）：

<?php

namespace App\Providers;

use Illuminate\Cache\RateLimiting\Limit;
use Illuminate\Foundation\Support\Providers\RouteServiceProvider as ServiceProvider;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\RateLimiter;
use Illuminate\Support\Facades\Route;

class RouteServiceProvider extends ServiceProvider
{
    public const HOME = '/home';

    public function boot(): void
    {
        RateLimiter::for('api', function (Request $request) {
            return Limit::perMinute(60)->by($request->user()?->id ?: $request->ip());
        });

        $this->routes(function () {
            Route::middleware('api')
                ->prefix('api')
                ->group(base_path('routes/api.php'));

            Route::middleware('web')
                ->group(base_path('routes/web.php'));
        });
    }
}

將路由檔案的註冊遷移至 bootstrap/app.php 的 withRouting()。

->withRouting(
    web: __DIR__.'/../routes/web.php',
    api: __DIR__.'/../routes/api.php', // 若使用 API 路由
    commands: __DIR__.'/../routes/console.php',
    health: '/up',
)

將速率限制遷移至 AppServiceProvider::boot()。

// app/Providers/AppServiceProvider.php
use Illuminate\Cache\RateLimiting\Limit;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\RateLimiter;

public function boot(): void
{
    RateLimiter::for('api', function (Request $request) {
        return Limit::perMinute(60)->by($request->user()?->id ?: $request->ip());
    });
}

若有使用 HOME 常數的地方，可直接替換為 URL 字串，或將常數移到 AppServiceProvider。遷移後刪除 app/Providers/RouteServiceProvider.php。

整理服務提供者

Laravel 10 預設提供 5 個服務提供者。將其統合成 AppServiceProvider.php 單一檔案。要刪除的提供者（先將內容移到 AppServiceProvider 再刪除）：

檔案	遷移目的地
`app/Providers/AuthServiceProvider.php`	`AppServiceProvider::boot()` 中的 `Gate::policy()` 等
`app/Providers/BroadcastServiceProvider.php`	若使用 Broadcasting，則遷移至 `bootstrap/app.php` 的 `withBroadcasting()`
`app/Providers/EventServiceProvider.php`	`AppServiceProvider::boot()` 中的 `Event::listen()` 等
`app/Providers/RouteServiceProvider.php`	已於前一步驟處理

遷移舊（app/Providers/AuthServiceProvider.php）內容的範例：

// 舊：app/Providers/AuthServiceProvider.php
use Illuminate\Foundation\Support\Providers\AuthServiceProvider as ServiceProvider;

class AuthServiceProvider extends ServiceProvider
{
    protected $policies = [
        Post::class => PostPolicy::class,
    ];

    public function boot(): void
    {
        $this->registerPolicies();
    }
}

// 新：app/Providers/AppServiceProvider.php
// 若遵循 Laravel 標準的命名慣例將自動偵測，故不需此步驟
use Illuminate\Support\Facades\Gate;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        Gate::policy(Post::class, PostPolicy::class);
    }
}

刪除不再需要的提供者檔案後，刪除 config/app.php 中的 providers 陣列。

// config/app.php 的 providers 陣列
// 整段皆可刪除
'providers' => ServiceProvider::defaultProviders()->merge([
App\Providers\AppServiceProvider::class,
// 已刪除的提供者相關條目也一併刪除
// App\Providers\AuthServiceProvider::class, // 刪除
// App\Providers\EventServiceProvider::class, // 刪除
// App\Providers\RouteServiceProvider::class, // 刪除
])->toArray(),

接著建立 bootstrap/providers.php 以對應新結構。

<?php

// bootstrap/providers.php
return [
    App\Providers\AppServiceProvider::class,
];

若 bootstrap/providers.php 存在，Laravel 會優先讀取此檔案作為提供者清單。

更新 Controller 基底類別

Laravel 10 的 Controller 基底類別使用了 AuthorizesRequests 與 ValidatesRequests trait。Laravel 11 的新基底類別是不含這些 trait 的簡單抽象類別。舊（Laravel 10）：

<?php

namespace App\Http\Controllers;

use Illuminate\Foundation\Auth\Access\AuthorizesRequests;
use Illuminate\Foundation\Validation\ValidatesRequests;
use Illuminate\Routing\Controller as BaseController;

class Controller extends BaseController
{
    use AuthorizesRequests, ValidatesRequests;
}

新（Laravel 11 以後）：

<?php

namespace App\Http\Controllers;

abstract class Controller
{
    //
}

trait 所提供的功能替換方式如下。

舊方式（透過 trait）	新方式
`$this->validate($request, $rules)`	`$request->validate($rules)`
`$this->authorize('update', $post)`	`Gate::authorize('update', $post)`
`$this->authorizeResource(Post::class)`	Laravel 11 沒有簡易的替代方式，因此保留 `App\Http\Controllers\Controller` 為 Laravel 10 樣式

若既有的控制器有使用 trait 的方法，可以選擇修改每個控制器，或將 trait 保留在 Controller 基底類別中。並不需要一次全部變更也能運作。

若由 Breeze 或 Jetstream 產生的驗證控制器有呼叫 $this->validate() 或 $this->authorize()，變更基底類別前務必先確認運作情況。

刪除不需要的 config 檔案

config/cors.php、config/hashing.php、config/view.php 等未變更為預設的檔案可以刪除。有變更的檔案請保留。

更新 public/index.php

因新結構已變更，整份予以覆寫。

<?php

use Illuminate\Foundation\Application;
use Illuminate\Http\Request;

define('LARAVEL_START', microtime(true));

// Determine if the application is in maintenance mode...
if (file_exists($maintenance = __DIR__.'/../storage/framework/maintenance.php')) {
require $maintenance;
}

// Register the Composer autoloader...
require __DIR__.'/../vendor/autoload.php';

// Bootstrap Laravel and handle the request...
/** @var Application $app */
$app = require_once __DIR__.'/../bootstrap/app.php';

$app->handleRequest(Request::capture());

更新 artisan

artisan 檔案同樣整份覆寫。

#!/usr/bin/env php
<?php

use Illuminate\Foundation\Application;
use Symfony\Component\Console\Input\ArgvInput;

define('LARAVEL_START', microtime(true));

// Register the Composer autoloader...
require __DIR__.'/vendor/autoload.php';

// Bootstrap Laravel and handle the command...
/** @var Application $app */
$app = require_once __DIR__.'/bootstrap/app.php';

$status = $app->handleCommand(new ArgvInput);

exit($status);

更新 tests/TestCase.php

CreatesApplication trait 已不再需要，因此進行變更。 tests/CreatesApplication.php 可以直接刪除。

<?php

namespace Tests;

use Illuminate\Foundation\Testing\TestCase as BaseTestCase;

abstract class TestCase extends BaseTestCase
{
    //
}

更新 .env .env.example phpunit.xml

CACHE_DRIVER 已改為 CACHE_STORE，項目也有所增加，如有必要請進行變更。由於此區的變更牽涉到 config 檔與正式環境，請謹慎進行。並不需要勉強跟進。

運作確認

遷移完成後，依下列順序進行運作確認。

# 清除設定快取
php artisan config:clear
php artisan route:clear
php artisan cache:clear

# 確認路由是否已正確註冊
php artisan route:list

# 執行測試
php artisan test

若發生問題，請從備份還原已刪除的檔案並確認錯誤訊息。

遷移後的檔案結構

遷移後的專案會形成如下的結構（標示出從舊結構的變更點）。

app/
├── Console/
│   └── Commands/          ← 自訂指令原樣保留
│   （刪除 Kernel.php）
├── Exceptions/
│   （刪除 Handler.php）
├── Http/
│   ├── Controllers/
│   │   └── Controller.php ← 變更為單純的抽象類別
│   └── Middleware/        ← 自訂中介層原樣保留
│   （刪除 Kernel.php）
├── Models/
└── Providers/
    └── AppServiceProvider.php ← 統合成 1 個檔案
    （刪除 AuthServiceProvider.php）
    （刪除 BroadcastServiceProvider.php）
    （刪除 EventServiceProvider.php）
    （刪除 RouteServiceProvider.php）
bootstrap/
├── app.php                ← 替換為 Application::configure() 形式
└── providers.php          ← 新建
routes/
├── web.php
├── api.php                ← 僅在需要時
└── console.php            ← 排程定義也置於此

總結

遷移內容	舊位置	新位置
HTTP 中介層	`app/Http/Kernel.php`	`bootstrap/app.php` 的 `withMiddleware()`
例外處理	`app/Exceptions/Handler.php`	`bootstrap/app.php` 的 `withExceptions()`
排程定義	`app/Console/Kernel.php`	`routes/console.php`
路由註冊	`app/Providers/RouteServiceProvider.php`	`bootstrap/app.php` 的 `withRouting()`
服務提供者清單	`config/app.php` 的 `providers` 陣列	`bootstrap/providers.php`
Policy 註冊	`app/Providers/AuthServiceProvider.php`	自動註冊。或在 `AppServiceProvider::boot()` 手動註冊
事件監聽器	`app/Providers/EventServiceProvider.php`	自動註冊。或在 `AppServiceProvider::boot()` 手動註冊

AI 開發

設計模式

套件開發

應用程式結構

Laravel 13 新功能

Eloquent 深入探索

驗證擴充

認證擴充

安全性

佇列

測試

從舊結構到新結構的遷移指南

前言

需要遷移的情境

前置條件

遷移範例

遷移後的檔案結構

總結

參考連結

​前言

​需要遷移的情境

​前置條件

​遷移範例

​遷移後的檔案結構

​總結

​參考連結

前言

需要遷移的情境

前置條件

遷移範例

遷移後的檔案結構

總結

參考連結