laravel 404 nginx

2026-05-26资讯阅读 613

Laravel 项目部署 Nginx 后 404？一文搞定从配置到调试全流程

在 Laravel 项目部署到 Nginx 环境时，404 错误是开发者最常遇到的“拦路虎”之一。明明路由定义正确、控制器方法无误，页面却总显示“Not Found”。这背后往往是 Nginx 配置规则与 Laravel 路由机制的衔接问题。本文从配置细节到调试工具，带你彻底解决 Laravel + Nginx 下的 404 难题。

一、伪静态规则：Nginx 不知道该“找哪条路”

Laravel 的路由本质是通过 index.php 解析的（单入口设计），但 Nginx 默认只会返回真实存在的文件。如果没有配置伪静态规则，访问如 /home 这样的路由时，Nginx 找不到对应文件，就会直接返回 404。

laravel 404 nginx

核心问题：Nginx 未将非文件请求转发到 index.php。
解决方法：在 Nginx 配置中添加伪静态规则，让所有请求先尝试找静态文件，失败后统一交给 index.php 处理。正确配置如下：

server {
    listen 80;
    server_name your-domain.com;
    root /var/www/laravel/public;  # 关键：指向 Laravel public 目录
    index index.php index.html;

    location / {
        try_files $uri $uri/ /index.php?$query_string;  # 所有请求走 index.php
    }

    location ~ \.php$ {
        fastcgi_pass unix:/run/php/php8.1-fpm.sock;  # PHP-FPM 路径
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }
}

二、路径配置：Nginx 认错了“家”

许多新手会将 Nginx 的 root 路径直接指向 Laravel 项目根目录（而非 public 文件夹）。例如项目根目录是 /var/www/laravel，但 Laravel 的入口文件实际在 /var/www/laravel/public/index.php。若 Nginx 配置中 root 指向 /var/www/laravel，当访问 / 时，Nginx 会尝试找 /var/www/laravel/index.php，但文件实际在 public 目录，导致 404。

验证方法：执行 nginx -t 检查配置语法，确保 root 路径指向 public 目录。若修改后仍报错，可通过 curl http://localhost/public/index.php 直接测试入口文件是否能正常访问。

三、PHP-FPM 解析：“翻译官”失职

即使伪静态配置正确，若 Nginx 无法将请求正确转发给 PHP-FPM，也会导致 404。需重点检查：

FastCGI 连接：确认 fastcgi_pass 指向的 PHP-FPM 进程是否存在（如 unix:/run/php/php8.1-fpm.sock 或 127.0.0.1:9000）；
服务状态：执行 systemctl status php8.1-fpm 检查 PHP-FPM 是否运行；
权限问题：public 目录及 index.php 文件需对 Nginx 用户（通常是 www-data）有读写权限。

四、应用层隐藏问题：路由“迷路”或缓存“失忆”

若上述配置无误，仍需排查 Laravel 应用本身：

路由定义错误：检查 routes/web.php 中是否存在路由拼写错误（如 HomeController 类名错误）；
缓存未更新：执行 php artisan route:clear 和 config:cache 清除缓存，避免旧路由规则干扰；
环境变量：确认 .env 文件中 APP_URL 是否与实际域名一致，避免资源路径（图片、CSS）加载失败。

五、调试工具与实战步骤

Nginx 配置验证：执行 nginx -t 检查配置语法，发现错误立即修正；
入口文件测试：直接访问 http://your-domain/public/index.php，若能显示首页，说明 PHP 解析正常，问题在伪静态规则；
错误日志定位：查看 Nginx 错误日志（/var/log/nginx/error.log），重点关注“File not found”或“FastCGI sent in stderr”等关键词；
路由调试：使用 php artisan route:list 检查路由列表，确认目标路由是否被正确注册。

总结与预防

Laravel 与 Nginx 的 404 问题，核心是“配置衔接”与“路由解析”的配合。记住三个关键点：伪静态规则是桥梁，public 目录是核心路径，PHP-FPM 是解析引擎。日常开发建议使用 Laravel Valet 或 Docker 简化环境配置，生产环境通过 CI/CD 自动化部署，从源头减少配置错误。掌握这些，下次遇到 404，就能快速“拨乱反正”。