Laravel 中文文档

主题

发行说明 ​

版本规范 ​

Laravel 及其官方扩展包遵循语义化版本控制。框架主版本每年发布一次（约 Q1），次版本和补丁版本可能每周发布。次版本和补丁版本绝不包含破坏性变更。

在你的应用或扩展包中引用 Laravel 框架或其组件时，始终应使用类似 ^13.0 这样的版本约束，因为 Laravel 主版本确实包含破坏性变更。但我们力求保证你能在一天或更短时间内完成主版本升级。

命名参数 ​

命名参数不在 Laravel 向后兼容性保证范围内。为了改进 Laravel 代码库，我们可能在必要时重命名函数参数。因此，在调用 Laravel 方法时使用命名参数应谨慎，并理解参数名称在未来可能会发生变化。

支持策略 ​

所有 Laravel 版本提供 18 个月的 bug 修复和 2 年的安全修复。对于其他所有库，仅最新主版本接受 bug 修复。此外，请查阅 Laravel 支持的数据库版本。

版本PHP (*)发布时间Bug 修复截止安全修复截止
108.1 - 8.32023 年 2 月 14 日2024 年 8 月 6 日2025 年 2 月 4 日
118.2 - 8.42024 年 3 月 12 日2025 年 9 月 3 日2026 年 3 月 12 日
128.2 - 8.52025 年 2 月 24 日2026 年 8 月 13 日2027 年 2 月 24 日
138.3 - 8.52026 年 3 月 17 日Q3 20272028 年 3 月 17 日
已停止维护
仅安全修复

(*) 支持的 PHP 版本

Laravel 13 ​

Laravel 13 延续了 Laravel 的年度发布节奏，专注于 AI 原生工作流、更强的默认配置以及更具表达力的开发者 API。本次发布包含原生 AI 基础设施、JSON:API resources、语义/向量搜索能力，以及队列、缓存和安全方面的持续改进。

最小破坏性变更 ​

本次发布周期的重点之一是尽量减少破坏性变更。我们致力于在全年持续交付不破坏现有应用的体验改进。

因此，Laravel 13 在升级工作量上相对较小，同时仍带来了大量新能力。大多数 Laravel 应用无需修改太多代码即可升级到 Laravel 13。

PHP 8.3 ​

Laravel 13.x 要求最低 PHP 版本为 8.3。

Laravel AI SDK ​

Laravel 13 引入了官方 Laravel AI SDK，提供统一 API，支持文本生成、工具调用 agent、embeddings、音频、图像以及向量存储集成。

借助 AI SDK，你可以构建与提供商无关的 AI 功能，同时保持一致的 Laravel 原生开发体验。

例如，一个基础 agent 可以通过单次调用完成提示：

php
use App\Ai\Agents\SalesCoach;

$response = SalesCoach::make()->prompt('Analyze this sales transcript...');

return (string) $response;

Laravel AI SDK 还支持生成图像、音频和 embeddings：

对于视觉生成场景，SDK 提供了简洁的 API，通过自然语言提示创建图像：

php
use Laravel\Ai\Image;

$image = Image::of('A donut sitting on the kitchen counter')->generate();

$rawContent = (string) $image;

对于语音体验，你可以将文本合成为自然语音，用于助手、旁白和无障碍功能：

php
use Laravel\Ai\Audio;

$audio = Audio::of('I love coding with Laravel.')->generate();

$rawContent = (string) $audio;

对于语义搜索和检索工作流，可以直接从字符串生成 embeddings：

php
use Illuminate\Support\Str;

$embeddings = Str::of('Napa Valley has great wine.')->toEmbeddings();

JSON:API Resources ​

Laravel 现已内置官方 JSON:API resources，可以方便地返回符合 JSON:API 规范的响应。

JSON:API resources 处理资源对象序列化、关联包含、稀疏字段集、链接以及符合 JSON:API 规范的响应头。

请求伪造保护 ​

为了安全起见，Laravel 的请求伪造保护 middleware 已得到增强，正式命名为 PreventRequestForgery，在保持与基于 token 的 CSRF 保护兼容性的同时，新增了基于来源（origin）的请求验证。

队列路由 ​

Laravel 13 通过 Queue::route(...) 新增了按类路由队列功能，允许你在一个中心位置为特定 job 定义默认的队列/连接路由规则：

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

扩展的 PHP Attributes ​

Laravel 13 持续扩展框架对 PHP 原生 attribute 的支持，使常见的配置和行为声明更具声明性，并与类和方法共同定位。

值得关注的新增内容包括 controller 和授权 attribute，如 #[Middleware] 和 #[Authorize]，以及面向队列 job 的控制 attribute，如 #[Tries]、#[Backoff]、#[Timeout] 和 #[FailOnTimeout]。

例如，controller middleware 和 policy 检查现在可以直接在类和方法上声明：

php
<?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)
    {
        // ...
    }
}

Eloquent、事件、通知、验证、测试和资源序列化 API 中也引入了额外的 attribute，为框架更多领域提供了一致的 attribute 优先选项。

Cache TTL 延长 ​

Laravel 现在包含 Cache::touch(...)，允许你在不检索和重新存储值的情况下延长现有缓存项的 TTL。

Laravel 13 深化了语义搜索支持，引入了原生向量查询、embedding 工作流以及相关 API，分别记录在搜索、查询构造器和 AI SDK 文档中。

这些功能使得使用 PostgreSQL + pgvector 构建 AI 驱动的搜索体验变得简单直接，包括对直接从字符串生成的 embeddings 进行相似度搜索。

例如，你可以直接通过查询构造器运行语义相似度搜索：

php
$documents = DB::table('documents')
    ->whereVectorSimilarTo('embedding', 'Best wineries in Napa Valley')
    ->limit(10)
    ->get();