Yii 2 安装完全指南:Composer 与归档安装、环境验证及 Apache/Nginx/NGINX Unit/IIS 配置
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 等扩展——这些也是下文环境校验的核心依据。
二、通过归档文件安装
归档安装只需三步:
- 从 yiiframework.com 下载归档文件;
- 将归档解压到 Web 可访问的目录;
- 编辑
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 的场景。此外还有两条路线:
- 只安装核心框架、从零构建整个应用:参考从零构建应用;
- 从更适合团队开发的高级模板起步:安装 Advanced Project Template。
四、安装资源包(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!" 页面:
如果未出现,请检查 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。
七、安装后可以做什么
安装并验证完成后,推荐按以下顺序继续学习:
- 了解应用整体结构与生命周期:应用结构;
- 学习路由与 URL 生成(含
enablePrettyUrl、showScriptName的完整配置):路由与 URL 生成; - 接入数据库:使用数据库;
- 在模板之上实现新功能,可跟随从零构建应用或官方入门系列的后续章节。
至此,你已经掌握了 Yii 2 的完整安装链路:选择 Composer 或归档方式、理解 cookieValidationKey 的安全含义、用 php yii serve 快速验证、通过需求检查器排查环境,并能在 Apache、Nginx、NGINX Unit 与 IIS 上以 web/ 为文档根目录进行安全部署。
