前言
Laravel 12 于 2025 年 2 月发布。本指南讲解从 Laravel 11.x 升级到 12.x 的步骤。预计升级时间约 5 分钟。当然,破坏性变更对应用的影响会因规模和所用功能而异。
用 Laravel Shift 自动升级
也可以用 Laravel Shift 自动化升级。Shift 会自动更新应用的依赖和配置文件。按影响面分级的变更
影响度:高
- 依赖更新
- Laravel installer 更新
影响度:中
- Eloquent
HasUuidstrait 与 UUIDv7
影响度:低
- Carbon 3
- Concurrency 结果索引映射
- 容器的类依赖解析
- 图片校验的 SVG 排除
- 本地文件系统 disk 的默认根路径
- 多 schema 的数据库检查
- 嵌套数组请求的合并
升级步骤
更新依赖
影响度:高 请更新composer.json 中的以下依赖。
更新 Laravel installer
影响度:高 如果你用 Laravel installer CLI 创建新项目,请把它升级到兼容 Laravel 12.x 和新启动套件的版本。 用composer global require 安装的情况:
php.new 安装的情况,按操作系统运行重装命令。
- macOS
- Windows PowerShell
- Linux
新启动套件
Laravel 12 引入了取代 Breeze 和 Jetstream 的新启动套件。执行laravel new 时会以交互方式让你选择前端技术栈。
可选启动套件:
- 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
升级现有应用时不必重新引入启动套件,这个变更只针对新项目。
破坏性变更(Breaking Changes)
Eloquent
HasUuids trait 与 UUIDv7
影响度:中
HasUuids trait 现在会返回 UUID v7(有序 UUID)。想保留原先的“顺序 UUID v4”行为时,请换成 HasVersion4Uuids trait。
HasVersion7Uuids trait,请改回 HasUuids(现在两者行为一致)。
校验
图片校验的 SVG 排除
影响度:低image 校验规则默认不再允许 SVG。想允许 SVG 时请显式指定。
存储
本地文件系统 disk 的默认根路径
影响度:低filesystems 配置里没有显式定义 local disk 时,默认根路径从 storage/app 改为 storage/app/private。
想保留旧行为,请在配置文件里显式定义 local disk。
数据库
多 schema 的数据库检查
影响度:低Schema::getTables()、Schema::getViews()、Schema::getTypes() 默认返回所有 schema 的结果。只想拿某个 schema 时,传入 schema 参数。
Schema::getTableListing() 默认返回带 schema 前缀的表名。
数据库构造函数签名变更
影响度:非常低Illuminate\Database\Schema\Blueprint 与 Illuminate\Database\Grammar 的构造函数现在要求以 Connection 实例作为第一个参数。
| API | 状态 |
|---|---|
Blueprint::getPrefix() | 废弃 |
Connection::withTablePrefix() | 移除 |
Grammar::getTablePrefix() / setTablePrefix() | 废弃 |
Grammar::setConnection() | 移除 |
Concurrency
结果索引映射
影响度:低 给Concurrency::run() 传关联数组时,结果会按各自的键返回。
容器
类依赖解析的默认值
影响度:低 DI 容器在解析类实例时会尊重类属性的默认值。请求
嵌套数组请求的合并
影响度:低$request->mergeIfMissing() 现在支持用点号语法合并嵌套数组数据。以前点号语法的键会被原样当作顶层键。
路由
路由优先级
影响度:低 多个同名路由时的行为在“缓存”和“未缓存”两种模式下统一了。未缓存模式下也不再是最后注册的优先,而是最先注册的优先。认证
DatabaseTokenRepository 构造函数变更
影响度:非常低
Illuminate\Auth\Passwords\DatabaseTokenRepository 的构造函数中 $expires 参数从“分钟”改为“秒”。
Carbon 3
影响度:低 移除了对 Carbon 2.x 的支持。Laravel 12 的应用必须使用 Carbon 3.x。总结
Laravel 12 是一次相对平滑的升级。主要要点如下:| 变更点 | 影响度 | 应对 |
|---|---|---|
composer.json 依赖更新 | 高 | 改为 laravel/framework ^12.0 |
| 更新 Laravel installer | 高 | composer global update |
HasUuids → UUIDv7 | 中 | 需要时切换到 HasVersion4Uuids |
image 校验排除 SVG | 低 | 需要 SVG 时加上 allow_svg |
| 本地 disk 默认根变化 | 低 | 在配置里显式指定 |
| 必须 Carbon 3 | 低 | 检查 API 兼容性 |