Laravel + Nginx 404问题频发？5步排查法+完整配置指南

在将Laravel项目部署到Nginx服务器时，开发者常遇到“页面未找到”的404错误——明明路由定义正确、代码逻辑无误，请求却始终被拦截。这类问题看似复杂，实则多因Nginx配置或环境设置疏漏导致。本文从核心原因到实战解决方案，帮你快速定位并修复Laravel+Nginx的404难题。

一、核心原因：Nginx为何“看不懂”Laravel路由？

Laravel的路由系统依赖Nginx将所有请求转发到index.php处理，若Nginx未配置关键规则，会直接返回404。常见原因包括：

1. 伪静态规则缺失

Laravel的路由本质是“重写”逻辑，但Nginx默认不识别PHP框架的路由语法。若缺少try_files指令，Nginx会将请求视为普通静态文件，无法转发到index.php。

2. PHP-FPM路径配置错误

FastCGI进程管理（PHP-FPM）的SCRIPT_FILENAME参数指向错误路径，导致Nginx无法正确调用PHP解析器。例如，若public目录未被正确识别，PHP脚本可能被拦截。

3. 路由缓存未更新

Laravel的路由缓存功能（php artisan route:cache）会缓存路由定义。若路由修改后未清除缓存，Nginx会读取旧缓存文件，导致新路由无法生效。

4. 存储目录权限问题

storage或bootstrap/cache目录权限不足时，Laravel无法写入缓存文件，可能导致路由解析失败（尤其在动态路由场景下）。

5. Nginx配置缓存未刷新

修改Nginx配置后未执行nginx -s reload，或配置文件存在语法错误，会导致新配置不生效，请求仍按旧规则处理。

二、5步排查与修复方案

Step 1：检查Nginx伪静态规则

Laravel要求Nginx将所有请求转发到index.php。在server配置块中添加以下规则：

location / {
    try_files $uri $uri/ /index.php?$query_string;  # 关键：先尝试静态文件，失败则转发到index.php
}

验证方法：重启Nginx后，访问任意路由（如/api/user），若仍404，需检查try_files路径是否正确指向public目录。

Step 2：修复PHP-FPM配置

在location ~ \.php$块中确保SCRIPT_FILENAME正确指向index.php：

location ~ \.php$ {
    fastcgi_pass unix:/var/run/php/php8.0-fpm.sock;  # 替换为你的PHP-FPM路径
    fastcgi_index index.php;
    fastcgi_param SCRIPT_FILENAME $document_root/index.php;  # 指向public目录下的index.php
    include fastcgi_params;
}

排查工具：通过nginx -t检查配置语法，用curl -I yourdomain.com/404测试请求是否被转发到PHP解析器。

Step 3：清除路由缓存

若路由修改后未生效，执行以下命令清除缓存：

php artisan route:clear   # 清除路由缓存
php artisan config:clear  # 清除配置缓存（若涉及环境变量）

注意：生产环境建议定期执行route:cache提升性能，但修改路由后必须重新缓存。

Step 4：修复存储目录权限

Laravel的缓存、日志、会话等文件依赖storage目录。执行以下命令修正权限：

chmod -R 755 storage bootstrap/cache  # 赋予读写执行权限
chown -R www-data:www-data storage  # 若使用www-data用户运行PHP-FPM

测试：访问/storage/logs/laravel.log，若能正常打开日志文件，说明权限配置正确。

Step 5：检查Nginx服务状态

修改配置后需重启Nginx，避免配置缓存生效：

nginx -s reload  # 重载配置
nginx -s stop && nginx  # 重启服务（若重载失败）

终极排查：查看Nginx错误日志定位具体问题：

tail -f /var/log/nginx/error.log  # 关注“404 Not Found”或“FastCGI sent in stderr”关键词

三、实战案例：从“404地狱”到“秒级访问”

某开发者将Laravel项目部署到Nginx后，所有路由均返回404。排查发现：

Nginx配置中缺少try_files规则，导致请求未转发到index.php；
PHP-FPM的SCRIPT_FILENAME错误指向/var/www/index.php（而非public/index.php）；
路由缓存未清除，新添加的/api/login路由未生效。

修复步骤：

补充try_files规则，将请求转发到public/index.php；
修正fastcgi_param SCRIPT_FILENAME路径；
执行route:clear后重新部署，问题彻底解决。

结语

Laravel+Nginx的404错误看似复杂，实则可通过“伪静态规则→PHP-FPM路径→缓存→权限→服务重启”的5步排查法快速定位。关键在于理解Nginx的请求转发逻辑，以及Laravel对环境配置的依赖。掌握这些要点，开发者可高效应对部署中的各类“404陷阱”，让项目稳定运行。

建议收藏：将上述Nginx配置模板直接复制到服务器，结合实际环境调整路径，即可大幅降低404概率。遇到复杂场景时，优先检查错误日志和缓存状态，往往能事半功倍。

laravel 404 nginx