Laravel部署PHP 8.3需先确认框架版本≥10.42或为11.x，否则因ReflectionUnionType等变更直接报错；须关闭mbstring.strict、json.throw_on_error，Nginx改用$realpath_root，升级Composer至2.7+并清缓存。

PHP 8.3 部署 Laravel **不是简单换版本就能跑通**，Laravel 官方对 PHP 8.3 的支持从 Laravel 10.42+ 和 Laravel 11.x 才开始稳定，低于这个版本会直接报错或触发未定义行为（比如 ReflectionUnionType 相关 fatal error）。必须先确认框架版本兼容性，再动手。

确认 Laravel 版本是否支持 PHP 8.3

不查就硬上，90% 会在 composer install 或首次请求时崩在 vendor/autoload.php。Laravel 10 在 10.42 之前不识别 PHP 8.3 的联合类型反射变更；Laravel 9 及更早版本压根没适配计划。

运行 php artisan --version 查当前 Laravel 版本，再对照官方文档：Laravel 10 ≥ 10.42、Laravel 11 全系支持

检查 composer.json 中 "laravel/framework" 的约束，如 "^10.0" 且锁定了旧 minor 版，需先升级：composer update laravel/framework --with-all-dependencies

升级后务必清空 bootstrap/cache/ 下所有缓存文件，否则旧的 packages.php 或 config.php 仍可能引用已废弃的反射逻辑

PHP 8.3 新特性引发的 Laravel 运行时问题

PHP 8.3 默认启用 mbstring.strict，并收紧了 json_encode() 对资源类型和循环引用的处理——这两点会直接导致 Laravel 的日志写入失败、Session 启动报错、甚至队列 job 序列化失败。

在 php.ini 中显式关闭严格模式：mbstring.strict = Off（Laravel 的 Str::limit() 等方法依赖宽松截断）

禁用 json_encode 的新警告（避免 JsonException 被抛出）：json.throw_on_error = Off

如果用了自定义 LogChannel 或封装了 LoggerInterface，检查是否传入了 resource 类型参数（如未关闭的 cURL 句柄），PHP 8.3 会拒绝序列化

Nginx + PHP-FPM 下的 fastcgi_param 兼容陷阱

用 PHP 8.3 + FPM 时，若 Nginx 配置沿用旧模板，$_SERVER['SCRIPT_FILENAME'] 可能指向错误路径，导致 Laravel 的 public/index.php 无法被正确识别为入口，报 Class 'Illuminate\Foundation\Application' not found。

必须使用 $realpath_root 而非 $document_root：fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;

确保 php-fpm.conf 中启用了 realpath_cache_size = 4096k 和 realpath_cache_ttl = 600，否则 symlink 部署（如 current → releases/20260509）下 $realpath_root 会失效

验证方式：在 public/index.php 开头加 var_dump($_SERVER['SCRIPT_FILENAME']); die();，访问看输出是否为绝对真实路径

Composer install --no-dev 在 PHP 8.3 下的隐性失败

PHP 8.3 对 AST 解析更严格，某些未更新的开发依赖（如旧版 phpunit/phpunit、nikic/php-parser）即使加了 --no-dev，也可能因 composer.lock 中残留的 require-dev 引用链，导致 autoload_classmap.php 生成异常，最终 class_exists('Tests\TestCase') 返回 false。

执行前先清理锁文件残留：composer install --no-dev --optimize-autoloader --ignore-platform-req=php（临时绕过平台检查，仅用于诊断）

成功后立刻删掉 --ignore-platform-req 并重跑，确认无警告

检查 vendor/composer/autoload_classmap.php 是否包含大量空数组或重复键——有则说明解析出错，需升级 composer 到 2.7+ 并删掉 vendor/ 重装

真正卡住人的，往往不是“能不能装”，而是 PHP 8.3 把原来容忍的边界情况全变成硬错误。尤其是 mbstring.strict 和 realpath_cache 这两个开关，不手动干预，Laravel 就算跑起来也随时可能在某个日志写入或软链切换时静默崩溃。

Tags: PHP8.3怎么部署Laravel PHP8.3Laravel

分享到：