前言
Laravel 12 於 2025 年 2 月發佈。本指南說明從 Laravel 11.x 升級到 12.x 的步驟。升級預估所需時間約為 5 分鐘。不過破壞性變更對應用程式的影響會因規模與使用的功能而異。
使用 Laravel Shift 自動化升級
也可以使用 Laravel Shift 自動化升級作業。Shift 會自動更新應用程式的相依套件與設定檔。依影響程度分類的變更
影響程度:高
- 更新依賴套件
- 更新 Laravel installer
影響程度:中
- Eloquent
HasUuidstrait 與 UUIDv7
影響程度:低
- Carbon 3
- Concurrency 的結果 index 映射
- Container 的類別依賴解析
- image validation 排除 SVG
- 本機檔案系統磁碟的預設 root 路徑
- multi-schema 的資料庫檢查
- nested array request 的合併
升級步驟
更新依賴套件
影響程度:高 請更新composer.json 中以下依賴。
更新 Laravel installer
影響程度:高 若使用 Laravel installer CLI 建立新的 Laravel 應用程式,請更新為支援 Laravel 12.x 與新的 starter kit 的版本。 若以composer global require 安裝時:
php.new 安裝,請依作業系統執行重新安裝的指令。
- macOS
- Windows PowerShell
- Linux
新 starter kit
Laravel 12 引入了取代原本 Breeze 或 Jetstream 的新 starter kit。執行laravel new 時可用互動方式選擇前端 stack。
可用的 starter kit:
- React — Inertia 2、React 19、TypeScript、Tailwind 4、shadcn/ui
- Vue — Inertia 2、Vue Composition API、TypeScript、Tailwind 4、shadcn-vue
- Svelte — Inertia 2、Svelte 5、TypeScript、Tailwind 4、shadcn-svelte
- Livewire — Livewire、Tailwind 4、Flux UI
升級既有的應用程式並不需要重新導入 starter kit。這是針對新專案的變更。
破壞性變更 (Breaking Changes)
Eloquent
HasUuids trait 與 UUIDv7
影響程度:中
HasUuids trait 已改為回傳 UUID v7(有序 UUID)。若想保留之前有序 UUID v4 的行為,請切換到 HasVersion4Uuids trait。
HasVersion7Uuids trait,請改為 HasUuids trait(行為相同)。
驗證
image validation 排除 SVG
影響程度:低image validation rule 預設不再允許 SVG。若要允許 SVG,請明確指定。
儲存
本機檔案系統磁碟的預設 root 路徑
影響程度:低 若沒有在filesystems 設定中明確定義 local disk,預設的 root 路徑已從 storage/app 改為 storage/app/private。
若要維持之前的行為,請在設定檔明確定義 local disk。
資料庫
multi-schema 的資料庫檢查
影響程度:低Schema::getTables()、Schema::getViews()、Schema::getTypes() 預設會回傳所有 schema 的結果。若要指定特定 schema,請傳入 schema 引數。
Schema::getTableListing() 預設會回傳附 schema 前綴的資料表名稱。
資料庫 constructor 簽章變更
影響程度:非常低Illuminate\Database\Schema\Blueprint 與 Illuminate\Database\Grammar 的 constructor 已改為要求以 Connection instance 作為第一個引數。
資料表前綴請直接從 connection 取得。
Concurrency
結果 index 映射
影響程度:低 傳給Concurrency::run() 的關聯陣列,結果會依對應的 key 回傳。
Container
類別依賴解析的預設值
影響程度:低 DI Container 在解析類別 instance 時,會尊重類別屬性的預設值。Request
巢狀陣列 request 的合併
影響程度:低$request->mergeIfMissing() 現在可用點記號合併巢狀陣列資料。之前點記號的 key 會被直接建立為最上層 key。
路由
路由的優先順序
影響程度:低 有多個同名路由時的行為,在快取有與無下都已統一。無快取的路由中,最先註冊(而非最後)的路由會優先。認證
DatabaseTokenRepository constructor 的變更
影響程度:非常低
Illuminate\Auth\Passwords\DatabaseTokenRepository 的 constructor 中 $expires 參數已從以分為單位改為以秒為單位。