最稳妥方式是运行 composer create-project –prefer-dist yiisoft/yii2-app-basic basic（或 advanced），它提供完整骨架；常见错误是误用 composer require yii2 核心库而缺失入口文件；需确保 php ≥5.4 且启用 pdo、mbstring 等扩展；入口文件路径必须正确引用 ../vendor/autoload.php；开发可用 php yii serve 快速启动。
用 composer create-project 初始化 Yii2 项目最稳妥
直接运行 composer create-project --prefer-dist yiisoft/yii2-app-basic basic（或 yii2-app-advanced）是官方推荐方式，它会自动拉取带完整目录结构、预置配置和基础脚本的模板，比手动 require 更少出错。
常见错误现象：有人先 composer init 再 composer require yiisoft/yii2，结果发现没有 web/index.php、config/web.php 等关键入口和配置——因为 yii2 包本身只是核心库，不包含应用骨架。
- 使用场景：新项目起步，需要可立即运行的最小可行环境
-
--prefer-dist强制走压缩包安装，比--prefer-source快且干净 - 如果网络慢，可提前配置国内镜像：
composer config -g repo.packagist composer https://packagist.phpcomposer.com（注意该镜像已停用，现推荐https://mirrors.aliyun.com/composer/）
安装失败时优先检查 php.ini 扩展和版本
Yii2.0 要求 PHP ≥ 5.4.0，但实际部署中多数卡在扩展缺失，典型报错是 class 'PDO' not found 或 mbstring extension is not loaded。
这些不是 Composer 的问题，而是 PHP 运行环境没配好。Composer 只负责下载代码，不解决底层依赖。
- 必须启用的扩展：
pdo、pdo_mysql（如用 MySQL）、mbstring、openssl、curl - 检查方式：终端执行
php -m | grep -E "pdo|mbstring|openssl"；windows 用户注意php.ini是否加载了对应extension=xxx.dll - PHP 7.4+ 用户注意：
mcrypt已废弃，Yii2 不再依赖它，别再为装不上mcrypt白忙活
vendor/autoload.php 路径写错会导致 Class not found
Yii2 入口文件（如 web/index.php）第一行必须正确引入 Composer 自动生成的自动加载器，否则所有类都找不到。
典型错误：把 require __DIR__ . '/../vendor/autoload.php'; 写成 require __DIR__ . '/vendor/autoload.php';（少了一个 ..），尤其在高级模板里，web/ 目录是子目录，路径差一级就全崩。
- 确认路径是否正确：进入
web/目录后，执行ls ../vendor/autoload.php应该能列出文件 - 不要手动生成或复制
autoload.php——它由 Composer 每次install或update重写，改了也没用 - apache 下若用
mod_rewrite隐藏index.php，也要确保.htaccess里的重写规则没干扰到vendor/路径解析
本地开发用 php yii serve 最省事
不用配 Apache/nginx，Yii2 自带内置服务器命令，适合快速验证环境是否跑通。
执行 php yii serve --docroot="web"（基础模板默认就是 web），然后访问 http://localhost:8080。它本质是调用 PHP 内置 Web Server，轻量、无额外依赖。
- 注意端口被占：加
--port=8081换端口 - 别在
web/目录下直接运行——命令必须在项目根目录（含yii文件的地方）执行 - 这个命令仅限开发，不适用于生产；生产环境仍需 Nginx/Apache + 正确的
root和try_files配置
环境变量、数据库配置、Web 服务器路由这些环节，任何一个路径或权限写错，都会让页面空白或报 500 却不提示具体原因——这时候别急着重装，先看 runtime/logs/app.log 里第一条错误。