用途:该技能用于实现 Laravel 13 变更或将 Laravel 12 升级到 13,强调基于已安装的包版本与项目既有约定,而非套用新功能。适用对象是已安装或明确要求 Laravel 13 的项目。
主要能力与用法:采用仓库优先流程,先阅读 AGENTS.md、CLAUDE.md 与 docs/ 等说明,检查 composer.json、composer.lock、package.json、bootstrap/app.php、bootstrap/providers.php、路由、配置和测试,并用 php artisan about 或 composer show 确认依赖。识别受支持的命令路径(宿主 PHP、Sail、Docker Compose 或仓库封装),并保持一致。确认应用形态:纯 API 还是全栈,Blade、Livewire 或 Inertia,前端框架及版本,认证、测试、队列、缓存、搜索与数据库驱动。版本敏感行为优先查 Laravel Boost 的 search-docs,否则参考 Laravel 13.x 或所装包官方文档。
基线要求:Laravel 13 需要 PHP 8.3 或更高,并遵守仓库及部署环境声明的平台范围;通过 bootstrap/app.php 配置路由、中间件与异常处理,通过 bootstrap/providers.php 注册提供者;routes/web.php 与 routes/console.php 视为新应用默认,routes/api.php 与 routes/channels.php 可选,不假设存在。升级应用保留既有结构。谨慎使用命名参数,因其参数名不在 Laravel 向后兼容承诺内。
HTTP 与领域设计:控制器与路由闭包保持轻薄,复用既有 action、service、job、model 或领域层;重复或复杂校验与授权使用 Form Request;用策略、门禁或既有授权层执行授权,校验不等于授权;优先 Eloquent 模型与关系,必要时用查询构造器或绑定原生表达式,不拼接不可信 SQL;预防 N+1,按需选择列,API 资源中用 whenLoaded,大数据集分页、游标或分块;多写不变量放在事务中,队列副作用保证重试安全,需要已提交数据时在提交后派发;使用 change() 修改列时必须重述要保留的修饰符,并尽量做可回滚迁移。破坏性操作如 migrate:fresh、db:wipe、大范围删除与不可逆删除需要覆盖目标与数据影响的授权,已有许可可复用,仅编辑代码不构成授权。
API 与前端:仅在项目暴露无状态 API 时使用 routes/api.php,仅当变更要求时才用 install:api;遵循既有响应封装、错误格式、分页与版本约定,默认使用标准 API Resources,仅当契约要求 JSON:API 时才用 Laravel 13 JSON:API Resources。从已装包与配置识别 Sanctum、Passport、会话认证、WorkOS AuthKit 或自定义认证并保留其守卫与令牌语义。纯 API 工作不应依赖 Vite、Tailwind 与 Node。前端需从仓库发现页面、组件与布局路径,不假设 resources/js/Pages;Inertia 按其已安装大版本支持的 API 使用,官方起始套件用 Inertia 3 支持 React、Vue 与 Svelte,但既有应用可能是其他兼容版本;使用 Inertia 链接、表单、访问、部分重载、延迟数据与 SSR 必须被已装适配器与本地模式支持,并覆盖加载、空、校验与错误状态。Wayfinder 仅在已安装时使用;Livewire 遵循已装版本与组件风格,Flux UI 仅在使用时使用;Tailwind CSS 4 保留其 CSS-first 配置、令牌、组件库、响应式规则与暗色策略,不迁移可用的 Tailwind 3。
Laravel 13 新特性:包括一方 AI 原语、JSON:API 资源、语义与向量搜索以及更强的请求伪造防护,均应视为可选设计选择,涉及包、提供者、数据库、安全、成本与运维影响;使用或从 12 升级前先读 references/laravel-13-features-and-upgrade.md。
测试与验证:按仓库保留 Pest 或 PHPUnit,Laravel 13 两者都支持,不要强制转换;跨框架边界行为用功能测试,隔离逻辑用单元测试,必要时加回归测试;用 php artisan help make:test 确认生成器参数,升级后仅在依赖兼容性验证通过后预期 Pest 4 或 PHPUnit 12;运行最小相关测试目标,使用仓库封装与测试数据库,绝不指向生产;对受影响面运行格式化、静态分析、前端 lint、类型检查、构建与浏览器或 E2E 检查,遵循更广测试套件的审批要求,并报告实际运行的检查、结果与未运行的检查。
Boost 使用:依赖 Boost 前先读取应用信息;版本敏感行为先用简短主题查询 search-docs,让 Boost 按已装包版本过滤文档;发现已安装 Boost 服务器暴露的工具,而不假设版本间名称一致;数据库检查保持只读,可执行代码工具限定在本地或测试环境,未经明确授权不得用 Tinker 或数据库工具改动生产数据。
项目完整性:优先复用既有依赖、组件、工厂、策略、资源与约定;凭据放在环境配置中,不在日志、夹具、前端包或代理输出中暴露密钥;行为、安装、公共 API 或运维流程变化时更新持久文档;最终交付区分框架事实、建议与仓库特定约定。限制:技能本身未提供具体价格、平台或效果信息;不要因技能列出包就安装、升级或替换包,须先确认任务需求与兼容性。