yii 3.0 项目快速启动需严格满足 php ≥8.2、composer ≥2.5，执行 composer create-project yiisoft/app 创建骨架，显式配置 psr-15 路由与 handler，通过 di 注入 pdo 并启用调试工具栏。
要在2026年快速跑起一个可用的Yii3.0项目，不是配环境、装依赖、改配置三步走完就万事大吉——PHP版本错一位、容器注册漏一行、入口文件少个工厂调用，服务直接500且不报具体错。你得踩准每个硬性节点，跳过所有“理论上可行”的弯路。
确认PHP与Composer版本是否达标
打开终端，执行：php -v，输出必须是 【8.2 或更高版本】（如 8.2.12、8.3.7、8.4.0），低于 8.2 的任何输出都立即终止后续操作——框架源码含构造器属性提升和联合类型，PHP 8.1 解析即 fatal error。
接着运行：composer --version，确保显示的是 【2.5.0 或更新版本】；旧版 Composer 在解析 yiisoft/yii-web 的 PSR-11 容器定义时会静默跳过依赖绑定，导致 ApplicationFactory 找不到容器实例。
若版本不符：Linux/macOS 用户用 curl -sS https://getcomposer.org/installer | php 更新；Windows 用户重装 Composer-Setup.exe，勾选“Add to PATH”选项。
创建项目并验证基础结构
在 Web 根目录（如 /var/www/html）下执行：
composer create-project yiisoft/app myapp --prefer-dist
这一步会拉取 yiisoft/app 模板、yiisoft/yii-web、yiisoft/di 等核心包，约 70MB。注意：不要加 --stability=dev，当前稳定版已为 GA 版本（2025年12月31日发布），dev 分支无额外功能，反而可能引入未合入的破坏性变更。
进入项目目录：cd myapp，然后启动内置服务器：php yii serve（不是 php -S）。访问 http://localhost:8080，页面出现 “Congratulations! You’ve successfully installed Yii3.” 即表示骨架正常。
若浏览器空白或报错 Class 'Yiisoft\Yii\Web\ApplicationFactory' not found，请检查 vendor/yiisoft/ 目录是否存在 yii-web 和 di 子目录——缺失说明 Composer 安装中途断开，删掉 myapp 重来，不要尝试手动补包。
让控制器响应请求
Yii3.0 不再有 Yii::$app->run()，也不再自动扫描 controllers/ 目录。所有路由必须显式声明。
第一步：打开 config/routes.php，找到注释掉的示例路由，取消注释并改成：
return [ ['GET', '/', ['App\Handler\HomePageHandler::handle']],];
第二步：在 src/Handler/ 下新建 HomePageHandler.php，内容为：
<?php namespace AppHandler;use PsrHttpMessageResponseInterface;use YiisoftHttpStatus;final class HomePageHandler{ public function handle(): ResponseInterface { return YiisoftYiiWebResponse::html('Hello from Yii3!')->withStatus(Status::OK); }}
第三步：清空 runtime/cache/ 下所有文件（缓存机制已变更，旧缓存会导致路由不生效），然后重启服务器：php yii serve --port=8080。
刷新页面，看到 “Hello from Yii3!” 即成功。这一步绕过了传统控制器写法，直击 PSR-15 中间件链本质——Handler 是最轻量级的可执行单元，无需继承基类，不依赖 ServiceLocator。
连接数据库并执行第一条查询
方法一：使用预配置 PDO 连接（推荐新手）
编辑 config/common.php，在 return [ 内加入：
'pdo' => [ 'class' => PDO::class, 'dsn' => 'mysql:host=localhost;dbname=testdb;charset=utf8mb4', 'username' => 'root', 'password' => '', 'options' => [ PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION, ],],
方法二：注入 PDO 实例到 Handler（更符合 DI 哲学）
修改 HomePageHandler 构造函数，添加参数：private PDO $pdo；然后在 config/web.php 的 container 配置块中绑定：
PDO::class => static fn () => new PDO('mysql:host=localhost;dbname=testdb', 'root', ''),
接着在 handle() 方法里写：$this->pdo->query("SELECT VERSION()")->fetchColumn();，返回值拼进 HTML 即可验证连通性。
【注意：MySQL 8.0+ 默认认证插件为 caching_sha2_password，PHP 8.2+ PDO 需启用 mysqlnd 扩展，否则连接失败且无明确提示】
启用调试工具栏
Yii3.0 默认不加载调试工具栏，必须手动安装扩展并注册中间件。
执行：composer require yiisoft/yii-debug --dev
编辑 config/console.php 和 config/web.php，在 middlewares 数组开头加入：
YiisoftYiiDebugToolbarToolbarMiddleware::class,
再确保 config/debug.php 存在且包含允许 IP 列表，例如：
'allowedIPs' => ['127.0.0.1', '::1'],
重启服务，页面右下角出现蓝色小图标即表示激活成功。没有它，你将看不到 SQL 查询耗时、内存占用、路由匹配详情——这不是功能缺失，是设计选择。
