企业官网建设流程全解析

• 后端
• Web框架

本篇技术指南以 Yii 2 官方文档的安装章节（乌兹别克语版 docs/guide-uz/start-installation.md）为核心骨架，结合仓库内framework/的源码实现进行佐证，系统讲解 Yii 2 的两种标准安装路径（Composer 与归档包）、安装完成后的环境自检方法，以及将 Basic 项目模板部署到 Apache 与 Nginx 的推荐配置。读完本文，你将掌握从零搭建一个可直接运行的 Yii 2 基础应用、验证其运行环境、并在生产服务器上安全部署的完整实战能力。

一、两种安装方式总览：Composer 还是归档包

Yii 2 提供了两种官方安装方式：

1. 通过 Composer 包管理器安装（推荐）：Composer 是 PHP 生态的事实标准依赖管理工具。选择这种方式，你后续可以通过一条命令安装新的扩展、或者一键升级 Yii 本身，维护成本最低。
2. 通过归档包（zip/tar 压缩包）安装：从官网下载现成的应用压缩包解压使用，适合无法使用 Composer 的受限环境。

需要特别说明的是，Yii 2 的标准安装与 Yii 1 不同：一次安装会同时下载「框架核心」与「项目模板」两部分。所谓项目模板，就是一个可运行、自带基础功能的 Yii 工程，例如登录、联系表单、Gii 代码生成器等，其目录组织方式即官方推荐的最佳实践，可直接作为你新项目的起点。

本指南以及后续的 start-hello.md、start-workflow.md 等章节，均以Basic 项目模板（yiisoft/yii2-app-basic）为基础展开。Yii 还提供另一个Advanced 项目模板（yii2-app-advanced），更适合多团队、多应用分层的协作开发场景，将在后文「其他安装选项」中说明。

二、方式一：通过 Composer 安装（推荐）

2.1 先安装 Composer 本身

如果系统尚未安装 Composer，请参照 getcomposer.org 官方下载页 的指引操作。在 Linux 或 macOS 上，典型安装命令如下：

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

在 Windows 上，直接下载并运行 Composer-Setup.exe 安装程序即可。

遇到问题可查阅 Composer 官方文档的 「疑难解答」章节；如果你是 Composer 新手，建议至少通读 「基本用法」章节。

注意：本指南中的全部composer命令均假设 Composer 已全局安装，即可以直接以composer命令调用。如果你使用的是项目目录内的composer.phar，请相应地将命令中的composer替换为php composer.phar。

如果此前已安装过旧版 Composer，请先通过composer self-update将其更新到最新版本。

2.2 关于 GitHub API 速率限制的注意事项

安装 Yii 的过程中，Composer 需要从 GitHub API 拉取大量依赖元数据。请求量取决于你应用依赖的包数量，有可能超过 GitHub API 的匿名速率限制。一旦触发限制，Composer 可能会提示你输入 GitHub 账号密码以换取 API 访问令牌（token）。在网速较快的情况下，该限制可能在 Composer 自行处理前就被触发，因此官方建议在安装 Yii 之前就预先配置好 GitHub API 访问令牌，具体步骤见 Composer 官方文档中关于 GitHub API 令牌的说明。

2.3 创建 Yii 基础项目模板

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

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

该命令会将 Yii 最新稳定版的项目模板安装到名为basic的目录中（目录名可随意更换）。--prefer-dist表示优先下载打包好的 dist 压缩包，安装更快、更省带宽。

提示：如果composer create-project命令执行失败，请参考 Composer 疑难解答文档 排查常见错误。修复问题后，可进入basic目录运行composer update继续完成被中断的安装。

进阶：若想安装 Yii 的最新开发版（未经充分测试），可增加--stability=dev参数：

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

切勿在生产服务器上使用开发版——未经测试的代码随时可能引发运行故障。

