Yii 2 安装完全指南:Composer 与归档安装、环境校验及 Apache/Nginx 生产配置
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 分为三步:
- 从 yiiframework.com 的下载页面下载归档文件;
- 将下载的文件解压到 Web 可访问的目录;
- 修改
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)。
浏览器中应显示上述 "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 模板构建自己的业务功能。
