Laravel 14 功能预告

Laravel 14 是 Laravel 框架的下一个主要版本，预计将于 2027 年第一季度发布。该版本将要求最低 PHP 8.4 版本，并遵循 Laravel 的标准支持周期：提供错误修复支持至 2028 年第三季度，提供安全更新支持至 2029 年第一季度。

Laravel 团队尚未公布具体的发布日期或功能列表。以下所有信息均源自 laravel/framework 的 master 分支（即 Laravel 14 的开发所在分支），相关内容在正式发布前仍可能发生变动。

新特性

Laravel 14 的新特性将在发布后陆续添加到本文中。大多数新特性仍会包含在 Laravel 13 的每周次要版本更新中；而下文列出的特性之所以留待 Laravel 14 发布，是因为它们涉及向契约（Contract）添加方法或更改方法签名。

Route::query()

由 Vazha Aptsiauri 提交的 #60655 增加了对 HTTP QUERY 方法的路由支持。这是一种携带请求体（request body）的安全（safe）方法：

Route::query('/search', function () {
    return request()->input('filter');
});

Route::any() 涵盖了 QUERY 方法，而 CSRF 中间件将其视为读取请求，处理方式与 GET、HEAD 和 OPTIONS 相同。 Laravel 13.19 已在 HTTP 客户端中新增了 Http::query() 方法，并提供了 query() 和 queryJson() 测试辅助方法。 关于 Laravel 13，请参阅我们关于结合 Scout 搜索使用 HTTP QUERY 方法的教程。

$user->authorize() 

Will Rowe 在 #59708 中为 Authorizable 契约（Contract）和 Trait 新增了 authorize() 方法：

// Laravel 13
Gate::forUser($user)->authorize('viewAny', Post::class);
 
// Laravel 14
$user->authorize('viewAny', Post::class);

它的工作方式与 $user->can() 类似，但在检查失败时会抛出 AuthorizationException 异常。

 report() 的上下文

report() 辅助函数和异常处理器的 report() 方法接受一个可选的上下文数组（由 Caleb White 在 #60767 中添加）：

try {
    $order->charge();
} catch (Throwable $e) {
    report($e, ['order_id' => $order->id]);
}

ExceptionHandler 契约已变更为 report(Throwable $e, array $context = [])，因此重写了 report() 方法的自定义处理器需要包含这个新参数。

针对按需磁盘（On-Demand Disks）的 Storage::fake()