从当前仓库的源码可以印证 Composer 安装链条的底层依赖：框架核心 framework/composer.json 声明了php >= 7.4.0的硬性要求，并依赖yiisoft/yii2-composer插件（负责模板初始化与扩展安装机制），同时直接声明了bower-asset/jquery、bower-asset/inputmask、bower-asset/punycode、bower-asset/yii2-pjax等前端资源包——这说明 Yii 2 是通过 Composer 统一解析 PHP 包与前端 CSS/JavaScript 资源版本的。

三、方式二：从归档包安装

从归档包安装 Yii 仅需三步：

1. 从 yiiframework.com 下载页 下载归档文件；
2. 将下载的压缩包解压到 Web 可访问的目录中；
3. 修改config/web.php，为cookieValidationKey配置项填入一个自定义的密钥（使用 Composer 安装时此步骤会自动完成）：

// !!! insert a secret key in the following (if it is empty) - this is required by cookie validation 'cookieValidationKey' => 'enter your secret key here',

不要小看这第三个步骤。从源码看，cookieValidationKey是 Cookie 校验签名的关键配置：在 framework/web/Request.php 中，当enableCookieValidation开启而cookieValidationKey为空字符串时，会直接抛出InvalidConfigException；framework/web/Response.php 在写出 Cookie 时同样会读取该校验密钥进行 HMAC 签名。也就是说，没有这个密钥，Yii 的 Cookie 校验机制将无法工作。enter your secret key here只是占位符，请务必替换为足够长且随机的真实密钥。

四、其他安装选项

上述两种方式安装的都是「开箱即用的完整 Web 应用」，对于大多数项目（无论大小）都是很好的起点，尤其适合刚开始学习 Yii 的开发者。除此之外还有两种差异化选择：

• 只要框架、从零搭建应用：如果你仅需要框架核心，希望完全从空目录开始构建自己的应用结构，请参照 从零开始构建应用 章节的操作指引。
• 面向团队协作的高级模板：如果你希望以更复杂的工程结构起步（更适合多人团队、多应用分层的开发环境），可考虑使用Advanced 项目模板（yiisoft/yii2-app-advanced）。

