Laravel API部署Nginx后返回404 NotFound问题排查求助

我开发了一个调用SDK的简易API，接收参数校验后返回新值。本地使用php artisan serve运行正常，可通过HTTP客户端发起请求；但部署到Linux VPS并配置Nginx后出现异常：双参数路由/ali/{url}/{type}可正常工作，修改为单参数路由/ali/{url}后返回404错误。

排查思路 #

1. 优先查看日志定位问题 #

• 检查Nginx错误日志（/var/log/nginx/api.log），确认请求是否被正确转发到index.php，是否有文件不存在的报错记录
• 查看Laravel日志（storage/logs/laravel.log），排查是否存在路由匹配失败、参数解析异常等细节信息

2. 确认路由匹配优先级 #

• 执行php artisan route:list列出所有路由，确认/ali/{url}已正确注册，且没有被其他路由（如/ali/*这类通配路由）提前匹配覆盖
• 检查路由定义顺序，Laravel路由按定义顺序匹配，确保/ali/{url}在冲突路由之前定义

3. 修正Nginx请求转发逻辑 #

• 单参数路由的{url}可能包含斜杠、点号等特殊字符，导致Nginx误判为真实文件路径，未转发到Laravel。调整location /块配置：

  location / {
      try_files $uri $uri/ /index.php?$query_string;
  }
  

• 检查location ~ \.php$块的PATH_INFO传递，确保Laravel能正确解析路由参数：

  location ~ \.php$ {
      try_files $uri =404;
      fastcgi_split_path_info ^(.+\.php)(/.+)$;
      fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
      fastcgi_index index.php;
      fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
      fastcgi_param PATH_INFO $fastcgi_path_info;
      include conf/fastcgi_params;
  }
  

4. 处理参数特殊字符限制 #

• 如果{url}参数包含斜杠（如/ali/https://example.com），Laravel默认路由参数不匹配斜杠，需修改路由规则：

  Route::get('/ali/{url}', [AliexpressController::class, 'index'])->where('url', '.*');
  

• 先用简单参数（如/ali/test）测试，排除参数本身格式导致的匹配失败

5. 清除Laravel缓存并重启服务 #

• 部署后可能存在路由缓存未更新，执行以下命令清除缓存：

  php artisan route:clear
  php artisan config:clear
  

• 重启Nginx和PHP-FPM确保配置生效：

  systemctl restart nginx php8.2-fpm
  

6. 检查文件权限 #

• 确认Laravel的storage和bootstrap/cache目录权限正确，Nginx运行用户（通常为www-data）拥有读写权限：

  chown -R www-data:www-data /var/www/alilinkgen/storage /var/www/alilinkgen/bootstrap/cache
  chmod -R 755 /var/www/alilinkgen/storage /var/www/alilinkgen/bootstrap/cache
  

内容的提问来源于stack exchange，提问作者Rafael Tuneca