Storage::fake('ondemand') 会拦截 Storage::build() 的调用，从而允许你使用与命名磁盘相同的断言来测试按需磁盘 (#61378)。该 PR 被提交到了 master 分支，因为应用程序中可能已经存在名为 ondemand 的磁盘。

orWhereKey() 与 whereKey() 中的子查询

Caleb White 在 #61395 中整合了 whereKey() 和 whereKeyNot()，并新增了 orWhereKey() 和 orWhereKeyNot() 方法。随后的 PR #61496 使得这四个方法均支持接收子查询。

重大变更

队列暂停方法需优先指定队列

Laravel 13.25 引入了暂停所有队列的功能，而 Queue 门面（facade）上针对特定队列的方法此前要求将连接（connection）作为第一个参数。#61076 将连接参数移至末尾，并将其默认值设为系统默认连接：

// Laravel 13
Queue::pause('redis', 'emails');
Queue::pauseFor('redis', 'emails', 60);
 
// Laravel 14
Queue::pause('emails');
Queue::pauseFor('emails', 60);
Queue::pause('emails', 'redis');

resume() 和 isPaused() 方法同样接受队列作为第一个参数，以及可选的连接作为第二个参数。

lazy() 和 chunk() 不再修改构建器

在 Laravel 13 中，lazy() 和 chunk() 在进行分页处理时会改变查询构建器。如果随后重复使用同一个构建器，将会返回错误的结果：

$query = User::query();
 
foreach ($query->lazy(2) as $user) {
    // ...
}
 
$query->count(); // 0 in Laravel 13

Jack Bayliss 在 #61411 和 #61428 中修复了这两个方法，因此在 Laravel 14 中，count() 将返回完整的行数。

传入 ID 数组时的 findOr()

此前，当传入 ID 数组时，Builder::findOr() 从未执行其回调函数。Matthieu 提交的 #61577 修复了这一问题，使其行为与 findOrFail() 以及关联关系中的 findOr() 保持一致：

User::findOr([1, 99], fn () => 'fallback');
 
// Laravel 13: a Collection containing only user 1
// Laravel 14: 'fallback'

针对数组的 Cache::has() 和 Cache::forget()

尽管 has() 和 forget() 的文档注释（docblocks）支持传入数组已有四年之久，但此前 Cache::has(['a', 'b']) 总是返回 `true`，而 Cache::forget(['a', 'b']) 也未能真正移除这些键。Jack Bayliss 提交的 PR #61466 修复了这两个方法的问题。在 Laravel 14 中，只有当所有键都存在时，has() 才会返回 true：

Cache::put('foo', 'bar');
 
Cache::has(['foo', 'missing']);
 
// Laravel 13: true
// Laravel 14: false

向 forget() 传递数组会移除其中的所有键，并且仅当所有键均被成功移除时，它才会返回 true：

Cache::forget(['foo', 'baz']);
 
// Laravel 13: the keys remain, and the Redis store emits an
// "Array to string conversion" warning
// Laravel 14: both keys are removed

MassPrunable 现已包含软删除模型

当模型使用软删除功能时，Prunable trait 会在清理查询（prune query）中自动添加 withTrashed() 方法。此前 MassPrunable 并未包含这一行为，而 #61425 修复了这一差异，使其保持一致。以一个同时使用了这两个 trait 的模型为例：

use Illuminate\Database\Eloquent\MassPrunable;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\SoftDeletes;
 
class Post extends Model
{
    use MassPrunable, SoftDeletes;
 
    public function prunable()
    {
        return static::where('created_at', '<=', now()->subMonth());
    }
}

在 Laravel 13 中，model:prune 命令会强制删除匹配的记录（不包括已软删除的记录），而已软删除的记录则保留在数据表中。而在 Laravel 14 中，该命令会强制删除所有匹配的记录，包括已软删除的记录。

如果在支持软删除的模型上使用了 MassPrunable trait，请务必检查 prunable() 查询是否仍能选中预期的记录。若要保持 Laravel 13 的行为，请在查询中添加 withoutTrashed() 方法。

PHP 版本要求

Laravel 14 将要求最低 PHP 版本为 8.4，这高于 Laravel 13 所要求的 PHP 8.3 最低版本。在 #59104 这一变更中，Laravel 14 将最低版本提升至 PHP 8.4，这是因为 Symfony 8 要求最低 PHP 版本为 8.4。

Laravel 同样支持更高版本的 PHP。关于 PHP 8.6 的更多特性，请参阅“PHP 8.6 新特性”相关内容。

master 分支上其他可能纳入 Laravel 14 的依赖项变更包括：

• ably/ably-php 升级至使用 Ably 协议 2.0 的版本 (#60860)
• orchestra/testbench-core 升级至 ^12.0 版本
• 支持 PHPUnit 11.5、12.5 和 13 版本

支持时间表

Laravel 的支持政策规定，主版本通常在每年的第一季度发布。根据该政策，Laravel 14 将获得错误修复支持至 2028 年第三季度，并获得安全更新支持至 2029 年第一季度：

注意：官方文档尚未列出 Laravel 14，具体细节有待确定。

于 2026 年 3 月 17 日发布的 Laravel 13 将继续获得：

• Bug 修复支持至 2027 年第三季度
• 安全修复支持至 2028 年 3 月 17 日

Laravel 12 不再获得 Bug 修复支持，其安全修复支持将于 2027 年 2 月 24 日结束。