Yii框架子目录部署配置详解

Yii框架在子目录（如`/myapp/`）中部署并非简单上传即可运行，而需严格同步三处关键配置：PHP端通过`config/web.php`显式设置`baseUrl`和`scriptUrl`确保URL生成与资源路径正确；Nginx端用带前缀的`location /myapp/`块配合`alias`、适配的`try_files`及`SCRIPT_FILENAME $request_filename`精准路由请求；同时必须赋予`runtime`和`web/assets`目录正确的读写权限（`chmod 755`且`chown www:www`），否则将导致路由错乱、静态资源404、资产生成失败等静默故障——任何一处路径前缀缺失、斜杠错误或权限不足，都会让整个应用悄然失能。

Yii框架不能直接部署到子目录（比如 https://example.com/myapp/）就开跑，必须显式告诉它“我在哪”，否则路由生成、资源路径、重写规则全乱套——Url::to() 会漏掉子目录前缀，assets/ 加载 404，index.php 也找不到正确配置。

web 目录必须是 Web 服务器的 DocumentRoot，但 Yii 要运行在子路径下

这不是矛盾，而是两件事：Web 服务器的根目录（root）仍需指向 Yii 项目的 web/ 子目录；但应用逻辑上要“感知”自己位于 /myapp/ 这个 URL 前缀下。关键在三处同步：

• config/web.php 中设置 'baseUrl' => '/myapp'（注意开头带 /，结尾不带）
• config/web.php 的 urlManager 配置里加 'scriptUrl' => '/myapp/index.php'
• Nginx 的 location 块需匹配该子路径，且 try_files 指向带前缀的 index.php

Nginx 子目录重写规则怎么写才不 404

错把 location / 当成万能兜底，是子目录部署最常踩的坑。Nginx 不会自动把 /myapp/xxx 的请求“降级”进子目录处理，你得明确声明。

正确做法是用带前缀的 location 块，并确保 try_files 和 fastcgi_param 都适配：

location /myapp/ {
    alias /var/www/html/myapp/web/;
    index index.php;
    try_files $uri $uri/ /myapp/index.php?$args;

    location ~ \.php$ {
        fastcgi_pass 127.0.0.1:9000;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $request_filename;
        include fastcgi_params;
    }
}

注意：alias 后路径末尾必须有 /；SCRIPT_FILENAME 用 $request_filename（不是 $document_root$fastcgi_script_name），否则 PHP 找不到 index.php。

URL 美化（enablePrettyUrl）在子目录下怎么配才生效

启用 enablePrettyUrl 时，Yii 默认假设应用在域名根下。子目录下必须额外指定 baseUrl 和 scriptUrl，否则 Url::to(['site/login']) 会生成 /site/login 而不是 /myapp/site/login。

完整配置示例（config/web.php）：

return [
    'components' => [
        'urlManager' => [
            'enablePrettyUrl' => true,
            'showScriptName' => false,
            'baseUrl' => '/myapp',
            'scriptUrl' => '/myapp/index.php',
        ],
    ],
];

同时确保 Nginx 的 location /myapp/ 块里 try_files 行末是 /myapp/index.php?$args，而不是 /index.php?$args。

runtime 和 assets 目录权限在子目录部署中容易被忽略

宝塔或手动部署时，常只改了项目根目录权限，却忘了 web/assets 是由 Yii 在运行时动态生成并写入的——它的物理路径在 /var/www/html/myapp/web/assets，但 URL 路径是 /myapp/assets/。如果 web/assets 不可写，首次访问就会报 Failed to write file to disk。

执行以下命令（替换实际路径）：

• chmod -R 755 /var/www/html/myapp/runtime
• chmod -R 755 /var/www/html/myapp/web/assets
• 确认 Web 服务器进程用户（如 www-data 或 www）对这两个目录有读写权：chown -R www:www /var/www/html/myapp/runtime /var/www/html/myapp/web/assets

子目录部署真正的复杂点不在重写规则本身，而在于所有路径变量（baseUrl、scriptUrl、alias、SCRIPT_FILENAME）必须严格对齐——差一个斜杠或一个前缀，整个应用就静默失效。

今天关于《Yii框架子目录部署配置详解》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！