Laravel部署于Ubuntu+Nginx服务器无法下载存储文件问题

这种情况我之前部署Laravel项目时也踩过坑，上传正常但下载失败，大概率是权限配置或者Nginx路由规则的问题，咱们一步步来排查：

1. 先把存储目录的权限捋顺 #

上传正常说明写入权限没问题，但下载时Laravel需要读取文件，甚至可能需要在临时目录生成缓存文件，所以得确保相关目录的权限对Nginx运行用户（一般是www-data）开放：

• 执行以下命令给项目的storage和public目录设置正确权限：

  sudo chown -R www-data:www-data /var/www/your-project/storage
  sudo chmod -R 755 /var/www/your-project/storage
  sudo chown -R www-data:www-data /var/www/your-project/public
  sudo chmod -R 755 /var/www/your-project/public
  

• 另外别忘了系统临时目录/tmp，PHP处理下载时可能会用到它，检查权限：

  ls -ld /tmp
  

  如果输出不是drwxrwxrwt，就用sudo chmod 1777 /tmp修复。

2. 检查Nginx配置是否拦截了下载请求 #

如果你的下载路由是类似/download/{fileId}这种动态路径，得确保Nginx没有把它当成静态文件处理，而是交给Laravel的index.php解析。

• 打开你的Nginx站点配置文件（一般在/etc/nginx/sites-available/your-project.conf），确认包含以下规则：

  location / {
      try_files $uri $uri/ /index.php?$query_string;
  }
  
  location ~ \.php$ {
      fastcgi_pass unix:/run/php/php8.2-fpm.sock; # 这里替换成你实际的PHP-FPM sock路径
      fastcgi_index index.php;
      fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
      include fastcgi_params;
  }
  

• 如果你用了storage:link把存储目录软链到public下，还要确保Nginx允许跟随软链接，配置里可以加上disable_symlinks off;（如果之前没加的话）。

3. 核对Laravel下载代码的路径逻辑 #

本地和服务器的文件路径可能存在差异，别用硬编码的绝对路径！比如正确的写法应该是用Laravel的Storage门面：

// 正确示例：从public磁盘下载文件
return Storage::disk('public')->download('uploads/your-file.pdf');

• 可以在服务器上手动确认文件是否存在：

  ls /var/www/your-project/storage/app/public/uploads/your-file.pdf
  

  同时用su www-data -c "cat /var/www/your-project/storage/app/public/uploads/your-file.pdf"测试www-data用户能不能读取这个文件。

4. 检查PHP的open_basedir限制 #

有些服务器会通过open_basedir限制PHP的访问目录，如果你的Laravel存储目录不在允许列表里，就会导致下载失败。

• 找到你的PHP配置文件（比如/etc/php/8.2/fpm/php.ini），搜索open_basedir，确保它包含你的项目目录和/tmp：

  open_basedir = /var/www/your-project/:/tmp/
  

• 修改后重启PHP-FPM生效：

  sudo systemctl restart php8.2-fpm
  

5. 看日志找精准错误信息 #

如果上面的步骤都没解决，直接看日志找线索：

• Nginx错误日志：sudo tail -f /var/log/nginx/error.log
• Laravel应用日志：tail -f /var/www/your-project/storage/logs/laravel.log
  日志里会明确告诉你是权限不足、路径不存在还是其他问题，比瞎猜高效多了。

内容的提问来源于stack exchange，提问作者Fer VT