跳过 laravel 10 直升 11 不可行，必须先确保项目已在 laravel 10.x 运行且 php ≥ 8.2；否则 composer update 会卡在依赖解析或静默降级到 10.x 最后小版本，php 必须为 8.2.2 或 8.3.22（禁用 8.4.x），阿里云镜像会过滤 dev 包导致“找不到匹配包”，需切腾讯镜像或官方源，bootstrap/app.php 成唯一启动入口，中间件、路由、服务提供者注册均需手动适配，隐式绑定变严格，response::json() 已废弃，第三方包如 sanctum 必须升至 ^4.0，ramsey/uuid 被移除改用 ext-uuid。
跳过 Laravel 10 直升 11 不可行，必须先确保项目已在 Laravel 10.x 运行且 PHP ≥ 8.2；否则 composer update 会卡在依赖解析，或静默降级到 10.x 最后小版本。
PHP 和 Composer 镜像源是第一道坎
升级失败常发生在本地环境，和框架本身无关：
- PHP 必须是
8.2.2或8.3.22——8.4.x（尤其是8.4.8）会触发does not match your minimum-stability错误，因部分依赖（如fruitcake/php-cors）尚未适配其新稳定性策略 - 阿里云 Composer 镜像会过滤
-dev包和 unstable 标签，而 Laravel 11 安装时依赖的laravel/tinker ^2.10.1等包在某些时间点仅以dev-master形式存在，导致“找不到匹配包” - 临时切回官方源：
composer config -g repo.packagist composer https://packagist.org；或换腾讯镜像：composer config -g repos.packagist composer https://mirrors.tencent.com/composer/
bootstrap/app.php 成了唯一启动入口，漏写就起不来
以前分散在 app/Http/Kernel.php、RouteServiceProvider.php、config/app.php 的逻辑，现在全收口到 bootstrap/app.php。顺序错或漏掉任一环节，服务直接崩溃：
-
->withMiddleware()里必须显式注册所有中间件，例如：$middleware->web(append: [EnsureEmailIsVerified::class])；旧app/Http/Kernel.php被删后，里面的内容不会自动迁移 - 路由默认只加载
routes.php；若仍用routes/web.php+routes/api.php，得手动require并调用Route::middleware('web')->group(...) -
config/app.php中若还保留App\Providers\AppServiceProvider::class，会报Provider already registered—— Laravel 11 已自动注册标准提供者
迁移和模型绑定失效，错误不报但请求直接 404 或 500
这些变更不抛异常，上线后才暴露：
- 新建迁移中时间戳字段默认加了
->default(now())，老表在 MySQL 5.7 或 SQLite 下执行php artisan migrate会失败，报Invalid default value for 'created_at'；临时解法是改用useCurrent()或删掉该默认值 -
Route::apiResource('posts', PostController::class)的隐式模型绑定变严格：原来/api/posts/abc会进show(Post $post)，升级后直接 404；需检查Post模型的$primaryKey类型是否与数据库字段一致（比如id是BIGINT却声明为string） -
Response::json()已废弃，但response()->json()仍可用；全局搜索项目中所有Response::json调用并替换
第三方包兼容性必须人工核对
php artisan upgrade 命令只做结构迁移，不校验生态兼容性：
-
laravel/sanctum必须升级到^4.0，否则composer update会卡住或强制降级 -
laravel/scout、laravel/telescope等主流扩展也需对应升级；尤其注意ramsey/uuid在 11.x 中被移除，改用 PHP 8.2 原生ext-uuid，需确认服务器已启用该扩展 - 自定义目录（如
app/Services、app/Actions）完全被忽略，不会重命名、不会警告、也不会校验命名空间是否仍有效
最易被忽略的是中间件注册顺序和路由分组的手动补全——它们不报错，但会导致 CSRF 失效、认证跳过、API 返回 HTML 页面等“看起来正常但逻辑错乱”的问题。
