Ubuntu下Laravel路由问题的排查与修复
一、先快速定位问题类型
- 出现404 Not Found：多为Web服务器重写规则未生效（如仅根路径可访问，其他路径404），或路由未定义/被缓存。
- 出现Method Not Allowed（405）：路由定义了但请求方法不匹配（如用GET访问只支持POST的路由）。
- 出现Route [xxx] not defined：路由未定义、命名错误、或路由缓存未更新。
- 出现TokenMismatchException（表单）：CSRF 令牌验证失败，与路由无直接关系，但会影响提交。
- 建议先开启调试查看明确错误：.env → APP_DEBUG=true，并查看 storage/logs/laravel.log。这些现象与排查方向在 Ubuntu 上的 Apache/Nginx 环境中均适用。
二、通用修复步骤（与服务器无关）
- 核对路由定义：在 routes/web.php 或 routes/api.php 中确认 URL、请求方法、控制器与方法是否存在且拼写正确。
- 清除路由缓存：执行 php artisan route:clear；如线上使用缓存，再执行 php artisan route:cache。
- 检查命名与冲突：避免同名路由；用 php artisan route:list 查看所有路由与名称。
- 核对控制器与命名空间：控制器文件位置与命名空间匹配，方法可访问。
- 核对路由参数与顺序：参数规则匹配，更具体的路由放前面，避免被通用路由拦截。
- 检查中间件：确保路由使用的中间件已正确注册，未错误拦截合法请求。
以上步骤可快速排除大多数“未定义路由”“访问方式不对”“缓存未更新”等问题。
三、Apache 环境专项排查（Ubuntu 常见）
- 启用重写模块并重启：
- 启用：sudo a2enmod rewrite
- 重启：sudo systemctl restart apache2
- 虚拟主机配置要点（示例）：
- DocumentRoot 指向项目的 public 目录。
- 在对应的 <Directory /path/to/your-project/public> 中设置：
- AllowOverride All（关键，允许 .htaccess 生效）
- Require all granted
- 确认 public/.htaccess 存在且未被修改（Laravel 自带的重写规则用于将所有非静态资源请求转发给 index.php）。
- 若仍仅根路径可访问，多为 AllowOverride 未设为 All 或 .htaccess 未生效 所致，修正后重载 Apache。
这些配置项缺失是 Ubuntu 上“除根路径外全 404”的最常见原因。
四、Nginx 环境专项排查（Ubuntu 常见）
- 站点配置要点（示例）：
- root 指向项目的 public 目录。
- 核心重写规则：
- try_files $uri $uri/ /index.php?$query_string;
- PHP 处理（按本机 PHP 版本调整）：
- 使用 PHP-FPM（如：fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;）
- 确保 SCRIPT_FILENAME $document_root$fastcgi_script_name; 正确
- 启用站点并验证重载：
- 软链：sudo ln -s /etc/nginx/sites-available/your-site /etc/nginx/sites-enabled/
- 语法检查：sudo nginx -t
- 重载：sudo systemctl reload nginx
- 若所有路由均 404，优先检查 root 是否指向 public 与 try_files 规则是否正确。
五、文件权限与日志定位
- 权限设置（生产常见）：
- 项目属主：sudo chown -R www-data:www-data /var/www/your-laravel-project
- 存储与缓存可写：sudo chmod -R 755 /var/www/your-laravel-project/storage
- 查看日志定位：
- Laravel 日志：storage/logs/laravel.log
- Web 服务器日志：/var/log/apache2/error.log 或 /var/log/nginx/error.log
- 仍异常时，临时开启 APP_DEBUG=true 获取更详细错误页面，修复后记得关闭。
权限不当或日志缺失会掩盖真实原因，排查时务必核对。
