> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Laravel 13 新功能汇总

> 解析 2026 年 3 月发布的 Laravel 13 的主要新功能与改进点。

## 简介

Laravel 13 于 2026 年 3 月 17 日发布。作为每年一度的例行大版本发布,Laravel 13 特别聚焦于 **AI 原生工作流**、**更安全的默认行为**、以及**表达力更强的开发者 API**。

破坏性变更被控制到最少,大部分应用只需少量修改即可完成升级。同时新增了 Laravel AI SDK 和语义搜索等一大批可能大幅改变现代应用开发方式的新功能。

<Info>
  Laravel 13 支持策略:Bug 修复到 2027 年 Q3,安全修复提供至 **2028 年 3 月 17 日**。
</Info>

***

## PHP 需求更新

Laravel 13 需要 **PHP 8.3 及以上**。对 PHP 8.2 的支持已经结束。

| 版本     | PHP           | 发布日期                | Bug 修复期限        | 安全修复期限              |
| ------ | ------------- | ------------------- | --------------- | ------------------- |
| 11     | 8.2 - 8.4     | 2024 年 3 月 12 日     | 2025 年 9 月 3 日  | 2026 年 3 月 12 日     |
| 12     | 8.2 - 8.5     | 2025 年 2 月 24 日     | 2026 年 8 月 13 日 | 2027 年 2 月 24 日     |
| **13** | **8.3 - 8.5** | **2026 年 3 月 17 日** | **2027 年 Q3**   | **2028 年 3 月 17 日** |

PHP 8.3 带来的主要好处包括:类型化常量、`json_validate()` 函数、`#[\Override]` 属性等可用。

***

## 主要新功能

### Laravel AI SDK

Laravel 13 的重头戏是**官方 AI SDK**。它以统一的 API 提供文本生成、工具调用智能体、嵌入、语音、图像生成以及向量存储集成。

在不绑定特定供应商的前提下构建 AI 功能,同时保留 Laravel 风格的开发体验。

**文本生成(智能体)**

```php theme={null}
use App\Ai\Agents\SalesCoach;

$response = SalesCoach::make()->prompt('请分析这段销售通话记录……');

return (string) $response;
```

**图像生成**

```php theme={null}
use Laravel\Ai\Image;

$image = Image::of('厨房台面上的甜甜圈')->generate();

$rawContent = (string) $image;
```

**语音合成**

```php theme={null}
use Laravel\Ai\Audio;

$audio = Audio::of('我很喜欢用 Laravel 写代码。')->generate();

$rawContent = (string) $audio;
```

**生成嵌入**

```php theme={null}
use Illuminate\Support\Str;

$embeddings = Str::of('Napa Valley 的葡萄酒最棒。')->toEmbeddings();
```

