> ## 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-TW/blog/upgrade-12-to-13">
  詳細列出破壞性變更清單和分步升級操作。
</Card>


## Related topics

- [部落格](/zh-TW/blog/index.md)
- [博客](/zh-CN/blog/index.md)
- [安裝](/zh-TW/installation.md)
- [Laravel Boost Custom Agent for PhpStorm with GitHub Copilot](/zh-TW/packages/laravel-boost-phpstorm-copilot.md)
- [什麼是 Laravel](/zh-TW/introduction.md)