升级 Laravel 最常卡在 PHP 版本不达标：它不直接报错，而是在 composer install、artisan 或页面访问时突发 Fatal error、Parse error 或静默 500；需严格按四步排查——查真实 PHP 版本（含 Docker/Valet 环境）、核对 Laravel 版本与官方 PHP 要求矩阵、同步更新 composer.json 中 "php" 及扩展约束、禁用 --ignore-platform-reqs 等危险绕过操作。
升级 Laravel 时最常卡住的地方，不是代码改写，而是 PHP 版本不达标——它不会直接报“PHP 版本太低”，而是在 composer install、php artisan 或页面访问时突然崩溃，比如 Fatal error: Uncaught TypeError、Parse error: unexpected '?'，甚至静默返回 500 错误。核心问题在于：Laravel 每个大版本都锁定了 PHP 最低支持线，跨线运行必然出错。
第一步：确认当前环境真实 PHP 版本
别信 IDE 或面板显示的版本，要查命令行实际执行环境：
- 运行
php -v—— 注意输出的主版本号（如PHP 7.4.33或PHP 8.1.26） - 如果用 Docker/Valet/Sail，进容器或服务内部再执行一次
php -v，主机环境 ≠ 运行环境 - Web 页面报错时，可在
public/index.php顶部临时加一行：die(phpversion());，看实际加载的是哪个 PHP
第二步：查清项目 Laravel 版本和对应 PHP 要求
打开 composer.json，找 "laravel/framework" 行；若不确定，运行：
-
grep '"laravel/framework"' composer.json（Linux/macOS） - 或
php artisan --version（若 artisan 还能跑）
对照官方兼容矩阵（截至 2026 年主流版本）：
立即学习“PHP免费学习笔记（深入）”；
- Laravel 5.5–5.8 → 要求 PHP ≥ 7.1.3，最高兼容到 7.4.x（不支持 PHP 8.0+）
- Laravel 6.x → PHP 7.2–7.4（不支持 PHP 8.0+）
- Laravel 7.x → PHP 7.2.5–8.0（不支持 PHP 8.1+）
- Laravel 8.x → PHP 7.3–8.1（8.75+ 才完整支持 8.1）
- Laravel 9+ → PHP 8.0.2+（强制要求 PHP 8.0+）
- Laravel 10/11 → PHP 8.1+，且需
ext-pdo、ext-json等扩展显式启用
第三步：检查 composer.json 的 PHP 声明是否匹配
很多人只改了 Laravel 版本，却忘了同步更新 composer.json 里的 "php" 字段。Composer 安装时会按这个字段校验，但若设为 "^7.4" 却硬升到 Laravel 11，它可能静默跳过关键依赖，或报 Your requirements could not be resolved。
- 打开
composer.json，找到"php": "xxx"行 - 把它改成与目标 Laravel 版本一致的范围，例如升 Laravel 11 就该是
"php": "^8.1" - 同时检查扩展声明，如
"ext-mbstring": "*"、"ext-openssl": "*"，缺一不可 - 改完后务必运行
composer update --dry-run预检，再执行正式 update
第四步：绕过检查 ≠ 解决问题，警惕危险操作
看到报错就加 --ignore-platform-reqs 是常见误区：
-
composer install --ignore-platform-reqs只跳过安装时检测，无法修复运行时语法错误（如 PHP 8.1 的?类型声明在 PHP 7.4 下根本无法解析） -
"platform-check": false写进composer.json同样无效，只会让问题延后爆发在artisan serve或请求阶段 - 真正有效的做法是：先降级 PHP（旧项目）或升级 PHP（新项目），再重装依赖
不复杂但容易忽略。
