Laravel部署至Forge后新增路由返回404 排查求助
Laravel Forge新增路由全量返回404排查方案
核心前提
你已通过php artisan route:list确认新增路由(web/api、带/不带auth校验)已被Laravel CLI正确加载,因此问题出在缓存、权限、Web服务层或路径匹配环节,按以下优先级排查:
确认执行命令的路径正确
首先确认你手动执行artisan命令时,所处的路径是Forge当前站点的根目录(即current软链接指向的最新代码发布目录),而非旧版本的release目录。强制清除并重建Laravel全量缓存
常规php artisan optimize不会主动清除旧缓存残留,需依次执行以下命令后再重新生成优化缓存:php artisan route:clear php artisan config:clear php artisan cache:clear php artisan view:clear php artisan optimize修正缓存文件权限
若你是用root用户手动执行的artisan命令,生成的bootstrap/cache目录下缓存文件所有者会变为root,PHP-FPM运行用户(Forge默认为forge)无读取权限,会导致Web请求无法加载新路由表。执行以下命令修正权限:sudo chown -R forge:forge bootstrap/cache storage重启PHP-FPM清除OPcache缓存
注意:CLI执行artisan命令时使用的是独立的CLI PHP配置,与Web请求走的PHP-FPM OPcache完全隔离,因此CLI能正常看到新路由不代表PHP-FPM进程已加载新代码。
OPcache会常驻缓存旧代码的字节码,未重启PHP-FPM的情况下即使路由文件已更新,Web请求仍会使用旧的路由缓存。执行对应PHP版本的重启命令(替换X.X为你使用的PHP版本,如8.2对应php8.2-fpm):sudo systemctl restart phpX.X-fpm排查Nginx层问题
- 先核对
php artisan route:list输出的路由完整URL,确认访问地址大小写、前缀(如api路由默认带/api前缀)、参数位置完全匹配,Laravel路由默认大小写敏感,URL写错会直接返回404。 - 若Nginx开启了fastcgi响应缓存,需清除缓存目录内容,同时重启Nginx:
sudo systemctl restart nginx
- 先核对
排查上层缓存
若站点接入了CDN/反向代理服务,需清除对应新增URL的边缘缓存,避免旧的404响应被返回给用户。
内容的提问来源于stack exchange,提问作者superfive33
相关产品推荐
相关产品推荐