补充：Yii 依赖 Bower/NPM 生态的前端资源库，并通过 Composer 统一获取，这样 PHP 与 CSS/JavaScript 的版本可以在同一时刻解析、保持一致。若你希望自行通过原生 Bower/NPM、CDN 管理资源，或完全跳过资源安装，可在项目的composer.json中加入replace字段屏蔽相关bower-asset/*包。采用这种方式时，资源安装与版本冲突的解决需要你自行负责。

五、验证安装是否成功

安装完成后，若尚未配置 Web 服务器，可在项目根目录使用PHP 内置 Web 服务器快速启动应用：

php yii serve

该命令对应框架源码中的 framework/console/controllers/ServeController.php，其actionIndex()方法内部会调用 PHP 内置服务器（php -S）。从源码可见其默认行为与可调参数：

• 默认监听localhost:8080（$port = 8080）；
• 默认文档根目录为@app/web路径别名（$docroot = '@app/web'）；
• 若 8080 端口被占用或需同时启动多个应用，可用--port参数指定端口，例如php yii serve --port=8888；
• 还支持--docroot（或-t）与--router（或-r）参数指定文档根目录与路由脚本，并可通过0.0.0.0:8000这样的地址让局域网/虚拟机外部机器访问。

启动后，用浏览器访问安装好的 Yii 应用：

http://localhost:8080/

若你已将basic目录部署到 Web 服务器的根目录下（服务器运行在本机localhost），则通过以下 URL 访问（可能需要预先调整服务器配置）：

http://localhost/basic/web/index.php

此时你应该能看到下面的 "Congratulations!"（恭喜！）欢迎页面：

如果页面没有正常显示，请检查 PHP 安装是否满足 Yii 的最低要求，可通过以下两种方式之一进行检测：

• 在浏览器中打开http://localhost/basic/requirements.php；
• 或在终端执行：

cd basic php requirements.php

原文档写作时期要求 PHP 5.4 及以上。以当前仓库为准，框架核心 framework/composer.json 已要求php >= 7.4.0；而 framework/requirements/requirements.php 中强制项（mandatory）检查为PHP 7.3.0 及以上，同时强制要求Reflection、PCRE、SPL、Ctype、MBString扩展，可选扩展包括OpenSSL（加密/解密）、Intl+ICU（国际化格式化）、Fileinfo（文件上传 MIME 检测）、DOM（REST XML 响应）、IPv6（IP 校验扩展）以及pcntl（队列类 CLI 操作）。具体版本要求请以你实际安装的 Yii 版本所附的 requirements 检查结果为准。

如果应用需要连接数据库，还应安装 PDO PHP 扩展 及对应的数据库驱动（如 MySQL 对应pdo_mysql）。

六、Web 服务器配置（生产部署）

提示：如果你目前只是在本机试用 Yii、暂无部署到生产服务器的计划，可以暂时跳过本节。

按照上述方式安装的应用，在 Windows、macOS、Linux 上搭配 PHP 5.4+（当前仓库要求见上节）的 Apache 或 Nginx 均可开箱即用。Yii 2.0 亦兼容 HHVM，但 HHVM 在某些边界场景下与原生 PHP 行为存在差异，使用时应格外留意。

在生产服务器上，你可能希望应用通过https://www.example.com/index.php而非https://www.example.com/basic/web/index.php访问。实现方法是将 Web 服务器的文档根目录（DocumentRoot / root）指向basic/web文件夹；此外，还可以按 URL 解析与创建 章节的描述隐藏 URL 中的index.php。

安全收益：将文档根目录设置为basic/web后，用户将无法直接访问位于basic/web同级目录中的私有应用代码与敏感数据文件，这是一项重要的安全加固。

如果你的应用运行在无法修改 Web 服务器配置的共享主机上，可参照 共享主机环境部署 章节调整应用结构以提升安全性。

若应用运行在反向代理之后，可能还需要在请求组件中配置可信代理与请求头。

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（pretty 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>

6.2 推荐的 Nginx 配置

使用 Nginx 时，PHP 需要以 FPM SAPI 方式运行。参考以下配置，并将path/to/basic/web替换为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; # 禁止通过 PHP 执行 /assets 目录下的脚本 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; } # 拒绝访问所有点开头的隐藏文件（.ht、.svn、.git 等） location ~* /\. { deny all; } }

使用该配置时，建议同时在php.ini中设置cgi.fix_pathinfo=0，以避免产生大量不必要的系统stat()调用，从而提升性能。

另外，当站点启用 HTTPS 时，需要额外添加fastcgi_param HTTPS on;，Yii 才能正确判断当前连接是否为安全连接。

补充说明：原乌兹别克语版文档给出的 Nginxlocation /使用try_files $uri $uri/ /index.php?$args;的写法，并在\.php$块中include fastcgi.conf;；上文采用英文版同源文档中更完整的新写法（显式传递SCRIPT_FILENAME并追加try_files $uri =404;），两种写法原理一致，按你的服务器环境选择即可。

总结

本文完整覆盖了 Yii 2 的两条标准安装路径：

• Composer 方式（推荐）：一条composer create-project命令即完成框架与 Basic 模板的整体安装，后续可通过 Composer 方便地安装扩展与升级，建议安装前先配置 GitHub API 令牌以避免速率限制；
• 归档包方式：三步完成部署，核心在于必须为config/web.php中的cookieValidationKey配置随机密钥，否则 Cookie 校验（对应 Request.php 的强制校验逻辑）将无法工作。

安装完成后，可通过php yii serve（源码见 ServeController.php）或requirements.php快速验证运行环境，再依据本文给出的 Apache / Nginx 推荐配置，将文档根目录收敛到basic/web完成安全的生产部署。接下来可以继续阅读 start-hello.md 编写第一个 "Hello World" 页面，或通过 start-databases.md 接入数据库，逐步进入 Yii 2 的实战开发。

• 后端
• Web框架