Yii 2 安装完全指南:Composer 与归档安装、环境校验及 Apache/Nginx 生产配置

原创2026-09-21 18:11:341,704 阅读
文章标签:后端Web框架

Yii 2 安装完全指南:Composer 与归档安装、环境校验及 Apache/Nginx 生产配置

本篇技术指南以官方印尼语版《Instalasi Yii》为核心骨架,系统讲解 Yii 2 框架的两种主流安装方式——通过 Composer 包管理器安装与通过归档文件手动安装,并延伸到安装后的环境校验、php yii serve 内置服务器使用,以及 Apache / Nginx 等 Web 服务器的生产级配置。读完本文,你将掌握从零搭建一套可运行的 Yii 2 Basic 项目模板、验证 PHP 环境是否满足框架最低要求、并把应用安全地部署到生产服务器的完整实战方案,同时理解 cookieValidationKey、文档根目录等关键配置在源码层面的作用原理。

一、两种安装方式概览:Composer 与归档文件

Yii 2 提供两种安装途径,各有适用场景:

  • 通过 Composer 包管理器安装:这是官方推荐的优先方式。只需执行一条命令,即可完成框架核心与项目模板的下载和安装,后续还能通过命令行随时安装新的扩展或升级 Yii 本身,无需手工管理文件。
  • 通过下载归档文件安装:适用于无法使用 Composer 的环境,需要手工解压并修改少量配置文件。

无论采用哪种方式,Yii 的标准安装结果都包含两部分:框架本身(即本仓库 framework/ 目录所对应的核心代码)与一个项目模板。项目模板是一个开箱即用的 Yii 工程,预先实现了登录、联系表单等基础功能,代码按官方推荐方式组织,可作为你新项目的良好起点。

本指南及后续章节将以 Basic 项目模板(Basic Project Template)为例讲解安装与二次开发。Yii 还提供了另一种 Advanced 项目模板(Advanced Project Template),其代码组织结构更适合多层级、团队协作开发的应用;如果你刚接触 Yii,官方建议优先使用 Basic 模板——它足够简洁,同时功能足以覆盖约 90% 的 Web 应用开发场景。

二、通过 Composer 安装

2.1 安装 Composer 本身

如果你尚未安装 Composer,可先完成其安装:

  • Linux 与 macOS:执行以下两条命令,将 Composer 安装为全局可用的 composer 命令:
curl -sS https://getcomposer.org/installer | php
mv composer.phar /usr/local/bin/composer
  • Windows:下载并运行 Composer-Setup.exe 安装程序。

安装后建议确认使用的是最新版本,可通过 composer self-update 随时升级。若你以局部目录下的 composer.phar 方式使用,需将后文示例命令中的 composer 相应替换。

注意:安装 Yii 过程中 Composer 需要向 GitHub API 请求大量依赖信息,请求量可能超过 GitHub API 的速率限制(rate limit)。一旦触发限制,Composer 会提示输入 GitHub 登录凭据以获取访问令牌。在快速网络环境下该限制可能比预期更早触发,建议在安装 Yii 前预先配置好 GitHub API 访问令牌,并参考 Composer 官方文档中的故障排查章节。

2.2 安装 Yii 项目模板

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

composer global require "fxp/composer-asset-plugin:^1.4.1"
composer create-project --prefer-dist yiisoft/yii2-app-basic basic
  • 第一条命令安装 Composer Asset 插件,它允许通过 Composer 统一管理 Bower 与 NPM 包(Yii 的前端资源依赖)。该命令全局只需执行一次。
  • 第二条命令在名为 basic 的目录中安装 Yii 的 Basic 项目模板(即最新稳定版),你也可以自由指定其他目录名。

关于前端资源(Assets)管理的补充说明:从当前仓库的英文版安装文档(docs/guide/start-installation.md)可以看到,除了上述 Asset 插件方案外,如今更推荐通过 asset-packagist.org 或 Composer 插件两种途径之一来解析 PHP 与 CSS/JavaScript 包的版本。Yii 依赖 Bower 与 NPM 包来提供 jQuery 等前端库,并借助 Composer 在解析 PHP 依赖的同时解析前端资源版本。如果你希望完全绕过 Composer 的资源安装(例如改用 CDN 或原生 Bower/NPM 管理),可在 composer.json 中添加如下 replace 段:

"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"
}

注意:绕过 Composer 安装资源后,资源安装与版本冲突的解决责任将转移给你自己,不同扩展的资源文件之间可能出现不一致,需做好心理准备。更多细节可参考资源管理文档(英文完整版见 structure-assets.md)。

2.3 安装开发版本(可选)

若想安装最新的开发版本,可改用以下命令,它会为 Composer 添加最低稳定性(minimum-stability)选项:

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

警告:开发版本不应在生产环境使用,因为它可能破坏你正在运行的代码。

三、从归档文件安装

