如何在Yii项目中添加静态文件夹（Yii文件夹路由异常问题）

访问/faq/路径下的静态文件跳Yii404，核心原因是Web服务器的重写规则把所有请求都转发给了Yii入口文件index.php，没有优先判断请求路径对应的真实文件/目录是否存在，请求直接被Yii路由逻辑接管。
以下是两种可落地的方案，优先选第一种性能最优。 #

方案1：调整Web服务器重写规则（推荐） #

这个方案下静态文件直接由Nginx/Apache返回，完全不经过PHP/Yii解析，性能最高。

前置检查 #

首先确认文件存放位置正确：faq文件夹必须放在Yii项目的Web根目录（即web/文件夹，和Yii自带的index.php、assets目录同级），不要放在项目根目录、protected目录等非Web可访问路径下。

Nginx配置 #

找到站点对应的Nginx配置文件，调整location /段的try_files规则，核心逻辑是先匹配真实存在的文件、目录，匹配不到再转发给Yii：

server {
    listen 80;
    server_name website.com;
    # 注意root必须指向Yii项目的web目录，不要指向项目根目录
    root /your/project/path/web;
    index index.html index.php;

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

    # 原有PHP解析配置保持不变即可，无需修改
    location ~ \.php$ {
        fastcgi_pass 127.0.0.1:9000;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }
}

修改完成后执行nginx -t校验配置语法，确认无误后执行nginx -s reload重载配置即可生效。

Apache配置 #

如果使用Apache，首先确认mod_rewrite模块已开启，然后修改web/目录下的.htaccess文件，添加规则跳过真实存在的文件/目录的转发：

RewriteEngine On

# 匹配到真实文件/目录时直接访问，不转发给Yii
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . index.php

修改完成后重启Apache服务即可生效。 #

方案2：Yii框架层配置路由例外（适合无法修改Web服务器配置的场景） #

如果使用虚拟主机没有权限修改Web服务器配置，可以在Yii层面配置路由规则，跳过faq路径的路由解析，直接返回静态文件。这个方案请求会经过PHP进程，性能比方案1差。
以Yii2为例，打开配置文件config/web.php，做如下调整：

return [
    // 其他原有配置保持不变
    'components' => [
        'request' => [
            // 关闭faq路径下的CSRF校验，避免静态表单提交报400错误
            'noCsrfValidationRoutes' => ['faq/'],
        ],
        'urlManager' => [
            'enablePrettyUrl' => true,
            'showScriptName' => false,
            'rules' => [
                // 匹配所有faq开头的请求，直接返回对应静态文件
                'faq/<file:.+\.html>' => function ($file) {
                    $filePath = Yii::getAlias('@webroot/faq/' . $file);
                    if (is_file($filePath)) {
                        return Yii::$app->response->sendFile(
                            $filePath,
                            null,
                            ['inline' => true, 'mimeType' => 'text/html']
                        );
                    }
                    throw new \yii\web\NotFoundHttpException();
                },
            ],
        ],
        // 其他原有组件配置保持不变
    ],
];

如果是Yii 1.x版本，逻辑一致，在protected/config/main.php的urlManager规则中添加对应匹配规则，读取web目录下的faq文件返回即可。 #

常见问题排查 #

• 配置完成后仍返回404：先检查faq目录及内部HTML文件的权限，确保Web服务器运行用户有可读权限
• 出现文件下载提示：如果用方案2，确认sendFile方法的inline参数设为true，且mimeType配置正确
• 静态文件中引用的CSS/JS加载失败：把静态文件依赖的资源也放到web/faq目录下，使用相对路径引用即可

内容的提问来源于stack exchange，提问作者TelePuzik