Yii2部署教程：phpEnv安装与配置指南

本文详细讲解了在Windows轻量级PHP开发环境phpEnv中手动集成与部署Yii2框架的完整流程，涵盖PHP版本及关键扩展（如pdo_mysql、mbstring、intl等）的严格校验与配置修复、Composer的正确安装与SSL/镜像优化、Yii2项目的安全创建与目录结构处理、Apache虚拟主机与URL重写规则的手动配置、hosts绑定及权限问题排查，并重点揭示了phpEnv中Web与CLI模式php.ini分离导致的常见陷阱，为开发者提供了一套稳定、可复现的本地Yii2开发环境搭建方案。

phpEnv 是 Windows 下轻量级 PHP 开发环境（类似 phpStudy、XAMPP），但默认不带 Yii2，需手动集成。它本身不提供一键部署 Yii2 的功能，直接运行 composer create-project 通常会失败——因为 phpEnv 的 PHP 配置常缺扩展、路径权限受限、或 Composer 未正确识别 PHP CLI 环境。

确认 phpEnv 的 PHP 是否可用且完整

很多部署卡在第一步：phpEnv 自带的 PHP 看似能运行，但实际缺少 Yii2 强依赖的扩展或配置错误。

• 打开 phpEnv 控制面板 → “PHP设置” → 查看当前启用的 PHP 版本（必须 ≥7.4，推荐 8.0+）
• 点“PHP信息”链接，检查以下扩展是否 已启用：pdo_mysql、mbstring、openssl、xml、intl、curl；缺任一者，Yii2 启动时会报错如 Class 'yii\helpers\BaseStringHelper' not found 或数据库连接失败
• 在命令行中执行 php -v 和 php -m | findstr "mbstring intl"（Windows），确认 CLI 模式下扩展也生效——phpEnv 的 Web 模式和 CLI 模式可能使用不同 php.ini
• 若发现 CLI 不识别扩展，需手动编辑 phpEnv 安装目录下的 php\php.ini（非 Apache 目录里的那个），取消对应 extension= 行前的分号，并确保 extension_dir 指向正确的 ext/ 路径（如 extension_dir = "D:/phpEnv/php/ext"）

在 phpEnv 中正确安装 Composer 并初始化 Yii2

phpEnv 自带的 Composer 常是旧版或未绑定 PHP CLI，直接运行 composer create-project 极易因版本冲突或 SSL 错误中断。

• 先下载最新版 Composer Windows Installer（Composer-Setup.exe），安装时勾选“Use system PHP”，并指定 phpEnv 的 php.exe 路径（如 D:\phpEnv\php\php.exe）
• 安装后，在命令行执行 composer --version，再运行 composer diagnose，重点看是否提示 PHP OpenSSL extension not loaded 或 SSL certificate problem
• 若报 SSL 错误，临时禁用验证（仅限内网开发）：composer config -g secure-http false；更稳妥的是配置国内镜像：composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
• 创建项目时，**不要在 phpEnv 的 www 根目录直接操作**（权限混乱易出错），而是新建独立目录如 D:\projects\myapi，再运行：
  

  composer create-project --prefer-dist yiisoft/yii2-app-basic myapi

• 完成后，把整个 myapi 文件夹复制到 phpEnv 的 www 目录下（如 D:\phpEnv\www\myapi），然后只将 web 子目录设为 Web 可访问入口

Nginx/Apache 配置要点（phpEnv 默认用 Apache）

phpEnv 默认启用 Apache，但它的虚拟主机配置较简陋，Yii2 的 URL 重写（隐藏 index.php）需要手动补全规则，否则访问 /site/about 会 404。

• 进入 phpEnv 安装目录 → apache\conf\extra\httpd-vhosts.conf，添加如下虚拟主机段：

<VirtualHost *:80>
    DocumentRoot "D:/phpEnv/www/myapi/web"
    ServerName myapi.local
    <Directory "D:/phpEnv/www/myapi/web">
        RewriteEngine on
        RewriteCond %{REQUEST_FILENAME} !-f
        RewriteCond %{REQUEST_FILENAME} !-d
        RewriteRule . index.php [L]
        Require all granted
    </Directory>
</VirtualHost>

• 保存后，编辑系统 C:\Windows\System32\drivers\etc\hosts，追加一行：127.0.0.1 myapi.local
• 重启 phpEnv 的 Apache 服务；若仍 404，检查 Apache 错误日志（apache\logs\error.log）是否提示 mod_rewrite not enabled——需在 httpd.conf 中取消 #LoadModule rewrite_module modules/mod_rewrite.so 前的注释
• 访问 http://myapi.local，若看到 Yii2 欢迎页即成功；若提示 Setting unknown property: yii\web\Application::cookieValidationKey，说明 config/web.php 中该字段为空，需填入至少32位随机字符串

runtime 和 assets 目录权限问题

phpEnv 运行 Apache 时，其 worker 进程默认以 SYSTEM 或当前用户身份运行，但 Windows 下对 runtime 目录的写权限控制比 Linux 更隐蔽，常导致日志无法写入、缓存生成失败、资源发布（assets）报错。

• 右键点击 D:\phpEnv\www\myapi\runtime → “属性” → “安全” → “编辑” → 添加用户 IIS_IUSRS 或 Users，赋予“修改”权限（而非仅“读取和执行”）
• 同理处理 web/assets 目录；若仍报错 Unable to write to directory，可临时在 config/web.php 中强制指定 runtime 路径：
  'runtimePath' => __DIR__ . '/../runtime',
• 生产环境绝不可留 YII_DEBUG = true，但在 phpEnv 开发阶段建议保持开启，以便错误堆栈直接显示——关闭后所有错误将静默转为白屏或 500

最易被忽略的是：phpEnv 的 Apache 和 CLI 使用的 php.ini 往往不是同一个文件，扩展启用状态不一致；每次改完配置，必须分别验证 php -m 和 phpinfo() 输出是否一致。

终于介绍完啦！小伙伴们，这篇关于《Yii2部署教程：phpEnv安装与配置指南》的介绍应该让你收获多多了吧！欢迎大家收藏或分享给更多需要学习的朋友吧~golang学习网公众号也会发布文章相关知识，快来关注吧！