You need to enable JavaScript to run this app. Laravel部署至Forge后新增路由返回404 排查求助
优惠活动
大模型
产品
解决方案
定价
更多

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

相关产品推荐
方舟 Agent Plan

超全模态模型 × Harness 升级,最新支持 Deepseek-V4.1-Flash、GLM-5.3 系列、Doubao-Seedream-5.0-pro、Kimi-K3 (部分), 限时 9.9 元起

最近更新时间:2026.10.23 23:06:05