Homestead部署Laravel网站出现502 Bad Gateway错误求助

针对你在全新Homestead+VirtualBox 12.2.0环境中遇到的Laravel项目502 Bad Gateway问题，可按以下步骤排查修复：

1. 检查PHP-FPM服务运行状态 #

502错误大多是Nginx无法连接到PHP-FPM导致的，先确认对应版本的PHP-FPM是否正常运行：

• 进入Homestead虚拟机：vagrant ssh
• 针对出现问题的站点（比如使用PHP8.3的brockphotography.test），查看服务状态：

  sudo systemctl status php8.3-fpm
  

• 如果服务未启动，手动启动并设置开机自启：

  sudo systemctl start php8.3-fpm
  sudo systemctl enable php8.3-fpm
  

• 若服务启动失败，查看错误日志定位问题：

  sudo tail -n 20 /var/log/php8.3-fpm.log
  

2. 验证站点配置与PHP版本匹配 #

确认Homestead生成的Nginx配置中，PHP-FPM套接字路径与指定版本一致：

• 打开对应站点的Nginx配置文件（以brockphotography.test为例）：

  sudo nano /etc/nginx/sites-available/brockphotography.test
  

• 检查fastcgi_pass配置项，PHP8.3对应的套接字应为：unix:/run/php/php8.3-fpm.sock，若路径错误，修改后重启Nginx：

  sudo systemctl restart nginx
  

• 同时确认Homestead已安装对应PHP版本：

  php8.3 -v
  

  若未安装，执行以下命令安装Laravel所需的PHP8.3扩展：

  sudo apt install php8.3-fpm php8.3-mysql php8.3-mbstring php8.3-xml php8.3-curl
  

3. 修复共享文件夹权限问题 #

Homestead共享文件夹的权限配置不当可能导致PHP无法读取项目文件：

• 执行以下命令统一设置项目目录权限：

  sudo chown -R www-data:www-data /home/vagrant/brockphotography
  sudo chmod -R 755 /home/vagrant/brockphotography
  sudo chmod -R 775 /home/vagrant/brockphotography/storage
  sudo chmod -R 775 /home/vagrant/brockphotography/bootstrap/cache
  

4. 调整VirtualBox共享文件夹类型 #

VirtualBox 12.2.0默认的共享方式可能存在兼容性问题，尝试切换为NFS共享：

• 在Homestead.yaml的对应folders配置中添加type: nfs：

  folders:
    - map: D:/git_projects/laravel/brockphotography
      to: /home/vagrant/brockphotography
      type: nfs
  

• 重新配置并重启虚拟机：

  vagrant reload --provision
  

5. 重建Homestead环境 #

若以上步骤均无效，尝试彻底重建环境以清除配置残留：

vagrant destroy --force
vagrant up

内容的提问来源于stack exchange，提问作者Jacob Brockwell