企业官网建设流程全解析

Yii 2 安装完全指南：Composer 与归档两种方式、环境验证及 Apache/Nginx 生产部署配置

【免费下载链接】yii2Yii 2: The Fast, Secure and Professional PHP Framework项目地址: https://gitcode.com/gh_mirrors/yi/yii2

本篇指南基于 Yii 2 官方文档的《Yii 安装》一章（docs/guide-uk/start-installation.md，本文以其为核心骨架，并参考同主题英文版及框架源码）整理而成。你将掌握：通过 Composer 或归档文件安装 Yii 2 的完整步骤、安装后如何借助php yii serve内置服务器与 requirements 检查脚本验证环境、以及在生产服务器上配置 Apache / Nginx（含 NGINX Unit、IIS 等补充方案）将文档根目录指向web/目录并隐藏index.php的关键配置。读完本文，你可以独立完成一个 Yii 2 基础模板项目的从零安装到上线部署。

安装方式总览：Composer 与归档文件

Yii 2 提供两种安装路径：

1. 使用 Composer 包管理器（官方推荐）：一条命令即可完成框架与项目模板的安装，后续安装新扩展或升级 Yii 也只需执行一条命令。
2. 下载归档文件：从官网手动下载并解压，适合无法使用 Composer 的环境。

标准安装完成后，你获得的不仅是框架本体（本仓库 framework/ 目录即框架源码，composer 包名为yiisoft/yii2，见 framework/composer.json），还有一个项目模板——一个开箱即用的 Yii 工作项目，已实现用户登录/退出、联系表单等基础功能，代码按推荐方式组织，是绝佳的项目起点。

Yii 提供两种模板：

• 基础项目模板（Basic Project Template）：适合约 90% 的 Web 应用开发，与高级模板的主要区别在于代码组织方式。新手强烈建议从基础模板入手，它简单但功能完备。
• 高级项目模板（Advanced Project Template）：代码分层更细（常见为 frontend/backend/console 等多入口结构），更适合团队协作环境下的复杂应用开发。

本文及后续章节围绕基础项目模板展开讲解。

使用 Composer 安装

第一步：安装 Composer

如果尚未安装 Composer，Linux 和 macOS 用户执行以下命令：

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

Windows 用户则下载并运行 Composer-Setup.exe 安装程序。

本文所有 Composer 命令均假设已全局安装，可直接使用composer命令；如果你使用的是本地目录下的composer.phar，需相应调整示例命令。若之前已装过 Composer，请先确保版本足够新：执行composer self-update。

注意：安装 Yii 过程中，Composer 需要从 GitHub API 获取大量包信息，请求量可能超过 GitHub API 速率限制。若触发限制，Composer 会要求输入 GitHub 账号凭据以换取访问令牌，从而提升 API 配额。建议在安装 Yii 之前预先配置好访问令牌。

第二步：创建项目

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

composer global require "fxp/composer-asset-plugin:^1.4.1" composer create-project --prefer-dist yiisoft/yii2-app-basic basic

第一条命令安装 composer-asset-plugin 插件，使 Composer 能够管理 Bower 与 NPM 包依赖（该命令只需执行一次）；第二条命令将 Yii 安装到名为basic的目录，目录名可按需更改。

说明：随着生态演进，目前更常见的做法是借助 asset-packagist.org 托管前端资源包，或直接在composer.json中声明replace规则跳过 Composer 安装资源，两种思路详见下文「资源依赖的管理」小节。若composer create-project失败，可参考 Composer 官方排错文档修复错误后，在basic目录内执行composer update续传中断的安装。

安装最新开发版

若想体验最新开发版（非稳定版），可添加--stability=dev选项：

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

⚠️ 开发版不应部署到生产服务器，它可能破坏线上代码的稳定性。

资源依赖的管理

Yii 依赖 Bower / NPM 包提供 CSS 与 JavaScript 资源库，并通过 Composer 统一获取，使 PHP 与前端包版本在同一时刻解析。如果希望完全跳过 Composer 的资源安装（改用原生 Bower/NPM 客户端、CDN，或自行管理），可在composer.json中加入：

"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 安装资源后，你需要自行负责资源的安装与版本冲突解决，不同扩展的资源文件之间可能出现不一致。

关于资源体系的更多细节，可进一步阅读资源（Assets）文档。

从归档文件安装

归档安装只需三步：

1. 从官网下载 Yii 归档文件；
2. 将归档解压到 Web 可访问的目录；
3. 编辑config/web.php，为cookieValidationKey配置项填入一个秘密密钥（使用 Composer 安装时会自动生成，手工归档安装必须手动填写）：

// !!! 在下面填入一个秘密密钥（如果为空）——cookie 校验必需 'cookieValidationKey' => 'enter your secret key here',

为什么这个密钥如此重要？从源码看，framework/web/Request.php 的loadCookies()方法在启用 cookie 校验（enableCookieValidation）时，会用该密钥通过Yii::$app->getSecurity()->validateData()校验每个请求 cookie 的签名；若cookieValidationKey为空字符串，将直接抛出InvalidConfigException（提示 "cookieValidationKey must be configured with a secret key."，见 framework/web/Request.php）。也就是说，不配置此密钥，任何依赖 cookie 的功能（登录态、CSRF 防护等）都会失败，务必使用足够长且随机的字符串。

其他安装选项

上述流程适合绝大多数项目（无论大小），尤其适合刚开始学习 Yii 的开发者。若需要其他形态：

• 只想要框架本体、从零搭建应用：参考从零开始构建应用一节的指引；
• 想要更复杂的、适合团队协作的应用骨架：考虑安装高级项目模板（Advanced Project Template）。

