Yii 2 安装完全指南:Composer 与归档安装、环境验证及 Apache/Nginx/NGINX Unit/IIS 配置

原创2026-09-22 09:21:561,756 阅读
文章标签:后端Web框架

Yii 2 安装完全指南:Composer 与归档安装、环境验证及 Apache/Nginx/NGINX Unit/IIS 配置

导读

本指南以 Yii 2 官方日语版《Yii をインストールする》(docs/guide-ja/start-installation.md)为骨架,系统讲解 Yii 2 的两种安装途径——Composer 包管理器与归档文件下载,并覆盖安装后的环境需求校验、cookieValidationKey 安全配置、PHP 内置服务器快速体验,以及 Apache、Nginx、NGINX Unit、IIS 四种生产环境的推荐配置。读完本文,你将能够从零搭建一个可运行的 Yii 2 基础项目模板,并把文档根目录收敛到 web/ 以兼顾安全与优雅 URL。

Yii 2 有两种官方安装方式:使用 Composer、更新 Yii,并同时解析 PHP 与前端(CSS/JavaScript)依赖的版本关系。

标准安装会同时下载并安装框架本身与项目模板。项目模板是一个开箱即用的 Yii 应用,已实现登录、联系表单等基本功能,代码按推荐方式组织,可直接作为自己项目的起点。本文将以**基础项目模板(Basic Project Template)**为主线展开。

Info:官方指出基础模板适用于开发约九成的 Web 应用,它与高级项目模板(Advanced Project Template)的主要区别在于代码的组织方式——高级模板更适合多团队、多层级应用的协作开发。如果你是 Yii 新手,官方强烈建议先使用简单且功能足够的基础模板。


一、通过 Composer 安装

1.1 安装 Composer

如果尚未安装 Composer,请按照 getcomposer.org 的说明操作。Linux 与 Mac OS X 上执行:

curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer

Windows 上则下载并运行 Composer-Setup.exe。遇到问题可参考 Composer 文档的故障排查章节;若是 Composer 新手,建议至少阅读基本用法章节。

本指南中所有 composer 命令均假设你已全局安装 Composer,可直接使用 composer 命令;若使用本地目录中的 composer.phar,请相应调整示例命令。若之前已装过 Composer,请执行 composer self-update 确保版本最新。

注意(GitHub API 速率限制):安装 Yii 时 Composer 需要向 GitHub API 发起大量请求,请求数取决于应用依赖数量,可能超过 GitHub API 速率限制。一旦触发,Composer 会要求提供 GitHub 登录凭据以获取 API 访问令牌。在高速网络下,限制可能在 Composer 处理完之前就触发,因此官方建议在安装 Yii 之前预先配置访问令牌,方法见 Composer 关于 GitHub API 令牌的文档。

1.2 创建 Yii 项目

在 Web 可访问的目录下执行:

composer create-project --prefer-dist yiisoft/yii2-app-basic basic

该命令会在名为 basic 的目录中安装 Yii 应用模板的最新稳定版,目录名可自行更换。--prefer-dist 表示优先以发行包方式下载,速度更快。

Info:若 composer create-project 失败,可参考 Composer 文档的故障排查章节查找常见错误;修复错误后,在 basic 目录内执行 composer update 即可恢复被中断的安装。

Tip:若要安装最新开发版,可加 --stability=dev 选项:

composer create-project --prefer-dist --stability=dev yiisoft/yii2-app-basic basic

注意开发版可能破坏现有代码,禁止用于生产环境。

从当前仓库的 framework/composer.json 可以看到,Yii 2 框架本体要求 PHP >=7.4.0,并强制依赖 ext-mbstring、ext-ctype 等扩展——这些也是下文环境校验的核心依据。


二、通过归档文件安装

归档安装只需三步:

  1. 从 yiiframework.com 下载归档文件;
  2. 将归档解压到 Web 可访问的目录;
  3. 编辑 config/web.php,为 cookieValidationKey 配置项填写一个秘密密钥(通过 Composer 安装时此步骤会自动完成):
