新手避坑指南：Nginx与Yii结合时404的5大原因及解决方案

在Web开发中，Nginx作为高性能Web服务器，常与Yii框架搭配使用。但开发者在实际部署中，404错误却频频出现——用户访问正常路由返回“页面不存在”，搜索引擎抓取失败，严重影响体验。本文将拆解Nginx与Yii组合下404的核心原因及解决方法，帮你快速定位问题。

一、Nginx与Yii为何会频繁触发404？

Yii作为PHP框架，依赖URL路由规则和Nginx的伪静态配置协同工作。当两者配合不当，或环境配置存在偏差时，就会出现“请求合法却返回404”的怪象。常见场景包括：

1. Yii路由规则未生效（最常见）

Yii的URL管理默认采用“伪静态”模式（Pretty URL），需通过config/web.php配置路由规则。若配置错误，如：

enablePrettyUrl未设为true，导致请求无法解析为具体控制器/动作；
rules规则缺失或匹配错误，如用户访问site/about，但路由未映射到SiteController::actionAbout，Yii直接返回404。

2. Nginx伪静态规则缺失

Nginx默认不处理PHP框架的路由，需通过location规则将所有请求转发至Yii入口文件（通常为index.php）。若缺少以下配置：

location / {
    try_files $uri $uri/ /index.php?$args;
}

Nginx会因找不到具体文件（如site/about非真实文件）直接返回404，而非交给Yii处理路由。

3. 路径与权限配置错误

入口文件路径错误：Nginx的root指令指向的目录错误，或index指令未指定index.php（如root /var/www/html;，但Yii入口文件在子目录/blog下）；
权限问题：Nginx用户（如www-data）对Yii框架目录无读取权限，导致index.php无法加载，返回404。

4. 环境变量与缓存干扰

Yii的$_SERVER['SCRIPT_FILENAME']路径配置错误，导致框架找不到入口文件；
Nginx配置变更后未重启（如修改nginx.conf后未执行nginx -s reload），或PHP-FPM重启后连接失效，Nginx错误拦截请求。

5. 子目录部署时路径不兼容

若Yii应用部署在子目录（如example.com/blog），需同时调整Yii的baseUrl和Nginx的root：

Yii的config/web.php中'baseUrl' => '/blog'未设置，导致前端资源路径错误；
Nginxlocation规则未匹配子目录请求，如location /blog/ { ... }遗漏配置。

二、3步快速排查与解决404

步骤1：检查Yii路由配置

打开config/web.php，确认URL管理配置：

'urlManager' => [
'enablePrettyUrl' => true, // 开启伪静态
'enableStrictParsing' => false, // 允许非严格匹配（开发环境）
'showScriptName' => false, // 隐藏index.php
'rules' => [
    'about' => 'site/about', // 示例路由规则
    // 其他规则...
],
],

用curl测试路由：curl -I http://your-domain.com/about，查看响应头是否为200 OK（正常）或404 Not Found（异常）。

步骤2：修复Nginx伪静态规则

在nginx.conf或站点配置文件中添加以下规则（以Yii部署在根目录为例）：

server {
    listen 80;
    server_name your-domain.com;
    root /var/www/html/your-yii-app/web; # 指向Yii的web目录
    index index.php;

    location / {
        try_files $uri $uri/ /index.php?$args; # 关键：重写请求到index.php
    }

    location ~ \.php$ {
        try_files $uri =404;
        fastcgi_pass unix:/run/php/php8.0-fpm.sock; # 指向PHP-FPM
        fastcgi_index index.php;
        include fastcgi_params;
    }
}

验证：执行nginx -t检查配置语法，无误后重启Nginx：systemctl restart nginx。

步骤3：排查路径与权限

入口文件验证：在nginx站点配置中，确认root指向Yii的web目录（如/var/www/html/your-yii-app/web），且index包含index.php；
权限检查：执行chown -R www-data:www-data /var/www/html/your-yii-app，确保Nginx用户可读取所有文件；

子目录特殊处理：若部署在子目录，修改config/web.php的baseUrl和Nginxroot：

root /var/www/html/blog; # 子目录路径
location /blog/ {
  try_files $uri $uri/ /blog/index.php?$args; # 匹配子目录请求
}

三、最佳实践：预防404的3个技巧

双日志监控：同时开启Nginx的access_log（记录请求）和Yii的error.log（记录框架错误），快速定位“请求未被处理”或“路由不存在”问题；
开发环境调试：在config/web.php中设置'errorHandler' => ['errorAction' => 'site/error']，让Yii捕获404并返回自定义页面；
自动化测试：部署后用puppeteer或phpunit批量测试核心路由，提前发现配置问题。