升级 Laravel 前需检查 PHP 和框架版本兼容性，修正 composer.json；注意隐式模型绑定变严格、api 中间件组移除限流、Response::json() 已废弃等关键变更。
升级前必须检查 composer.json 的 PHP 和 Laravel 版本约束
新版 Laravel 对 PHP 版本有硬性要求，比如 Laravel 11 要求 PHP ≥ 8.2，而很多老项目还卡在 7.4 或 8.0。直接 composer update 会失败，错误信息通常是：Your requirements could not be resolved to an installable set of packages.
实操建议：
- 先运行
php -v确认当前 PHP 版本，再查对应 Laravel 版本的 官方发布说明，确认是否兼容 - 修改
composer.json中的"php"和"laravel/framework"行，例如从"^10.0"改为"^11.0"，同时把"php": "^8.0"改成"^8.2" - 别漏掉其他强依赖 Laravel 的包，比如
laravel/sanctum、laravel/breeze，它们也有主版本对齐要求，不匹配会导致Class not found或服务提供者注册失败
Route::apiResource() 的隐式模型绑定行为变了
Laravel 10 默认开启隐式模型绑定严格模式（strict binding），而旧版是宽松的。升级后常见现象：原本能访问的 /api/posts/abc（id 是字符串）突然返回 404，因为框架现在默认只接受整数 ID 匹配 Post 模型主键。
实操建议：
- 如果路由用的是
Route::apiResource('posts', PostController::class)，且控制器方法签名是show(Post $post)，就要检查Post模型的$primaryKey类型和数据库字段类型是否一致 - 临时绕过：在模型中加
public $incrementing = false;并显式声明protected $keyType = 'string'; - 更稳妥的做法是在路由定义里关闭隐式绑定，改用显式传参：
Route::get('/api/posts/{id}', [PostController::class, 'show']);，然后在方法里手动Post::findOrFail($id)
中间件组 api 默认不再包含 throttle:api
Laravel 10.3+ 把限流中间件从 api 组中移除了，升级后所有 API 接口默认失去请求频率限制，容易被刷爆。你不会看到报错，但监控会发现异常流量激增。
实操建议：
- 打开
app/Http/Kernel.php，检查$middlewareGroups['api']数组，确认是否还包含\Illuminate\Routing\Middleware\ThrottleRequests::class . ':api' - 如果没有，手动加回去；或者更推荐的方式：在具体路由上按需添加，比如
Route::middleware('throttle:60,1')->group(...) - 注意
throttle中间件的第二个参数是「分钟」，不是「秒」，写成throttle:60,60是错的，会导致每小时才限 60 次
Response::json() 已废弃，但 response()->json() 仍可用
这个改动本身不破坏运行，但如果你在测试或封装工具函数时用了 Response::json()，升级到 Laravel 11 后会触发 Deprecated: Method Illuminate\Http\Response::json() is deprecated 警告，CI 流程可能因此失败。
实操建议：
- 全局搜索项目里的
Response::json(，替换成response()->json( - 别用
Response门面去调静态方法，Laravel 的响应构造逻辑已转向实例化 + 链式调用，门面只是快捷方式，不是底层入口 - 如果封装了统一响应类，确保它内部调用的是
response()->json(...)->withHeaders(...)这类链式方法，而不是试图继承或重写Response类
API 版本升级最麻烦的从来不是代码改几行，而是那些没报错、没日志、但行为悄悄变了的地方——比如模型绑定策略、中间件默认开关、甚至队列任务的序列化方式。上线前一定用真实设备跑一遍核心路径，别只信 PHPUnit。
