Laravel 11 升级需满足 PHP 8.2+、逐版本升级（9→10→11）、同步更新核心依赖与第三方包兼容版本，并手动处理目录结构、命名空间、工厂语法及隐式绑定等变更。

直接升级到 Laravel 11 不是改个 laravel/framework 版本号就能跑起来的事——PHP 8.2 是硬门槛，跳过 10.x 会卡死在 Target class does not exist，php artisan upgrade 只能搬走 70% 的结构，剩下必须手动对。

确认当前版本和升级路径是否合法

别信 php artisan --version 输出就代表真实状态：它可能因依赖撕裂而不可靠。先看 composer.json 里 "laravel/framework" 的实际约束，再对照官网 Supported Versions 表格。截至 2026 年 5 月，只有 10.x 和 11.x 受支持；如果你是 9.x 或更早，必须走 9 → 10 → 11，不能跳。

• 运行 php -v，低于 8.2 就别碰 composer update，先升 PHP
• 用 composer outdated "laravel/*" 扫一遍生态包，比如 laravel/sanctum 在 11.x 下必须是 ^4.0，^3.2 会触发类找不到错误
• 查第三方包是否明确声明支持 Laravel 11，例如 spatie/laravel-backup v8 不兼容，得等 v9 或临时 fork

composer.json 必须同步改的几行

只改 "laravel/framework": "^11.0" 是最常见翻车点。Laravel 主版本升级本质是整套内核+生态协同演进，漏掉任一关键包都会导致 artisan 启动失败或路由全 404。

• 显式写入 "php": "^8.2"，否则 Composer 可能沿用旧约束，装出降级依赖
• "nunomaduro/collision": "^8.1"、"spatie/laravel-ignition": "^2.4"、"laravel/sanctum": "^4.0"（若用到）必须对齐
• "phpunit/phpunit": "^10.5" —— 注意不是 ^11.0，Laravel 11 官方尚未适配 PHPUnit 11
• 执行命令时加 --with-all-dependencies：composer update laravel/framework --with-all-dependencies，避免 illuminate/support 被锁在旧版

php artisan upgrade 之后必须人工核对的文件

php artisan upgrade（需先 composer require laravel/upgrade --dev）能重写 app/Providers/HttpKernel.php、清理废弃的 $middlewareGroups 键，但它不碰这些：

Laravel Cloud

Laravel Cloud（cloud.laravel.com）。此技能用于处理所有 Laravel Cloud 请求，包括搜索和读取数据。只要任务涉及 Laravel Cloud，即使用此技能。

下载

• config/app.php 中残留的 'providers' => [App\Providers\AppServiceProvider::class] —— Laravel 11 推荐用全路径，且部分提供者已被自动注册，重复声明报 Provider already registered
• app/Kernel.php 里 $middlewareGroups['api'] 已移除 \Illuminate\Routing\Middleware\ThrottleRequests::class . ':api'，API 默认不再限流，得手动加回去或按需绑定
• database/factories 下模型工厂语法已从类定义变为闭包，旧写法 class UserFactory extends Factory 会直接报 Class "UserFactory" not found
• 搜索项目中所有 str()、array_* 辅助函数调用，替换为 Str:: 或 Arr:: 命名空间调用

隐式绑定、中间件和浮点数类型这些静默变更

它们不报错，但上线后行为突变，监控难捕获。

• Route::apiResource('posts', PostController::class) 的隐式绑定现在默认严格模式：传字符串 ID（如 /api/posts/abc）会直接 404，除非模型显式设 $incrementing = false 和 $keyType = 'string'
• Response::json() 已废弃，但 response()->json() 仍可用；注意 response()->json($data, 200, [], JSON_UNESCAPED_UNICODE) 中第三个参数（headers）位置没变，但底层序列化逻辑已切到 JsonResponse 新实现
• Laravel 11 对浮点数列类型做了语义收紧：SQLite 用户需确保数据库版本 ≥ 3.35.0，否则 decimal 列迁移可能静默截断小数位

最容易被忽略的是：Laravel 11 默认删掉了 app/Http/Controllers、app/Http/Middleware 这些目录，但 php artisan make:controller 仍会往旧路径写——你得手动改 composer.json 的 autoload 部分，或统一迁移到 app/Controllers 并调整命名空间，否则新生成的控制器根本不会被自动加载。