laravel-upgrade-v13

用途

本技能用于将 Laravel 12 应用升级到 Laravel 13.0，提供从 Laravel 12.x（最新 12.69）到 Laravel 13（13.0 于 2026 年 3 月 17 日发布，当前稳定版 13.33）的集中化升级路径，覆盖 Composer 依赖升级、破坏性变更修复、Attributes 迁移与验证四个阶段。

代理工作流

资料标明升级前必须并行启动三个代理，每个代理单独调用并指定名称：fuse-ai-pilot:explore-codebase 用于审计现有 Laravel 12 模式（$fillable、$tries、VerifyCsrfToken 引用等）；fuse-ai-pilot:research-expert 通过 Context7（/laravel/docs/13.x/upgrade）核对 Laravel 13 最新文档；fuse-laravel:laravel-expert 负责应用 Laravel 13 最佳实践。升级完成后运行 fuse-ai-pilot:sniper 进行校验。

升级阶段

升级前审计：检测代码库中的 Laravel 12 模式，约 30 分钟。
Composer 升级：更新 Laravel、PHPUnit、Pest、Tinker，约 5 分钟。
破坏性变更修复：应用 Laravel 13 强制变更，约 1 至 3 小时。
Attributes 迁移：将 Eloquent 与队列属性迁移为 Attributes（可选），约 2 至 4 小时。
验证：测试通过、CI 正常，约 30 分钟。

多数项目总耗时不足一天。目录结构分为 1-composer、2-breaking-fixes、3-attributes、4-validation 四个部分，分别对应依赖升级、强制变更、可选重构和测试校验。

关键规则

PHP 最低版本为 8.3，升级 Composer 前需先移除 PHP 8.2 支持。
官方升级目标为 PHPUnit 12 与 Pest 4，应先升级开发依赖以便尽早发现测试失败；Pest 5 与 PHPUnit 13 可在之后使用，但要求 PHP 8.4 及以上。
VerifyCsrfToken 重命名为 PreventRequestForgery，需在 bootstrap/app.php 和别名中重命名中间件引用。示例代码：

// bootstrap/app.php
->withMiddleware(function (Middleware $middleware) {
    $middleware->preventRequestForgery(except: [
        'stripe/*',
        'webhook/*',
    ]);
})

缓存前缀存在破坏性变更：默认由下划线改为连字符。若无法接受缓存失效，需设置 CACHE_PREFIX、REDIS_PREFIX、SESSION_COOKIE 以保持旧行为：

# .env — 保持 L12 下划线行为
CACHE_PREFIX=laravel_cache_
REDIS_PREFIX=laravel_database_
SESSION_COOKIE=laravel_session

同一 Eloquent 或队列类不得混用 Attributes 与属性，每个模型或任务只保留一种来源。
若使用 Beanstalkd，不要忘记 pda/pheanstalk 的 ^8.0（或 ^7.0）版本。
不要在模型的 boot() 或 trait 的 boot*() 中保留嵌套模型实例化（new static()），Laravel 13 中会抛出 LogicException。

使用方式

Quick Reference 提供的 Composer 升级命令为：

composer require laravel/framework:^13.0 laravel/tinker:^3.0
composer require --dev phpunit/phpunit:^12.0 pestphp/pest:^4.0
composer update

完整命令序列需参见 composer-upgrade.md。各主题对应参考文件包括：composer-upgrade.md（依赖升级命令）、breaking-changes.md（全部 12 项变更）、attributes-migration.md（Eloquent 与队列类现代化）、laravel-boost-mcp.md（自动化 /upgrade-laravel-v13）、checklist.md（分步验证清单）。

适用场景

适用于从 Laravel 12 升级到 Laravel 13 的项目团队，尤其是需要系统性处理破坏性变更、缓存前缀兼容和 Attributes 迁移的场景。资料建议在功能分支（如 feat/laravel-13-upgrade）上执行升级，使用 Laravel Boost MCP 的 /upgrade-laravel-v13 进行引导式自动化，并在生产前于预发布环境使用真实缓存与队列 worker 测试。

最佳实践与限制

应先将 PHPUnit 与 Pest 升级，使测试失败在重构前暴露；将属性与 Attributes 迁移作为独立 PR，不与破坏性修复捆绑；不要在 main 分支直接升级 Composer 而不经 CI 验证；有生产热缓存时不可跳过缓存前缀环境变量设置。资料未提供该技能的具体安装命令、收费信息或平台限制等细节。