Laravel 13 升级笔记：PHP 8.3 门槛、PreventRequestForgery 改名与 Cache::touch 驱动差异
Laravel 13 于 2026-03-17 发布，要求 PHP 8.3+（支持 8.3–8.5），bug 修复到 2027 年 Q3、安全修复到 2028 年 Q1。发布说明见 Laravel 13 Releases；官方站点与安装入口 laravel.com，AI SDK 文档 laravel.com/ai。
官方口径是尽量少破坏性变更，多数应用升级改动不大。Laravel 12（PHP 8.2–8.5）仍在支持：bug 修复到 2026-08-13，安全修复到 2027-02-24。如果项目还在 PHP 8.2，先留在 Laravel 12。
PHP 8.3 起步与支持时间线
Laravel 13 最低 PHP 8.3，覆盖 8.3、8.4、8.5。支持窗口：bug 修复到 2027 Q3，安全修复到 2028 Q1。Laravel 12 的窗口更窄，bug 修复到 2026-08-13，安全修复到 2027-02-24。升级前先确认 CI 镜像、部署环境、扩展版本都到 8.3+。
一等 PHP 属性
Laravel 13 把属性提升到一等支持，覆盖 15+ 处。控制器/授权侧可用 #[Middleware]、#[Authorize]。队列 Job 可用 #[Tries]、#[Backoff]、#[Timeout]、#[FailOnTimeout]、#[DeleteWhenMissingModels]、#[WithoutRelations]。Eloquent、事件、通知、验证、测试、资源序列化等位置也加了属性。
// 控制器/授权
#[Middleware]
#[Authorize]
// 队列 Job
#[Tries]
#[Backoff]
#[Timeout]
#[FailOnTimeout]
#[DeleteWhenMissingModels]
#[WithoutRelations]
属性形式把配置贴近声明处，减少散落在服务提供者或 $tries、$backoff 属性里的重复。具体参数按各属性签名传入，升级时检查同名的属性或方法是否与现有逻辑冲突。
PreventRequestForgery 与 Sec-Fetch-Site 的升级风险
CSRF 中间件更名为 PreventRequestForgery。现代浏览器请求会先看 Sec-Fetch-Site 头，只有拿不到同源信号时才回退到 token 校验。需要重点测三类场景：自定义 CSRF 流程、老浏览器、子域。中间件类名/别名变化后，路由、测试和自定义中间件栈里的引用都要同步。
Queue::route 按类路由
Queue::route(...) 用来集中定义某个 Job 的默认队列/连接，不必在每个 Job 类里写 $connection、$queue，也不用在分发处逐个传 onConnection、onQueue。把路由规则放在一处，Job 类保持干净。升级时检查原有队列分发逻辑是否受影响。
Cache::touch 的实现差异
Cache::touch(...) 只延长 TTL，不读取旧值再写回。旧做法是 get 后 put，为了延 TTL 白传一次值；touch 直接发驱动原生操作：
- Redis：单条
EXPIRE - Memcached：
TOUCH - database driver：单条
UPDATE
返回 true 表示成功，false 表示键不存在。所有驱动都实现了该方法：Array、APC、Database、DynamoDB、File、Memcached、Memoized、Null、Redis（PR #55954）。
Cache::touch($key, $ttl);
升级注意：如果自定义了缓存仓库或包装了 Repository，确认 touch 的转发行为；对 database driver 来说，多一条 UPDATE 而不是读写往返。
JSON:API 资源
一方 JSON:API 资源类是 Illuminate\Http\Resources\JsonApi\JsonApiResource。它处理资源对象序列化、关系 include、稀疏字段集、links 和 JSON:API 响应头。适合移动端或第三方客户端 API，避免在每个资源里手写 JSON:API 的 data、relationships、included 结构。升级时把现有 API Resource 按需迁移到该基类，注意响应头与分页、错误格式的差异。
语义/向量检索与 pgvector
Laravel 13 提供原生向量查询、embedding 工作流，以及 PostgreSQL + pgvector 的相似度搜索与 rerank。文档入口见 search、queries 和 AI SDK 页面。
Laravel AI SDK
Laravel AI SDK 是官方一方包，统一 API 覆盖文本生成、tool-calling agent、embeddings、音频、图片、向量库集成，可作为 provider-agnostic 层使用。文档：https://laravel.com/ai。
升级注意点
多数应用把 laravel/framework 升到 ^13.0，改动约在 10 分钟级别。但以下位置要重点看：自定义缓存行为（尤其包装了 Cache::touch 或 database driver）、请求伪造边界（PreventRequestForgery 与 Sec-Fetch-Site）、滚动发布中的框架兼容。先跑测试套件，再按队列、缓存、API 资源三个方向做冒烟验证。