跳转到主要内容

前言

Laravel 12 于 2025 年 2 月发布。本指南讲解从 Laravel 11.x 升级到 12.x 的步骤。
预计升级时间约 5 分钟。当然,破坏性变更对应用的影响会因规模和所用功能而异。

用 Laravel Shift 自动升级

也可以用 Laravel Shift 自动化升级。Shift 会自动更新应用的依赖和配置文件。

按影响面分级的变更

影响度:高

  • 依赖更新
  • Laravel installer 更新

影响度:中

  • Eloquent HasUuids trait 与 UUIDv7

影响度:低

  • Carbon 3
  • Concurrency 结果索引映射
  • 容器的类依赖解析
  • 图片校验的 SVG 排除
  • 本地文件系统 disk 的默认根路径
  • 多 schema 的数据库检查
  • 嵌套数组请求的合并

升级步骤

更新依赖

影响度:高 请更新 composer.json 中的以下依赖。
{
  "require": {
    "laravel/framework": "^12.0"
  },
  "require-dev": {
    "phpunit/phpunit": "^11.0",
    "pestphp/pest": "^3.0"
  }
}
之后执行:
composer update

更新 Laravel installer

影响度:高 如果你用 Laravel installer CLI 创建新项目,请把它升级到兼容 Laravel 12.x 和新启动套件的版本。 composer global require 安装的情况:
composer global update laravel/installer
php.new 安装的情况,按操作系统运行重装命令。
/bin/bash -c "$(curl -fsSL https://php.new/install/mac/8.4)"
如果使用 Laravel Herd 的捆绑版本,请把 Herd 本身更新到最新版本。

新启动套件

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
laravel new my-app
执行命令后会提示你选择启动套件。选完之后安装依赖、启动开发服务器即可。
cd my-app
npm install && npm run build
composer run dev
升级现有应用时不必重新引入启动套件,这个变更只针对新项目。

破坏性变更(Breaking Changes)

Eloquent

HasUuids trait 与 UUIDv7

影响度:中 HasUuids trait 现在会返回 UUID v7(有序 UUID)。想保留原先的“顺序 UUID v4”行为时,请换成 HasVersion4Uuids trait。
use Illuminate\Database\Eloquent\Concerns\HasUuids; // [tl! remove]
use Illuminate\Database\Eloquent\Concerns\HasVersion4Uuids as HasUuids; // [tl! add]
如果你之前已经在使用 HasVersion7Uuids trait,请改回 HasUuids(现在两者行为一致)。

校验

图片校验的 SVG 排除

影响度:低 image 校验规则默认不再允许 SVG。想允许 SVG 时请显式指定。
use Illuminate\Validation\Rules\File;

'photo' => 'required|image:allow_svg'

// 或
'photo' => ['required', File::image(allowSvg: true)],

存储

本地文件系统 disk 的默认根路径

影响度:低 filesystems 配置里没有显式定义 local disk 时,默认根路径从 storage/app 改为 storage/app/private 想保留旧行为,请在配置文件里显式定义 local disk。
// config/filesystems.php
'local' => [
    'driver' => 'local',
    'root' => storage_path('app'),
],

数据库

多 schema 的数据库检查

影响度:低 Schema::getTables()Schema::getViews()Schema::getTypes() 默认返回所有 schema 的结果。只想拿某个 schema 时,传入 schema 参数。
// 所有 schema 的表
$tables = Schema::getTables();

// 只要 'main' schema 的表
$tables = Schema::getTables(schema: 'main');
Schema::getTableListing() 默认返回带 schema 前缀的表名。
$tables = Schema::getTableListing();
// ['main.migrations', 'main.users', 'blog.posts']

$tables = Schema::getTableListing(schema: 'main', schemaQualified: false);
// ['migrations', 'users']

数据库构造函数签名变更

影响度:非常低 Illuminate\Database\Schema\BlueprintIlluminate\Database\Grammar 的构造函数现在要求以 Connection 实例作为第一个参数。
// Laravel <= 11.x
$grammar = new MySqlGrammar;
$grammar->setConnection($connection);

// Laravel >= 12.x
$grammar = new MySqlGrammar($connection);
以下 API 被移除或标记为废弃:
API状态
Blueprint::getPrefix()废弃
Connection::withTablePrefix()移除
Grammar::getTablePrefix() / setTablePrefix()废弃
Grammar::setConnection()移除
表前缀请直接从连接获取。
$prefix = $connection->getTablePrefix();

Concurrency

结果索引映射

影响度:低 Concurrency::run() 传关联数组时,结果会按各自的键返回。
$result = Concurrency::run([
    'task-1' => fn () => 1 + 1,
    'task-2' => fn () => 2 + 2,
]);

// ['task-1' => 2, 'task-2' => 4]

容器

类依赖解析的默认值

影响度:低 DI 容器在解析类实例时会尊重类属性的默认值。
class Example
{
    public function __construct(public ?Carbon $date = null) {}
}

$example = resolve(Example::class);

// Laravel <= 11.x: 返回一个 Carbon 实例
// Laravel >= 12.x: 返回 null

请求

嵌套数组请求的合并

影响度:低 $request->mergeIfMissing() 现在支持用点号语法合并嵌套数组数据。以前点号语法的键会被原样当作顶层键。
$request->mergeIfMissing([
    'user.last_name' => 'Otwell',
]);

路由

路由优先级

影响度:低 多个同名路由时的行为在“缓存”和“未缓存”两种模式下统一了。未缓存模式下也不再是最后注册的优先,而是最先注册的优先。

认证

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 installercomposer global update
HasUuids → UUIDv7需要时切换到 HasVersion4Uuids
image 校验排除 SVG需要 SVG 时加上 allow_svg
本地 disk 默认根变化在配置里显式指定
必须 Carbon 3检查 API 兼容性

参考资料

最后修改于 2026年7月13日