必须使用 php 8.0+（推荐8.4），通过composer create-project yiisoft/yii-base-web创建项目，配置nginx/apache重写规则，初始化di容器并验证/health端点返回{"status":"ok"}。
要在本地快速搭建一个可运行、可调试、可部署的 Yii3 全栈开发环境，必须严格匹配 PHP 版本、Composer 依赖结构和 Web 服务器路由规则，缺一不可。
确认并安装满足要求的 PHP 环境
Yii3 不兼容 PHP 7.x 或 HHVM，强行使用会导致 composer install 失败、DI 容器初始化崩溃、属性类型声明报错等不可恢复问题。
执行 php -v 检查当前版本，若低于 8.0，请卸载旧版并安装 PHP 8.4（推荐）或至少 8.0。
Ubuntu 用户可运行：sudo apt install php8.4-cli php8.4-mbstring php8.4-xml php8.4-pdo php8.4-mysql php8.4-opcache php8.4-curl php8.4-json。
macOS 用户建议用 【Homebrew + php@8.4】，避免通过 MacPorts 或预装 PHP 引入路径混乱。
Windows 用户请直接下载 php.net 官方 PHP 8.4 Thread Safe VC17 x64 ZIP 包，解压后手动配置系统 PATH 并启用 extension=php_openssl.dll 等必需扩展。
创建 Yii3 项目骨架
Yii3 不再提供 yii2-composer 或高级模板，官方只维护两个基础模板：
方法一：Web 应用模板（含 public/index.php 入口和基本路由）
运行：composer create-project yiisoft/yii-base-web myapp
方法二：通用工程模板（无 Web 入口，适合构建 CLI 工具或微服务）
运行：composer create-project yiisoft/yii-project-template myapp
⚠️ 注意：不要用 yii/base 或 yii/framework 这类已废弃包名，它们在 2024 年后已从 Packagist 彻底移除。
项目生成后，进入目录执行 composer install，确保所有 yiisoft/* 组件正确拉取，特别是 yiisoft/di、yiisoft/router、yiisoft/log 三个核心包。
配置 Web 服务器支持 URL 重写
Nginx 配置关键段（保存为 /etc/nginx/sites-available/myapp）：
```nginx
server {
listen 80;
root /var/www/myapp/public;
index index.php;
server_name localhost;
location / {
try_files $uri $uri/ /index.php?$query_string;
}
location ~ \.php$ {
fastcgi_pass unix:/var/run/php/php8.4-fpm.sock;
fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
include fastcgi_params;
}
}
Apache 用户需启用 mod_rewrite，并在 public/.htaccess 中保留 Yii3 默认规则——该文件由模板自动生成，【切勿删除或注释 RewriteEngine On 行】。
PHP 内置服务器仅用于开发调试，启动命令为：php -S localhost:8080 -t public/。注意：它不支持 .htaccess，且无法模拟真实 Nginx/Apache 的 PATH_INFO 行为，某些路由中间件可能异常。
初始化应用配置与 DI 容器
第一步：打开 config/web.php，确认已包含以下最小依赖注入定义：
'yiisoft/router' => [ 'class' => \Yiisoft\Router\SimpleRouter::class ],<br>'yiisoft/view' => [ 'class' => \Yiisoft\View\WebView::class ]
第二步：在 src/Bootstrap.php 中注册默认中间件管道，例如添加日志记录和错误处理：
$app->add(new \Yiisoft\Logger\Filter\LogLevelFilter([LogLevel::ERROR, LogLevel::WARNING]));<br>$app->add(new \Yiisoft\ErrorHandler\Middleware\ErrorCatcher());
第三步：运行 php public/index.php，若返回空白页且 HTTP 状态码为 200，说明 DI 容器已成功加载并完成组件绑定；若报错 “Class not found” 或 “Cannot resolve dependency”，说明某 yiisoft/* 包未被正确 require 或 autoloader 未生效。
这一步操作起来很简单，直接把文件拖进去就行。
第四步：验证路由是否生效——访问 http://localhost:8080/health（默认健康检查端点），应返回 JSON {"status":"ok"}。该端点由 yiisoft/health-check 包提供，若 404，请检查是否漏装该包或未在 config/routes.php 中注册对应 handler。
