必须使用composer create-project yiisoft/app初始化项目，php≥8.2，入口需实例化container并传入applicationfactory，配置通过psr-11容器注册接口绑定，中间件须实现psr-15，路由显式绑定类方法，模块按领域目录组织无需module类。
要搭建一个符合 Yii 3.0 官方推荐路径、可上线、易维护的全栈项目架构，必须绕开 Yii 2.x 的惯性思维，从入口、容器、中间件、路由到模块组织全部按 PSR-11/PSR-15 重写，任何沿用 Yii::$app 或静态工厂调用的写法都会导致启动失败。
初始化项目骨架
执行 composer create-project yiisoft/app myapp ——这是唯一受官方支持的初始化方式，它会自动拉取 yiisoft/yii-web、yiisoft/di、yiisoft/router 等核心包，并生成符合 PHP 8.2+ 语法的入口文件和配置结构。
【PHP 版本必须 ≥ 8.2】 否则 Composer 会在解析 yiisoft/core 的联合类型声明（如 string|int|null）时直接报错退出，且不提示具体原因。
创建完成后，删掉 tests/ 目录外所有未被 composer.json 显式 require 的第三方包——Yii 3.0 的模块化设计意味着你不需要的包（比如 yiisoft/yii-debug）不会自动加载，但若手动引入又未注册中间件，会导致请求卡在 pipeline 中无响应。
重构入口与应用生命周期
打开 public/index.php，确认内容为：
<?php <br>require __DIR__ . '/../vendor/autoload.php';<br><br>use Yiisoft\App\ApplicationFactory;<br>use Yiisoft\Di\Container;<br><br>$container = new Container();<br>$application = (new ApplicationFactory($container))->createWebApplication();<br>$application->run();
这一步不能省略容器实例化——ApplicationFactory 不再接受全局 Yii::$container，所有依赖都必须由你传入的 $container 提供。若此处直接 new Application 而不传容器，后续控制器构造函数注入会全部失败。
删除所有 Yii::setAlias() 和 Yii::configure() 调用。Yii 3.0 的别名系统已移除，路径映射统一通过 config/params.php 中的数组键值定义，例如：'rootDir' => dirname(__DIR__)。
配置 DI 容器与组件注册
在 config/common.php 中，用键值对形式注册服务：
LoggerInterface::class => ['class' => FileLogger::class, 'file' => '@runtime/logs/app.log'],<br>CacheInterface::class => ['class' => ApcuCache::class],<br>DbConnection::class => ['class' => DbConnection::class, 'dsn' => 'mysql:host=localhost;dbname=test']
注意：键必须是接口或抽象类，值必须是数组（含 class 键），不能直接写 FileLogger::class——否则容器无法解析构造参数，抛出 UnresolvableDependencyException。
数据库组件不再叫 'db'，而是绑定到 DbConnection::class 接口；控制器里要用它，就得声明构造参数：public function __construct(private DbConnection $db)，而不是 $this->db。
定义 PSR-15 中间件链
第一步：在 config/web.php 中返回中间件数组：
return [<br> \Yiisoft\Middleware\TrustedHosts::class,<br> \Yiisoft\Middleware\BodyParamsParser::class,<br> \App\Middleware\Authentication::class,<br>];
第二步：每个中间件必须实现 MiddlewareInterface，且构造函数参数必须能被容器解析。例如 Authentication 若依赖 UserRepositoryInterface，就必须在 common.php 中先注册该接口。
第三步：删掉所有 beforeAction() 和 afterAction() 方法——它们在 Yii 3.0 中已被彻底移除，权限校验、日志记录、响应包装等逻辑必须下沉为独立中间件，否则请求根本不会进入控制器。
模块化组织业务代码
方法一：按领域建目录，不建传统 Module 类
把用户相关逻辑全放在 src/User/ 下：src/User/Controller/ProfileController.php、src/User/Service/UserService.php、src/User/Repository/UserRepositoryInterface.php。Yii 3.0 不再需要 Module::init() 或 modules 配置项，只要命名空间正确、类被 PSR-4 自动加载，就能被容器发现并注入。
方法二：用 yiisoft/layered-config 实现环境分层
在 config/ 下建 dev/、prod/ 子目录，各自放 db.php、logger.php。主配置 web.php 用 Configurator::merge() 合并，避免硬编码敏感信息。
方法三：路由绑定到具体类方法，禁用动作 ID 映射
在 config/routes.php 中写：$router->addRoute('GET', '/api/user/{id:\d+}', [UserController::class, 'view']);。不要依赖 actionView() 自动转 /view，这种隐式映射在 Yii 3.0 中不存在，漏写路由会导致 404 且无提示。
