Linux服务器上Laravel项目常见问题及解决

Linux服务器上 Laravel 项目常见问题与解决

一 权限与所有权

• 症状：访问出现500，日志提示无法写入 storage/ 或 bootstrap/cache/，或 composer install 报 Permission denied。
• 处理步骤：
  1. 确认 Web 服务运行用户（常见为 www-data 或 nginx）。
  2. 推荐的安全权限：
     • 项目根目录文件设为 644、目录设为 755：
       find /path/to/laravel -type f -exec chmod 644 {} ;
       find /path/to/laravel -type d -exec chmod 755 {} ;
     • 仅对需要写入的目录赋予组写并调整属组：
       chgrp -R www-data storage bootstrap/cache
       chmod -R ug+rwx storage bootstrap/cache
     • 如用 FTP/SFTP 部署，将部署用户加入 Web 组：usermod -a -G www-data youruser
  3. 避免使用 777，优先“最小权限 + 正确属组”。
  4. 若使用 LNMP 一键包并出现 .user.ini 限制，可临时 chattr -i 移除后再调整权限（变更后记得恢复或清理）。

二 环境与配置

• 症状：页面白屏或报错找不到配置，数据库连接失败，或本地正常线上异常。
• 处理步骤：
  1. 确保存在 .env 并从 .env.example 复制：cp .env.example .env。
  2. 生成应用密钥：php artisan key:generate。
  3. 检查 .env 中数据库连接、缓存、队列等配置；生产环境设置 APP_DEBUG=false。
  4. 安装依赖：composer install --optimize-autoloader --no-dev（上线建议排除 dev 依赖）。
  5. 若克隆仓库后出现类找不到或依赖异常，执行：composer dump-autoload。
  6. 修改 php.ini 或 Nginx/FPM 后需重启对应服务。

三 Web 服务器与路由

• 症状：路由 404、直接下载 .php、入口不对或返回 500。
• 处理要点：
  1. 文档根目录必须指向 public/。
  2. Nginx 关键配置：
     • 根目录：root /path/to/laravel/public;
     • 路由重写：try_files $uri $uri/ /index.php?$query_string;
     • PHP 处理：fastcgi_pass 指向正确的 php-fpm.sock 或 127.0.0.1:9000；fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
     • 安全头：X-Frame-Options、X-XSS-Protection、X-Content-Type-Options；隐藏敏感文件：location ~ /.(?!well-known).* { deny all; }
  3. Apache：启用 mod_rewrite，虚拟主机 DocumentRoot 指向 public， 设置 AllowOverride All。
  4. 常见陷阱：某些一键包引入的 enable-php 配置与 Laravel 的 try_files 冲突，或 fastcgi 段内错误使用 try_files 导致 500；LNMP 的 open_basedir 限制也会触发路径不可达，需要调整 php.ini 或虚拟主机配置。

四 依赖与扩展

• 症状：页面报错缺少扩展、类未找到、迁移失败等。
• 处理步骤：
  1. 安装并启用常用扩展：php-fpm php-mysql php-mbstring php-xml php-curl php-zip php-fileinfo php-openssl。
  2. 若使用 utf8mb4（Laravel 5.4+ 默认），遇到 “Specified key was too long” 时，在 AppServiceProvider 的 boot 方法中添加：Schema::defaultStringLength(191);
  3. 依赖异常或类映射问题：composer install、composer dump-autoload；必要时清除 vendor 后重装。
  4. 修改 php.ini 后重启 php-fpm 与 Nginx。

五 日志与快速排查

• 症状：错误只显示空白页或通用 500，无法定位。
• 处理步骤：
  1. 开发阶段临时开启错误显示：编辑 php.ini，将 display_errors = Off 改为 On，并重启服务；上线务必关闭。
  2. 查看 storage/logs/laravel.log 与 Nginx 错误日志（如 /var/log/nginx/error.log），优先从日志定位。
  3. 生产环境建议执行优化配置并关闭调试：php artisan config:cache、php artisan route:cache、php artisan view:cache；.env 中 APP_DEBUG=false。