验证安装是否成功

安装完成后，可配置 Web 服务器（见下节），或直接使用PHP 内置 Web 服务器，在项目根目录执行：

php yii serve

注意：默认监听 8080 端口。若端口被占用，或想同时运行多个应用，可用--port参数指定端口：

php yii serve --port=8888

该命令由 framework/console/controllers/ServeController.php 实现：其actionIndex()方法将docroot（默认@app/web）与地址拼装后交给 PHP 内置服务器（php -S），并打印 "Server started on http://…" 提示；还支持--docroot（别名-t）、--port（别名-p）、--router（别名-r）等选项。端口被占用、文档根目录不存在、路由文件缺失时，会分别返回不同的退出码（见 framework/console/controllers/ServeController.php）。若需从虚拟机等远程机器访问，可用0.0.0.0:8000形式指定监听地址。

启动后，用浏览器访问：

http://localhost:8080/

你应当看到 "Congratulations!" 欢迎页。如果页面未正常显示，请检查 PHP 环境是否满足 Yii 的最低要求，可通过以下任一方式检测：

• 将/requirements.php复制到/web/requirements.php，用浏览器访问http://localhost/requirements.php；

• 在控制台执行：

  cd basic php requirements.php

关于 PHP 版本要求的说明：原文档写作时要求 PHP 5.4 及以上（并建议使用 PHP 7），但以当前仓库的实际源码为准——framework/requirements/requirements.php 已将必选（mandatory）条件设为 PHP 7.3.0 或更高，同时必选Reflection、PCRE、SPL、Ctype、MBString扩展；OpenSSL（加密解密组件）、Intl（国际化、Yii::t()高级参数格式化、EmailValidator/UrlValidator的 IDN 支持等）为可选扩展，但建议安装以启用对应能力。完整清单及说明都在该 requirements 脚本中，检测逻辑由 framework/requirements/YiiRequirementChecker.php 提供，控制台与 Web 两种报告视图分别位于 framework/requirements/views/console/index.php 与 framework/requirements/views/web/index.php。

如果应用需要连接数据库，还必须安装PDO PHP 扩展及对应驱动（例如 MySQL 使用pdo_mysql）。本仓库的 tests 目录中提供了docker-compose.mysql.yml、docker-compose.pgsql.yml、docker-compose.mssql.yml、docker-compose.oracle.yml等容器化数据库测试环境，可作为参考。

配置 Web 服务器

提示：如果只是试用 Yii、暂无部署计划，可先跳过本节。

按上文安装的应用可开箱即用地运行于 Apache 或 Nginx（Windows、macOS、Linux 皆可）。生产环境中，你可能希望访问地址从https://www.example.com/basic/web/index.php简化为https://www.example.com/index.php——这需要把 Web 服务器的文档根目录（document root）指向basic/web，并可进一步隐藏 URL 中的index.php（方法见路由与 URL 创建一节）。

安全提示：将basic/web设为文档根目录后，位于其同级目录下的私有应用代码与敏感数据文件将无法被终端用户直接访问，这是一项重要的安全改进。

若应用运行在无法修改服务器配置的虚拟主机环境，仍可通过调整应用目录结构提升安全性，参考虚拟主机环境一节。

推荐的 Apache 配置

在 Apache 的httpd.conf或虚拟主机配置中添加以下内容（将path/to/basic/web替换为实际路径）：

# 将文档根目录设置为 "basic/web" DocumentRoot "path/to/basic/web" <Directory "path/to/basic/web"> # 使用 mod_rewrite 支持美观 URL RewriteEngine on # 若 UrlManager 中 showScriptName 为 false，禁止带脚本名访问 RewriteRule ^index.php/ - [L,R=404] # 若请求的文件或目录真实存在，则直接处理 RewriteCond %{REQUEST_FILENAME} !-f RewriteCond %{REQUEST_FILENAME} !-d # 否则将请求转发到 index.php RewriteRule . index.php # ...其他设置... </Directory>

RewriteCond %{REQUEST_FILENAME} !-f与!-d保证真实存在的静态文件不被重写，只有不存在的路径才交给index.php前端控制器处理；RewriteRule ^index.php/ - [L,R=404]则在开启美观 URL 后拒绝通过带脚本名的形式访问，避免重复内容与潜在暴露。

推荐的 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 才能正确识别连接是否加密（这会影响安全链接判断与 URL 生成）。

补充方案：NGINX Unit 与 IIS

NGINX Unit（带 PHP 语言模块）也能运行 Yii 应用，示例配置要点：监听 80 端口并将路由yii的匹配规则设定为「排除/assets/*，仅匹配*.php与*.php/*」，非 PHP 请求则回退到静态文件共享目录并最终 fallback 到index.php，PHP 应用目标分别定义direct（直接按 root 提供）与index（指定script: "index.php"）两个 target：

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

IIS方案建议：将应用放入文档根目录指向path/to/app/web的虚拟主机（Web 站点）并配置运行 PHP，然后在web目录放置web.config，通过 URL Rewrite 模块将所有「非真实文件/目录」的请求重写为index.php：

<?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>

安装完成之后

至此，你的 Yii 2 基础模板应用已可运行。后续可继续阅读本指南的后续章节：配置数据库、创建表单、使用 Gii 代码生成器快速搭建 CRUD，以及理解应用结构与请求生命周期，逐步从「装好」走向「用好」。

【免费下载链接】yii2Yii 2: The Fast, Secure and Professional PHP Framework项目地址: https://gitcode.com/gh_mirrors/yi/yii2