// !!! 在下面输入秘密密钥(如果为空)——cookie 验证需要它
'cookieValidationKey' => '在这里输入你的秘密密钥',

为什么必须设置 cookieValidationKey? 从源码可确认:在 framework/web/Request.php 的 loadCookies() 中,当 enableCookieValidation 为真而 cookieValidationKey 为空字符串时,会直接抛出 InvalidConfigException;每个请求 Cookie 都需经过 Yii::$app->getSecurity()->validateData($value, $this->cookieValidationKey) 的 HMAC 校验。类似地,framework/web/Response.php 在写 Cookie 时也会做同样的强校验。因此该密钥是会话安全的基础,建议使用足够长的随机字符串。


三、其他安装选项

以上流程安装出的应用已可开箱即用,适合大多数项目,尤其适合刚开始学习 Yii 的场景。此外还有两条路线:


四、安装资源包(Assets)

Yii 依赖 Bower。

如果你希望改用原生 Bower/NPM 客户端管理资源、使用 CDN,或完全跳过资源安装,可在 composer.json 中加入以下片段以阻止 Composer 安装资源:

"replace": {
    "bower-asset/jquery": ">=1.11.0",
    "bower-asset/inputmask": ">=3.2.0",
    "bower-asset/punycode": ">=1.3.0",
    "bower-asset/yii2-pjax": ">=2.0.0"
},

Note:绕过 Composer 安装资源后,资源的安装与版本冲突解决将由你自行负责,并需预料到不同扩展带来的资源文件之间可能出现不一致。


五、验证安装

安装完成后,可配置 Web 服务器(见下一节),或直接在项目根目录用 PHP 内置 Web 服务器:

php yii serve

Note:默认监听 8080 端口。若端口被占用或希望同时运行多个应用,可用 --port 参数指定端口:

php yii serve --port=8888

然后在浏览器访问:

http://localhost:8080/

php yii serve 的底层实现:该命令由控制台控制器 framework/console/controllers/ServeController.php 提供(自 2.0.7 起引入)。其 $port 默认值为 8080,$docroot 默认解析为 @app/web 别名指向的 web/ 目录;执行时先调用 isAddressTaken()(内部通过 fsockopen 探测端口是否被占用),再以 PHP_BINARY -S {address} -t {docroot} 形式启动 PHP 内置服务器。它还支持 -t(docroot)、-p(port)、-r(router)三个选项别名,并允许通过 0.0.0.0:8000 这样的地址绑定供远程访问(例如虚拟机场景)。

浏览器中应出现如下的 "Congratulations!" 页面:

Yii 安装成功页面

如果未出现,请检查 PHP 安装是否满足 Yii 的最低需求,可用以下任一方式检查:

  • 将 /requirements.php 复制为 /web/requirements.php,再用浏览器访问 http://localhost/requirements.php;

  • 或执行命令:

    cd basic
    php requirements.php
    

需求检查器如何工作:核心实现位于 framework/requirements/YiiRequirementChecker.php。checkYii() 会加载 framework/requirements/requirements.php 中定义的检查项;每个检查项声明 name(名称)、mandatory(是否强制)、condition(条件表达式,支持 eval: 前缀动态求值)、by(提出方)与 memo(说明)。未通过的强制项记为 error,非强制项记为 warning;结果同时输出 total/errors/warnings 汇总,render() 会根据是否在 CLI($_SERVER['argv'] 非空)自动选择控制台版或 Web 版报告视图。

