Yii框架如何创建项目？快速上手教程

本文详解了使用 Composer 创建 Yii 项目这一唯一可靠且官方强制推荐的方式，彻底摒弃手动复制 framework 文件夹等过时做法；文章不仅提供了创建基础版与高级版项目的标准命令、关键前置条件（如 PHP 版本、Composer 状态、目录权限），还深入解释了为何必须依赖 Composer 管理自动加载与依赖结构，并明确指出项目初始化后必须立即完成的三项关键配置——确保 runtime 和 assets 目录可写、正确配置数据库连接、严格通过 web/ 子目录访问应用，同时梳理了常见启动失败的根源与精准排查路径，帮助开发者避开从第一步就埋下的典型陷阱。

直接用 composer create-project 创建，别手动拷 framework 文件夹——那是 Yii 1 的老路子，现在 Yii 2/3 全靠 Composer 管理依赖和生命周期，硬搬旧方式会卡在 autoload、类找不到、迁移命令失效等一堆问题上。

用 Composer 创建 Yii 项目（推荐且唯一可靠方式）

Yii 官方已弃用 yiic webapp 这类脚本，所有稳定版本（包括 Yii 2.0.48+ 和 Yii 3.x）都要求通过 Composer 初始化。执行前确认：

• php -v 输出 ≥ 7.4（Yii 2.0.46+ 要求 PHP 7.4；Yii 3 要求 PHP 8.0+）
• composer --version 可正常输出，且未被代理或镜像源阻断
• 当前目录有写权限，不放在系统保护路径如 C:\Program Files 下

运行命令创建基础项目：

composer create-project yiisoft/yii2-app-basic myproject

若需前后端分离结构（如 admin + frontend），改用：

composer create-project yiisoft/yii2-app-advanced myproject

注意：不要加 --prefer-dist 参数——它可能拉取损坏的压缩包缓存，首次构建建议省略，让 Composer 直接 clone 完整 git 历史以保一致性。

为什么不能复制 framework 文件夹？

因为 Yii 2+ 不再是“单文件夹即框架”，而是由 Composer 自动注册 PSR-4 自动加载规则，并依赖 vendor/autoload.php 驱动整个应用。手动复制 framework 会导致：

• php yii migrate 报错 Class 'yii\console\Application' not found
• require_once('framework/yii.php') 失败（路径不对、常量未定义、YII_DEBUG 未设）
• Gii、Debug Toolbar 等扩展无法注册——它们的安装和启用全靠 composer.json 中的 require-dev 和配置文件联动

你看到的 framework/ 目录，在 Yii 2+ 中实际已拆进 vendor/yiisoft/yii2/，连命名空间都变了（yii\ → Yii\\ 或 Yiisoft\\）。

创建后必须立刻处理的三件事

项目生成完不是终点，以下操作漏掉任一，接下来跑不起来：

• 确保 runtime/ 和 web/assets/ 目录可写（Linux/macOS 执行 chmod 777 runtime web/assets；Windows 检查 IIS 用户或 Apache service 账户权限）
• 数据库配置改在 config/db.php，不是 protected/config/main.php（后者是 Yii 1 写法，Yii 2+ 已无 protected 目录）
• 访问地址必须是 http://localhost/myproject/web/（web/ 是入口目录），不是根目录——否则会暴露 config/、runtime/ 等敏感路径

如果想用 php yii serve 启动内置服务器，要先确认 yii 文件存在且可执行（Composer 会自动写好 shebang），然后在项目根目录运行：

php yii serve --port=8080

常见报错与对应检查点

刚创建完项目却打不开首页？对照这些高频错误快速定位：

• Parse error: syntax error, unexpected token "string" → PHP 版本太低，确认是否误用了 PHP 7.3 运行 Yii 2.0.48+
• Failed to open stream: No such file or directory in vendor/autoload.php → Composer 安装中途失败，删掉 vendor/ 和 composer.lock 重装
• 白屏无报错，但日志里有 Invalid Parameter – yii\base\InvalidParamException The view file does not exist → URL 访问路径错了，没指向 web/ 子目录
• Setting unknown property: yii\web\Application::bootstrap → 用了 Yii 3 的配置格式去跑 Yii 2 项目（比如把 'bootstrap' => ['log'] 写成数组键名带引号的字符串）

真正麻烦的从来不是“怎么建项目”，而是建完之后没意识到 web/ 是唯一合法入口、runtime/ 必须可写、以及 Composer 错误不会自动提示——它只会静默生成一个半残的 vendor。

理论要掌握，实操不能落！以上关于《Yii框架如何创建项目？快速上手教程》的详细介绍，大家都掌握了吧！如果想要继续提升自己的能力，那么就来关注golang学习网公众号吧！