从归档文件安装 Yii 分为三步:

  1. 从 yiiframework.com 的下载页面下载归档文件;
  2. 将下载的文件解压到 Web 可访问的目录;
  3. 修改 config/web.php,为 cookieValidationKey 配置项填入一个密钥(使用 Composer 安装时会自动完成此步骤):
// !!! Isikan nilai key jika kosong - ini diperlukan oleh cookie validation
// 中文注释:此处为空时必须填入密钥——cookie 校验必需
'cookieValidationKey' => 'enter your secret key here',

cookieValidationKey 为什么是必需项?

从源码层面看,这一配置与 Yii 的 Cookie 校验机制直接相关。在 framework/web/Request.php 中,cookieValidationKey 是 yii\web\Request 组件的一个公开属性,默认 enableCookieValidation = true(见 Request.php#L170-L174)。当请求加载 Cookie 时,loadCookies() 方法会先检查密钥是否为空:

protected function loadCookies()
{
    $cookies = [];
    if ($this->enableCookieValidation) {
        if ($this->cookieValidationKey == '') {
            throw new InvalidConfigException(get_class($this) . '::cookieValidationKey must be configured with a secret key.');
        }
        // ...使用 Yii::$app->getSecurity()->validateData() 校验每个 cookie 值
    }
    // ...
}

也就是说,只要启用了 Cookie 校验而密钥为空,框架会直接抛出 InvalidConfigException(参见 Request.php#L1753-L1764)。密钥的作用是对每个 Cookie 值进行 HMAC 签名校验,防止客户端篡改 Cookie 内容。因此:

  • 密钥必须是一段足够长的随机字符串,切勿使用示例中的占位文本;
  • 从 Yii 2 早期版本升级时,官方在 UPGRADE.md 中同样强调必须显式配置 yii\web\Request::cookieValidationKey,且 Advanced 模板中不要把它加进 common/config 或 console/config,因为控制台应用不涉及 CSRF 校验,其请求组件没有该属性。

四、其他安装选项

上述安装步骤会同时创建一个开箱即用的基础 Web 应用,适合大多数项目(无论规模大小),尤其适合初学者。如果你有其他需求,Yii 还提供了两条备选路径:

  • 仅安装框架核心、从零构建应用:可参考从零构建应用一文;
  • 使用更复杂的、适合团队协作环境的模板:可考虑安装 Advanced 项目模板,其多层级代码组织方式更适合团队开发。

五、验证安装

5.1 使用 PHP 内置服务器快速启动

安装完成后,你可以先配置 Web 服务器(见下一节),也可以直接使用 PHP 内置的开发服务器。在项目根目录执行:

php yii serve

默认情况下 HTTP 服务器监听 8080 端口。如果该端口已被占用,或你想用这种方式同时服务多个应用,可通过 --port 参数指定端口:

php yii serve --port=8888

然后在浏览器访问:

http://localhost:8080/

php yii serve 的源码级解读

该命令由控制台控制器 framework/console/controllers/ServeController.php 实现(自 Yii 2.0.7 起提供)。几个关键点:

  • 默认端口:$port = 8080(见 ServeController.php#L38),与文档所述一致;
  • 默认文档根目录:$docroot = '@app/web',通过 Yii::getAlias() 解析为当前应用的 web 目录(见 ServeController.php#L42、#L59);
  • 可选参数:除 --port(别名 -p)外,还支持 --docroot(别名 -t)指定服务目录、--router(别名 -r)指定路由器脚本(见 ServeController.php#L115-L122);
  • 地址参数:actionIndex($address = 'localhost') 接受 host 或 host:port 格式;文档根目录不存在、路由文件不存在、地址已被占用时,会分别返回退出码 2、3、4、5(见 ServeController.php#L31-L34);
  • 底层通过 passthru() 调用 php -S {address} -t {documentRoot} <a href="https://link.gitcode.com/i/ce4a1637e6aa30734728c90b043c091c" target="_blank">router] 启动 PHP 内置服务器,启动前会用 fsockopen 探测端口是否已被占用(见 [ServeController.php#L128-L137)。

Yii 安装成功后的 Congratulations 欢迎页面

浏览器中应显示上述 "Congratulations!" 欢迎页面。如果页面未能正常显示,请检查你的 PHP 安装是否满足 Yii 的环境要求。

5.2 检查 PHP 环境要求

可通过以下任一方式检查环境是否满足 Yii 的最低要求:

  • 将项目中的 /requirements.php 复制到 /web/requirements.php,然后用浏览器访问 http://localhost/requirements.php;
  • 或在终端执行:
cd basic
php requirements.php

关于版本要求的准确说明:原安装文档给出的最低版本为 PHP 5.4 及以上。需要指出的是,该文档写作年代较早,而当前仓库核心代码的版本要求已经显著提高——framework/requirements/requirements.php 中 YiiRequirementChecker 实际执行的核心强制检查项包括:

检查项 是否强制 要求
PHP 版本 强制 PHP 7.3.0 或更高
Reflection 扩展 强制 必须可用
PCRE 扩展 强制 必须已加载
SPL 扩展 强制 必须已加载
Ctype 扩展 强制 必须已加载
MBString 扩展 强制 必须已加载(多字节字符串处理必需)
OpenSSL 扩展 可选 加密/解密方法(Security 组件)所需
Intl 扩展 可选 国际化支持,需 1.0.2+
ICU 版本 可选 49.0+,用于 Formatter 复数规则等
ICU Data 版本 可选 49.1+
Fileinfo 扩展 可选 文件上传 MIME 类型检测
DOM 扩展 可选 REST API 输出 XML 响应
IPv6 支持 可选 IpValidator::expandIPv6 所需
pcntl 可选 推荐用于 yii2-queue 的 CLI 操作

因此,建议以 PHP 7.3.0 以上版本为准进行环境准备,而不是沿用文档中 5.4 的旧标准。检查逻辑由 framework/requirements/YiiRequirementChecker.php 实现:checkYii() 加载上述 requirements.php 中的强制与可选检查项,check() 方法逐条评估并将结果汇总为 summary(含 total/errors/warnings)与逐项明细,最终通过 render() 在 Web 或控制台界面输出报告。

若应用需要数据库,还应安装 PDO PHP 扩展及对应的数据库驱动(如 MySQL 需要 pdo_mysql)。请根据检查报告配置你的 PHP 环境,使其满足 Yii 的最低要求。

六、配置 Web 服务器

提示:如果你只是想试用 Yii、暂无部署到生产服务器的打算,可暂时跳过本节。

按上述说明安装的应用,应当能在 Windows、macOS 或 Linux 上、运行 PHP 7.3.0 以上的 Apache 或 Nginx 环境中开箱即用。Yii 2.0 也曾兼容 Facebook 的 HHVM,但由于 HHVM 与原生 PHP 存在一些边界行为差异,使用 HHVM 时需要额外小心。

在生产服务器上,通常希望应用通过 https://www.example.com/index.php 访问,而不是冗长的 https://www.example.com/basic/web/index.php。实现方式是将 Web 服务器的文档根目录指向 basic/web 文件夹,并可按照路由与 URL 生成一节所述隐藏 URL 中的 index.php。

安全说明:将 basic/web 设为文档根目录,可以防止终端用户访问与 basic/web 同级的私有应用代码和敏感数据文件。拒绝访问其他文件夹本身就是一项安全增强。

补充:如果你的应用运行在无法修改 Web 服务器配置的共享主机环境中,仍可调整应用结构来提升安全性,详见共享主机环境一节。

6.1 推荐的 Apache 配置

在 Apache 的 httpd.conf 文件或虚拟主机配置中使用如下配置,并将 path/to/basic/web 替换为 basic/web 的实际路径:

# Set document root to be "basic/web"
DocumentRoot "path/to/basic/web"

<Directory "path/to/basic/web">
    # use mod_rewrite for pretty URL support
    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>

6.2 推荐的 Nginx 配置

使用 Nginx 时,需要以 FPM SAPI 方式安装 PHP。以下配置中,请将 path/to/basic/web 替换为 basic/web 的实际路径,将 mysite.test 替换为实际要服务的域名:

server {
    charset utf-8;
    client_max_body_size 128M;

    listen 80; ## listen for ipv4
    #listen [::]:80 default_server ipv6only=on; ## listen for 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 / {
        # Redirect everything that isn't a real file to index.php
        try_files $uri $uri/ /index.php$is_args$args;
    }

    # uncomment to avoid processing of calls to non-existing static files by 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() 调用、提升性能。

补充:若你的应用运行在反向代理之后,可能还需要在 request 组件中配置可信代理与头信息,详见 runtime-requests.md 的 "Trusted proxies and headers" 小节(英文版文档)。

6.3 HTTPS 环境下的注意事项

当服务器以 HTTPS 运行时,需要额外添加 fastcgi_param HTTPS on;,这样 Yii 才能正确检测到连接是安全的(例如在生成绝对 URL 时正确使用 https 协议)。这与 Yii 的请求组件对安全连接的判断逻辑直接相关——框架正是通过检查 HTTPS 相关服务器变量来确定当前请求是否加密传输。

七、结语

至此,你已经掌握了 Yii 2 安装与部署的完整链路:从选择 Composer 或归档文件两种安装方式,到通过 php yii serve 快速验证、用 requirements.php 检查 PHP 环境,再到为生产环境配置 Apache 或 Nginx 并理解 cookieValidationKey 与文档根目录背后的安全设计。文中涉及的 ServeController、Request::loadCookies()、YiiRequirementChecker 等源码均可在本仓库 framework/console/controllers/ServeController.php、framework/web/Request.php、framework/requirements/ 中继续深入研读,英文版安装文档见 docs/guide/start-installation.md。下一步,你可以参考从零构建应用或路由与 URL 生成等章节,开始基于 Basic 模板构建自己的业务功能。

登录后查看全文
yii2