以当前仓库 framework/requirements/requirements.php 为准,强制项包括:PHP 版本 >= 7.3.0、Reflection 扩展、PCRE 扩展、SPL 扩展、Ctype 扩展、MBString 扩展;非强制项包括:OpenSSL(Security 组件加密解密所需)、Intl >= 1.0.2 与 ICU >= 49(国际化格式化所需)、Fileinfo(文件上传 MIME 检测)、DOM(REST 的 XML 响应格式化)、IPv6 支持(IpValidator::expandIPv6)、pcntl(推荐用于 CLI 队列操作)。此外 framework/composer.json 将 PHP 门槛进一步收紧为 >=7.4.0。

请据此配置 PHP 环境以满足最低需求。文档撰写时强调“最重要的是 PHP 5.4 以上、理想为 PHP 7”,而就当前仓库实际代码而言,最低版本要求已提升到 PHP 7.3+(composer.json 中为 7.4+),请以仓库与模板安装后的需求报告为准。若应用需要数据库,还应安装 PDO PHP 扩展 及对应驱动(如 MySQL 的 pdo_mysql)。


六、配置 Web 服务器

Info:若只是试运行 Yii、暂无部署到生产服务器的意图,可暂时跳过本节。

按上述说明安装的应用,应能在运行 PHP 5.4+ 的 Apache HTTP Server 或 Nginx 下、于 Windows/Mac OS X/Linux 上开箱即用。Yii 2.0 也与 facebook 的 HHVM 兼容,但 HHVM 在某些边界场景行为与原生 PHP 不同,使用时需格外留意。

生产服务器通常希望以 https://www.example.com/index.php 而非 https://www.example.com/basic/web/index.php 访问应用,做法是将 Web 服务器文档根目录指向 basic/web 文件夹,并按路由与 URL 生成一节的说明隐藏 URL 中的 index.php。

Info:将 basic/web 设为文档根目录,还能阻止终端用户访问存放在 basic/web 兄弟目录中的私有应用代码与敏感数据文件——拒绝访问其他文件夹本身即是一种安全强化。

Info:若运行于无法修改 Web 服务器配置的共享主机环境,仍可调整应用结构以提升安全性,详见共享主机环境。

Info:若应用部署在反向代理之后,可能需要在请求组件中配置受信代理与请求头。

6.1 推荐的 Apache 配置

将以下配置放入 Apache 的 httpd.conf 或虚拟主机配置中,并把 path/to/basic/web 替换为 basic/web 的真实路径:

# 将文档根目录设为 "basic/web"
DocumentRoot "path/to/basic/web"

<Directory "path/to/basic/web">
    # 使用 mod_rewrite 支持优雅 URL
    RewriteEngine on

    # 若 UrlManager 的 $showScriptName 为 false,则禁止带脚本名访问 URL
    RewriteRule ^index.php/ - [L,R=404]

    # 若请求对应真实文件或目录,则直接放行
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d

    # 否则将所有请求转发到 index.php
    RewriteRule . index.php

    # ... 其他设置 ...
</Directory>

showScriptName 对应 framework/web/UrlManager.php 中的 public $showScriptName = true 属性(仅当 enablePrettyUrl 为真时生效);当其为 false 时,URL 中不出现入口脚本名,这就是上面前两条重写规则要配合实现的“隐藏 index.php”行为。首页 URL 的生成也依赖它:framework/web/Application.php 的 getHomeUrl() 在 showScriptName 为真时返回脚本 URL,否则返回 getBaseUrl() . '/'。

6.2 推荐的 Nginx 配置

使用 Nginx 需将 PHP 安装为 FPM SAPI。以下配置中,把 path/to/basic/web 替换为真实路径、mysite.test 替换为实际服务器主机名:

server {
    charset utf-8;
    client_max_body_size 128M;

    listen 80; ## 监听 ipv4
    #listen [::]:80 default_server ipv6only=on; ## 监听 ipv6

    server_name mysite.test;
    root        /path/to/basic/web;
    index       index.php;

    access_log  /path/to/basic/log/access.log;
    error_log   /path/to/basic/log/error.log;

    location / {
        # 将所有非真实文件的请求重定向到 index.php
        try_files $uri $uri/ /index.php$is_args$args;
    }

    # 若不希望 Yii 处理不存在的静态文件请求,可取消注释
    #location ~ \.(js|css|png|jpg|gif|swf|ico|pdf|mov|fla|zip|rar)$ {
    #    try_files $uri =404;
    #}
    #error_page 404 /404.html;

    # 拒绝访问 /assets 目录下的 php 文件
    location ~ ^/assets/.*\.php$ {
        deny all;
    }

    location ~ \.php$ {
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_pass 127.0.0.1:9000;
        #fastcgi_pass unix:/var/run/php5-fpm.sock;
        try_files $uri =404;
    }

    location ~* /\. {
        deny all;
    }
}

使用该配置时,建议同时在 php.ini 中设置 cgi.fix_pathinfo=0,以避免大量不必要的 stat() 系统调用。若运行 HTTPS 服务器,还需添加 fastcgi_param HTTPS on;,以便 Yii 正确判断连接是否安全。

6.3 推荐的 NGINX Unit 配置

也可用 NGINX Unit 加 PHP 语言模块运行 Yii 应用,示例配置如下(/path/to/app/web/ 需替换为真实路径):

{
    "listeners": {
        "*:80": {
            "pass": "routes/yii"
        }
    },

    "routes": {
        "yii": [
            {
                "match": {
                    "uri": [
                        "!/assets/*",
                        "*.php",
                        "*.php/*"
                    ]
                },

                "action": {
                    "pass": "applications/yii/direct"
                }
            },
            {
                "action": {
                    "share": "/path/to/app/web/",
                    "fallback": {
                        "pass": "applications/yii/index"
                    }
                }
            }
        ]
    },

    "applications": {
        "yii": {
            "type": "php",
            "user": "www-data",
            "targets": {
                "direct": {
                    "root": "/path/to/app/web/"
                },

                "index": {
                    "root": "/path/to/app/web/",
                    "script": "index.php"
                }
            }
        }
    }
}

规则先匹配 .php 请求并直通 PHP 目标,其余请求走静态资源共享,失败时回退到 index.php,从而在 Unit 上同样实现“非真实文件都交给 Yii 入口”的语义。你还可以在 NGINX Unit 配置 中搭建自己的 PHP 环境或提供自定义 php.ini。

6.4 IIS 配置

推荐在文档根目录指向 path/to/app/web 的虚拟主机(网站)中托管应用,并确保该网站可运行 PHP。在 web 文件夹中放置名为 web.config(即 path/to/app/web/web.config)的文件,内容如下:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
<system.webServer>
<directoryBrowse enabled="false" />
  <rewrite>
    <rules>
      <rule name="Hide Yii Index" stopProcessing="true">
        <match url="." ignoreCase="false" />
        <conditions>
        <add input="{REQUEST_FILENAME}" matchType="IsFile"
              ignoreCase="false" negate="true" />
        <add input="{REQUEST_FILENAME}" matchType="IsDirectory"
              ignoreCase="false" negate="true" />
        </conditions>
        <action type="Rewrite" url="index.php" appendQueryString="true" />
      </rule>
    </rules>
  </rewrite>
</system.webServer>
</configuration>

该规则与 Apache/Nginx 的语义一致:仅当请求不是真实文件或目录时才重写到 index.php。在 IIS 上配置 PHP 可参考微软官方资料:如何设置第一个 IIS Web 站点 与 Configure a PHP Website on IIS。


七、安装后可以做什么

安装并验证完成后,推荐按以下顺序继续学习:

至此,你已经掌握了 Yii 2 的完整安装链路:选择 Composer 或归档方式、理解 cookieValidationKey 的安全含义、用 php yii serve 快速验证、通过需求检查器排查环境,并能在 Apache、Nginx、NGINX Unit 与 IIS 上以 web/ 为文档根目录进行安全部署。

登录后查看全文
yii2