Laravel 8.74.0 新站点仅在服务端出现500错误如何解决

核心问题根因 #

问题由两个错误叠加导致：

1. 本地开发PHP版本与服务器PHP版本不一致，composer安装的依赖适配高版本PHP，与服务器7.4.26环境不兼容，添加platform-check: false仅屏蔽了报错提示，未解决实际的依赖不兼容问题
2. 不符合官方规范的部署配置：将server.php重命名为index.php、移动.htaccess到根目录的操作属于临时处理，容易触发权限、路由解析类的隐式错误

分步修复操作 #

1. 修复依赖不兼容问题 #

• 先删除本地项目根目录下的vendor文件夹、composer.lock文件
• 编辑composer.json，在config配置段添加PHP版本锁定规则，指定和服务器一致的版本：

"config": {
    "platform": {
        "php": "7.4.26"
    },
    // 保留原有其他config配置不变
}

• 执行composer install --no-dev重新拉取适配PHP7.4的依赖包，不要执行composer update，避免不必要的依赖版本跳跃
• 依次执行php artisan config:clear、php artisan cache:clear清除本地缓存后，再重新打包项目上传到服务器

2. 修正部署配置（二选一即可） #

推荐方案：官方标准部署

• 恢复之前修改的server.php原名，删除根目录下复制的.htaccess文件
• 将服务器站点的根目录指向Laravel项目的public文件夹，站点默认索引文件设置为index.php，该配置可避免绝大多数目录权限、路由解析问题

兼容方案：无法修改站点根目录时使用

• 项目根目录新建index.php，写入以下内容：

<?php
define('LARAVEL_START', microtime(true));
require __DIR__.'/vendor/autoload.php';
$app = require_once __DIR__.'/bootstrap/app.php';
$kernel = $app->make(Illuminate\Contracts\Http\Kernel::class);
$response = $kernel->handle(
    $request = Illuminate\Http\Request::capture()
);
$response->send();
$kernel->terminate($request, $response);

• 将public目录下的.htaccess、favicon.ico、robots.txt以及所有静态资源目录（css/js/img等）复制到项目根目录
• 给项目下的storage、bootstrap/cache目录设置755及以上权限，确保web服务器进程拥有读写权限

3. 残留500错误排查 #

如果完成上述操作后仍返回500错误，编辑项目根目录的.env文件，将APP_DEBUG值改为true，刷新页面即可看到具体错误信息，根据提示针对性处理即可，问题修复后记得将APP_DEBUG改回false避免泄露敏感信息。

内容的提问来源于stack exchange，提问作者Anirban Kreative