Yii 2 框架核心包（yiisoft/yii2）安装指南与框架结构解析-平芜编程栈

后端
Web框架

【免费下载链接】yii2

Yii 2: The Fast, Secure and Professional PHP Framework

项目地址：https://gitcode.com/gh_mirrors/yi/yii2

Yii 2 是目前 Yii 框架家族中应用最广的稳定版本，其核心框架代码以yiisoft/yii2包的形式通过 Composer 分发。本文以 framework/README.md 为骨架，完整讲解该核心包的安装方式、依赖要求与版本约束，并结合当前仓库源码（framework/composer.json、framework/Yii.php、framework/BaseYii.php 等）深入剖析安装完成后的框架目录结构、自动加载机制与入口引导流程，帮助读者从"装得上"进阶到"看得懂"。

一、Yii 2 核心框架包是什么

yiisoft/yii2是 Yii 2 框架的核心代码包。根据 framework/README.md 的定位说明：

该目录承载的是 Yii 2核心框架本体（framework/目录），即 MVC 基础设施、数据库层、Web 组件、控制台工具等实现；
该仓库是主仓库的只读 git subsplit，代码持续与主仓库同步；
框架以 BSD-3-Clause 协议开源，许可证全文见 framework/LICENSE.md。

当前仓库根目录的 composer.json 是开发环境用的yiisoft/yii2-dev包，它通过"replace": {"yiisoft/yii2": "self.version"}与核心包互相替代，并将yii\命名空间映射到framework/目录：

"autoload": { "psr-4": { "yii\\": "framework/" } }

也就是说：用户项目安装的是yiisoft/yii2（框架核心包），开发者本地调试框架本体时使用的是yiisoft/yii2-dev，两者代码同源。

二、通过 Composer 安装核心包

官方推荐的安装方式是使用 Composer（安装方法见 start-installation.md 中的"Installing Composer"一节）。两种等价方式如下。

方式一：命令行直接安装

composer require yiisoft/yii2

该命令会解析依赖、写入composer.json的require段并执行安装，生成vendor/yiisoft/yii2/目录。

方式二：手动编辑 composer.json

在项目根目录composer.json的require段中加入：

{ "require": { "yiisoft/yii2": "~2.0.0" } }

然后执行：

composer update

~2.0.0是语义化版本约束，含义为"允许 2.0.x 系列内的小版本更新（>= 2.0.0 且 < 2.1.0）"，这是 Yii 官方在 framework/README.md 中给出的标准写法。若想锁定具体版本，也可以写成~2.0.55或2.0.55.*等形式。

资源（Assets）的安装方式选择

框架依赖 jQuery、Inputmask、punycode、yii2-pjax 等 Bower/NPM 前端资源包（见 framework/composer.json 的require段）。安装这些资源需要配置 Bower/NPM 资源安装方式，官方文档详见 structure-assets.md 的 "Bower 与 NPM 资源安装" 一节。常见做法是在项目根 composer.json 中配置asset-packagist.org仓库（当前仓库根 composer.json 即采用此方式）。

三、环境要求与依赖关系

依据 framework/composer.json，核心包的运行要求如下：

依赖	要求	说明
PHP	`>= 7.4.0`	2.0.x 系列对 PHP 版本的底线要求
ext-mbstring	`*`	多字节字符串处理扩展
ext-ctype	`*`	字符类型检查扩展
lib-pcre	`*`	PCRE 正则库
yiisoft/yii2-composer	`~2.0.4`	Composer 插件，负责资源安装与扩展安装器
ezyang/htmlpurifier	`^4.17`	HTML 安全过滤，用于表单与输出安全
cebe/markdown	`~1.0.0 \\| ~1.1.0 \\| ~1.2.0`	Markdown 解析，用于辅助文档渲染

生产环境中除上述必选依赖外，根据实际功能还可能用到ext-pdo（数据库）、ext-openssl（加密）等扩展，具体取决于应用使用的组件。

四、安装后的框架结构速览

安装yiisoft/yii2后，vendor/yiisoft/yii2/目录即对应本仓库的 framework/ 目录，核心结构如下：

Yii.php：全局入口类文件，注册自动加载并初始化 DI 容器；
BaseYii.php：yii\BaseYii的实现，承载别名、自动加载、对象创建、日志等底层能力；
classes.php：核心类映射表（class map），将yii\base\Action等 430 个类映射到具体文件路径；
yii：控制台应用引导脚本（bin）；
base/：基础类，包括 Application.php、Component.php、Controller.php、Model.php 等 50 个文件；
web/：Web 组件，如 Request、Response、UrlManager、AssetManager 等；
console/：控制台组件与内建命令；
db/：数据库访问层（DAO、Query Builder、ActiveRecord、迁移）；
caching/、log/、i18n/、validators/、helpers/、widgets/、filters/、grid/、rest/、rbac/、test/、mail/、mutex/等：按职责划分的组件目录。