详情请参考 [Laravel AI SDK 文档](https://laravel.com/ai)。

***

### 语义 / 向量搜索

新增了与 AI SDK 联动的原生向量查询支持。可以直接通过 Query Builder 使用 PostgreSQL + `pgvector` 进行语义搜索。

```php theme={null}
$documents = DB::table('documents')
    ->whereVectorSimilarTo('embedding', 'Napa Valley 最好的酒庄')
    ->limit(10)
    ->get();
```

从添加嵌入列到查询,全都可以在 Laravel 生态里闭环完成。

***

### JSON:API 资源

Laravel 新增了官方的 [JSON:API](https://jsonapi.org/) 资源支持。可以轻松返回符合 JSON:API 规范的响应。

* 资源对象序列化
* 关联包含
* 稀疏字段集
* 链接
* 符合 JSON:API 规范的响应头

***

### PHP 属性的扩展

Laravel 13 把基于 PHP 属性的声明式配置扩展到了整个框架。

**应用到控制器**

```php theme={null}
<?php

namespace App\Http\Controllers;

use App\Models\Comment;
use App\Models\Post;
use Illuminate\Routing\Attributes\Controllers\Authorize;
use Illuminate\Routing\Attributes\Controllers\Middleware;

#[Middleware('auth')]
class CommentController
{
    #[Middleware('subscribed')]
    #[Authorize('create', [Comment::class, 'post'])]
    public function store(Post $post)
    {
        // ...
    }
}
```

**应用到队列作业**

```php theme={null}
use Illuminate\Queue\Attributes\Tries;
use Illuminate\Queue\Attributes\Backoff;
use Illuminate\Queue\Attributes\Timeout;
use Illuminate\Queue\Attributes\FailOnTimeout;

#[Tries(3)]
#[Backoff(60)]
#[Timeout(120)]
#[FailOnTimeout]
class ProcessPodcast implements ShouldQueue
{
    // ...
}
```

新增的主要属性:

| 属性                 | 用途             |
| ------------------ | -------------- |
| `#[Middleware]`    | 为控制器 / 方法应用中间件 |
| `#[Authorize]`     | 为控制器执行策略检查     |
| `#[Tries]`         | 队列作业的最大尝试次数    |
| `#[Backoff]`       | 队列作业的退避时间      |
| `#[Timeout]`       | 队列作业的超时时间      |
| `#[FailOnTimeout]` | 超时时是否标记作业失败    |

Eloquent、事件、通知、验证、测试、资源序列化 API 等也引入了新的属性。

***

### 队列路由

通过 `Queue::route(...)`,可以在一处集中定义特定作业的默认队列 / 连接路由规则。

```php theme={null}
use App\Jobs\ProcessPodcast;
use Illuminate\Support\Facades\Queue;

Queue::route(ProcessPodcast::class, connection: 'redis', queue: 'podcasts');
```

不再需要在 Job 类里硬编码队列名,可以把基础设施配置和代码解耦。

***

### 缓存 TTL 延长

`Cache::touch(...)` 可以在不取回并重存值的情况下延长缓存项的 TTL。

```php theme={null}
// 不改变现值,把 TTL 延长 3600 秒
Cache::touch('expensive-computation', 3600);
```

***

## 安全加固

### CSRF 保护加强(`PreventRequestForgery`)

CSRF 中间件从 `VerifyCsrfToken` 重命名为 `PreventRequestForgery`,并新增了基于 `Sec-Fetch-Site` 头的请求来源校验。

```php theme={null}
use Illuminate\Foundation\Http\Middleware\PreventRequestForgery;

// 在测试中移除该中间件
->withoutMiddleware([PreventRequestForgery::class]);
```

`VerifyCsrfToken` 会作为废弃的别名保留,但建议迁移到新类名。

### 缓存反序列化限制

`config/cache.php` 新增了 `serializable_classes` 选项,默认值为 `false`。这样即便 `APP_KEY` 泄露,也可以防御 PHP 反序列化攻击。

```php theme={null}
// config/cache.php
'serializable_classes' => [
    App\Data\CachedDashboardStats::class,
    App\Support\CachedPricingSnapshot::class,
],
```

如果你在缓存中存储了 PHP 对象,需要将对应的类显式加入允许列表。

***

## 启动套件变化

Laravel 12 中焕新的启动套件(React/Vue/Livewire 基础)在 Laravel 13 中依然可用。

配合 Laravel 13 的发布节奏,**Inertia v3** 也一同发布。主要变化:

* 更简单的 layout props
* 支持 Vite 8
* 新增 `withApp` 回调
* 新的 Blade 组件

如果你在使用 Inertia v3,可以一并考虑升级。

***

## 其他改进

### AI 辅助升级(Laravel Boost)

[Laravel Boost](https://github.com/laravel/boost) 是官方的 MCP 服务器。它可以与 Claude Code、Cursor、OpenCode、Gemini、VS Code 等 AI 编辑器联动,通过 `/upgrade-laravel-v13` 斜杠命令实现半自动升级。

```shell theme={null}
composer require laravel/boost:^2.0 --dev
```

### 契约新增

以下契约新增了方法:

| 契约                                 | 新增方法                                                                        |
| ---------------------------------- | --------------------------------------------------------------------------- |
| `Bus\Dispatcher`                   | `dispatchAfterResponse`                                                     |
| `Routing\ResponseFactory`          | `eventStream`(SSE 支持)                                                       |
| `Auth\MustVerifyEmail`             | `markEmailAsUnverified`                                                     |
| `Queue\Queue`                      | `pendingSize`、`delayedSize`、`reservedSize`、`creationTimeOfOldestPendingJob` |
| `Cache\Store` / `Cache\Repository` | `touch`                                                                     |

***

## 总结

Laravel 13 是一次“破坏性变更少,新功能多”的发布。升级工作量小,但特别是 **AI SDK** 和 **语义搜索** 有潜力改变现代应用的开发方式。

当你准备好把已有应用从 Laravel 12 升级到 13 时,详细步骤请参考下面这份指南。

<Card title="Laravel 12 升级到 13 指南" icon="arrow-up-right" href="/zh/blog/upgrade-12-to-13">
  详细列出破坏性变更清单和分步升级操作。
</Card>


## Related topics

- [Laravel 12 升级到 13 指南](/zh/blog/upgrade-12-to-13.md)
- [Laravel Pennant](/zh/pennant.md)
- [2026 年 3 月 Laravel 更新](/zh/blog/changelog/202603.md)
- [laravel/symfony-on-cloud — 在 Laravel Cloud 上运行 Symfony 应用](/zh/blog/symfony-on-cloud-introduction.md)
- [开始使用 - VOICEVOX for Laravel](/zh/packages/laravel-voicevox/getting-started.md)