Laravel老版本升级必须逐主版本迭代（如8→9→10→11），不可跨版本直连；需先确认当前版本与PHP兼容性，同步更新laravel/*依赖、修正废弃API及结构变更，并手动验证关键配置与业务链路。
laravel/framework 版本号”就能跑起来的事。跳过中间主版本（如 8 → 11）必然失败，因为废弃的类、签名变更、目录结构重写、PHP 语法要求提升等层层叠加，没中间过渡层根本无法解析。
怎么确认自己卡在哪个“断代区”
先别改任何文件，直接运行：php artisan --version 看输出；再打开 composer.json 查 "laravel/framework" 的实际约束值（比如 "^8.75"）。这两处不一致时，以 composer.json 为准——Artisan 命令本身可能已因依赖撕裂而不可靠。
对照官方 Supported Versions 表格：截至 2026 年 4 月，只有 10.x 和 11.x 是受支持的主版本，8.x 和 9.x 已停止安全更新。如果你当前是 8.x，路径只有一条：8 → 9 → 10 → 11，缺一不可。
- 查 PHP 版本是否兜得住：运行
php -v；Laravel 11 强制要求^8.2，8.1 或更低会直接让composer update报错退出，不是警告 - 用
composer outdated "laravel/*"扫一遍生态包滞后情况，例如laravel/sanctum在 11.x 下必须是^4.0，^3.2会触发Target class does not exist - 第三方包兼容性不能靠猜：去 Packagist 查对应包的
require字段，或看其 GitHub README 是否明确写了 “Supports Laravel 11”
composer.json 改哪几行才不算埋雷
只改 "laravel/framework": "^11.0" 是最常见翻车点。Laravel 主版本升级本质是整套内核+生态的协同演进，漏掉任一关键包都会导致 artisan 启动失败、测试崩、甚至路由全 404。
必须同步显式声明以下几项：
-
"php": "^8.2"—— 不写这一行，Composer 可能沿用旧约束，装出一堆降级依赖 -
"spatie/laravel-ignition": "^2.4"（替代已废弃的facade/ignition） "nunomaduro/collision": "^8.1"-
"laravel/sanctum": "^4.0"（若项目用了 Sanctum） -
"phpunit/phpunit": "^10.5"—— 注意不是^11.0，Laravel 11 官方尚未适配 PHPUnit 11
执行命令时加 --with-all-dependencies：composer update laravel/framework --with-all-dependencies，避免 illuminate/support 等子包被锁在旧版，造成容器绑定失败。
升级后哪些文件不手动检查就必挂
Laravel 11 彻底重构了应用骨架，php artisan upgrade 只能覆盖 70% 结构迁移，剩下 30% 必须人工核对，否则上线后静默失效。
-
config/app.php：删掉所有已废弃的'providers'数组项，比如Illuminate\Pagination\PaginationServiceProvider::class，残留会导致启动报错 -
app/Providers/AppServiceProvider.php：检查register()和boot()方法里是否还调用$this->app->bind(...)这类旧式绑定，Laravel 11 推荐用服务容器自动解析 -
app/Http/Kernel.php：默认移除了web组里的EncryptCookies、VerifyCsrfToken等中间件，如果你的登录、表单提交依赖它们，得手动加回去 -
database/factories：模型工厂必须从类定义改为闭包，class UserFactory extends Factory写法会直接报Class "UserFactory" not found
缓存清理不能只清一次：php artisan config:clear && php artisan route:clear && php artisan view:clear && php artisan cache:clear —— 某些配置项（如 APP_KEY 格式）在 11.x 中校验变严，旧缓存可能让加密解密失败。
为什么升级完本地能跑，上预发就 500
最常见的隐形坑是环境差异和静默覆盖：
-
.env文件被升级脚本误改：Laravel 11 默认启用更强的APP_KEY校验，旧 key 若是 32 位以外长度，会触发RuntimeException: The only supported ciphers are AES-128-CBC and AES-256-CBC - 自定义 Artisan 命令未重注册：Laravel 11 的轻量内核不再自动扫描
app/Console/Commands，需确认每个命令类是否仍被app/Providers/ConsoleServiceProvider.php显式加载 - 队列任务中用了
public $property：Laravel 10 起已强制改为protected $property，否则序列化失败，任务卡死不报错 - 日志驱动配置错位：Laravel 11 的
config/logging.php结构与 9.x 差异极大，直接复制旧配置会导致logfacade 解析为空
真正麻烦的从来不是命令执行失败，而是某些功能看似正常，却在特定请求路径下返回空响应、丢失 session 或队列无限重试——这些必须靠真实业务链路验证，不能只靠 PHPUnit 跑通就认为 OK。
