Laravel 13 发布：最低 PHP 8.3，Attributes 与 Cache::touch() 进入核心

来源：博客园 JaguarJack · Laravel 官方文档

Laravel 13 已正式发布。本次版本将 PHP 8.3 作为最低版本要求，并遵循 Laravel 标准支持周期：Bug 修复支持至 2027 年第三季度，安全更新支持至 2028 年第一季度。

这一发布周期的重点在于尽量减少破坏性变更，同时在全年持续交付不影响现有应用的改进。

PHP 8.3 成为最低版本要求

Laravel 13 放弃了对 PHP 8.2 的支持，现在要求 PHP 8.3 或更高版本。PHP 8.3 带来了类型化类常量、改进的 json_validate()、只读属性增强以及 JIT 优化。Laravel 13 同步移除了原本仅为兼容 PHP 8.2 而保留的 polyfill 和向后兼容代码，框架更精简、更快。

对 PHP Attributes 的一等支持

这是 Laravel 13 面向开发者最大的改动：框架在多个位置引入了原生 PHP Attributes 语法。

// 模型示例
#[Table('users', key: 'user_id', keyType: 'string', incrementing: false)]
#[Hidden(['password'])]
#[Fillable(['name', 'email'])]
class User extends Model {}

此前需要通过类属性配置的行为，现在可以直接用 Attribute 内联声明，覆盖模型（Models）、队列任务（Jobs）、控制台命令（Console commands），以及 15 处以上其他位置。该功能完全可选且向后兼容，现有代码无需修改。

Laravel AI SDK

Laravel 13 引入了官方出品的 Laravel AI SDK，提供统一 API，涵盖文本生成、工具调用 Agent、Embeddings、音频、图像以及向量存储集成。该 SDK 随 Laravel 13 正式从 Beta 转为稳定版，具备完整的队列支持、错误处理，以及符合 Laravel 惯例的 API 设计。

JSON:API Resources

Laravel 现在内置了官方 JSON:API Resources，可以方便地返回符合 JSON:API 规范的响应。它负责资源对象序列化、关联关系包含（relationship inclusion）、稀疏字段集（sparse fieldsets）、链接（links）以及符合规范的响应头。

Queue Routing

Laravel 13 通过 Queue::route(...) 支持按 Job 类名进行队列路由，可以在统一位置为特定 Job 定义默认的队列和连接规则：

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

语义搜索 / 向量搜索

Laravel 13 内置了原生向量查询支持、Embedding 工作流，以及跨搜索、查询构造器和 AI SDK 的相关 API。这些能力让基于 PostgreSQL + pgvector 构建 AI 驱动的搜索体验变得直接，包括针对字符串直接生成 Embedding 并进行相似度搜索。例如，可以直接通过查询构造器运行语义相似度搜索：

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

Cache::touch()

新增了 Cache::touch() 方法，可以在不读取或重新写入缓存值的情况下延长 TTL：

// 按秒延长
Cache::touch('user_session:123', 3600);

// 按 DateTime 延长
Cache::touch('analytics_data', now()->addHours(6));

// 永久延长
Cache::touch('report_cache', null);

此前延长 TTL 需要先 get 再 put，会造成不必要的网络传输。Cache::touch() 跳过了这一环节——Redis 使用单条 EXPIRE 命令，Memcached 使用 TOUCH，数据库驱动执行单条 UPDATE。该方法成功时返回 true，键不存在时返回 false。已在所有缓存驱动中实现：Array、APC、Database、DynamoDB、File、Memcached、Memoized、Null 和 Redis。该特性对滑动会话过期、活跃订阅窗口、热门仪表盘数据、API 速率限制窗口等高频延期场景尤为实用。

Reverb 数据库驱动：不依赖 Redis 的实时通信

此前，横向扩展 Laravel Reverb 需要 Redis 作为消息代理。Laravel 13 引入了数据库驱动，允许使用现有的 MySQL 或 PostgreSQL 数据库实现横向扩展，无需额外部署 Redis。

Passkey 认证

Passkey（基于 WebAuthn 的无密码认证）现已集成至 Laravel 的 Starter Kits 和 Fortify。用户可通过生物识别（Face ID、指纹）或硬件密钥完成认证，无需密码。新建的 Laravel 13 应用开箱即用，不需要第三方包。

Teams 支持回归 Starter Kits

Jetstream 曾提供团队多租户功能，但新版 Starter Kits 中缺失了这一支持。Laravel 13 将基于团队的多租户功能带回官方 Starter Kits，实现更简洁，优于 Jetstream 的旧方案。

其他改进

• MySQL DELETE…JOIN 支持 ORDER BY / LIMIT：Laravel 的 MySQL 语法编译器现在支持完整的 DELETE…JOIN 查询，包含 ORDER BY 和 LIMIT 子句。此前这两个子句会被静默忽略，开发者不得不为复杂删除操作编写原始 SQL。
• HTTP Pool 并发默认值修复：此前 Http::pool() 的并发数默认为 null，导致池中的请求实际串行执行，是一个容易忽视的陷阱。Laravel 13 将默认并发数调整为 2，确保池化请求开箱即用地并发执行。
• Symfony 7.4 和 8.0 支持：Laravel 13 支持 Symfony 7.4 和 8.0。

Laravel 13 支持时间线

Laravel 12 于 2025 年 2 月 24 日发布，将继续接受 Bug 修复至 2026 年 8 月 13 日，安全修复至 2027 年 2 月 24 日。

升级到 Laravel 13

使用 Laravel Boost（AI 辅助升级）：Laravel Boost 是 Laravel 官方出品的 MCP Server，为 AI 编程助手提供引导式升级提示。在任意 Laravel 12 项目中安装后，在 Claude Code、Cursor、OpenCode、Gemini 或 VS Code 中执行 /upgrade-laravel-13 斜杠命令，即可开始升级流程。

使用 Laravel Shift（自动化 PR）：Laravel Shift 会为你打开一个 PR，提供结构清晰的原子提交，几次点击即可完成审查。

手动升级：需在 composer.json 中更新以下依赖：

"laravel/framework": "^13.0",
"laravel/tinker": "^3.0",
"phpunit/phpunit": "^12.0",
"pestphp/pest": "^4.0"