从类映射文件 framework/classes.php 可以看到，核心包采用"类映射 + PSR-4"双重加载策略，例如yii\base\Application直接映射到YII2_PATH/base/Application.php，保证高频核心类零开销加载。

五、入口引导与自动加载原理

安装完成后，入口脚本只需引入 Composer 的vendor/autoload.php与框架的Yii.php即可启动框架：

<?php require __DIR__ . '/vendor/autoload.php'; require __DIR__ . '/vendor/yiisoft/yii2/Yii.php'; $config = require __DIR__ . '/config/web.php'; (new yii\web\Application($config))->run();

framework/Yii.php 只做三件事：

引入 BaseYii.php 并继承之，得到一个可被用户项目替换扩展的全局Yii类；
通过spl_autoload_register(['Yii', 'autoload'], true, true)注册 Yii 自己的自动加载器；
加载classes.php类映射表，并实例化yii\di\Container依赖注入容器。

其中Yii::autoload()（见 BaseYii.php）的加载流程是：

先在$classMap（classes.php）中查找类名对应的文件路径，若路径以@开头则先经getAlias()解析为真实路径；
未命中映射时，若类名含命名空间（如yii\web\Request），则按@yii/web/Request.php的别名规则推导文件路径（@yii默认指向框架安装目录，见 BaseYii.php）；
调试模式（YII_DEBUG）下若文件加载后类仍不存在，抛出UnknownClassException提示"命名空间缺失"。

这套机制保证了框架类既可以被快速精确加载（类映射），又允许第三方扩展通过别名扩展命名空间（如@yii/bootstrap指向独立扩展目录）。

六、核心常量与配置入口

framework/BaseYii.php 在文件顶部定义了影响全局行为的关键常量，理解它们有助于正确配置运行环境：

常量	默认值	含义
`YII_BEGIN_TIME`	`microtime(true)`	应用启动时间戳，用于性能统计
`YII2_PATH`	框架安装目录	框架根路径，类映射文件大量使用
`YII_DEBUG`	`false`	是否开启调试模式
`YII_ENV`	`'prod'`	运行环境，可为`prod`、`dev`、`test`、`staging`等
`YII_ENV_PROD`/`YII_ENV_DEV`/`YII_ENV_TEST`	由`YII_ENV`推导	便捷的布尔判断常量
`YII_ENABLE_ERROR_HANDLER`	`true`	是否启用框架内置错误处理器

这些常量应在入口脚本中、引入 Yii 之前定义，例如：

defined('YII_DEBUG') or define('YII_DEBUG', true); defined('YII_ENV') or define('YII_ENV', 'dev');

同时 BaseYii.php 提供了Yii::createObject()，它接受类名、配置数组或可调用对象三种形式创建实例，并交由 DI 容器完成依赖注入——这是框架"配置驱动"特性的基石，例如：

$db = Yii::createObject([ 'class' => 'yii\db\Connection', 'dsn' => 'mysql:host=127.0.0.1;dbname=demo', 'username' => 'root', 'password' => '', 'charset' => 'utf8', ]);

七、控制台引导脚本

framework/yii 是框架自带的控制台引导脚本（Composerbin中登记为yii），安装后可通过vendor/bin/yii调用。其工作流程（framework/yii）：

默认开启YII_DEBUG；
依次探测vendor/autoload.php的位置（兼容框架源码仓库与 Composer 全局安装两种形态）；
引入Yii.php，创建yii\console\Application实例（id为yii-console，控制器命名空间为yii\console\controllers）；
将探测到的 vendor 路径注入应用并运行，返回退出码。

执行示例：

vendor/bin/yii help

由于该脚本面向框架自带的控制台命令（如migrate、fixture等），常规项目建议在应用入口中自行配置控制台应用，而非直接依赖此脚本。

八、版本信息与升级

当前框架版本可通过Yii::getVersion()获取，见 framework/BaseYii.php，本仓库对应版本为2.0.56-dev（开发版）；
各版本的变更记录见 framework/CHANGELOG.md，其中 2.0.55（2026-05-09 发布）起包含大量 PHPDoc 泛型注解修正、PHP 8.6 兼容性调整等；
升级说明见 framework/UPGRADE.md：常规升级只需在 composer.json 中更新版本约束并执行composer update。例如：

composer require "yiisoft/yii2:~2.0.55" --update-with-dependencies

升级前建议阅读 framework/UPGRADE.md 确认是否存在破坏性变更，并为项目做好备份。

九、许可证

十、验证安装与下一步

安装完成后，可通过以下方式验证：

# 检查框架是否出现在 vendor 目录 ls vendor/yiisoft/yii2 # 查看框架版本 php -r "require 'vendor/autoload.php'; require 'vendor/yiisoft/yii2/Yii.php'; echo Yii::getVersion();"

接下来可继续阅读 start-workflow.md（应用生命周期）与 structure-overview.md（目录结构总览），结合 framework/base/Application.php 与 framework/web/Application.php 的源码，从入口配置开始构建你的第一个 Yii 2 应用。