Yii框架Windows开发环境配置方法

Yii2框架在Windows环境下虽可正常开发，但极易因配置细节疏漏导致各类隐性错误——从PHP扩展未启用、Composer依赖安装失败，到Apache重写规则失效、静态资源404、数据库连接静默崩溃，问题根源往往不在功能缺失，而在于php.ini、Composer镜像、虚拟主机配置及权限设置这三处关键环节是否严格遵循Yii2的运行契约；本文直击Windows开发中最常踩坑的五大场景，提供可立即验证的实操方案，助你绕过XAMPP/WAMP默认配置的“伪可用”陷阱，真正实现开箱即用的稳定开发体验。

Yii 在 Windows 上能正常开发，但默认 XAMPP 或 WAMP 环境几乎必然报错——不是缺扩展，就是路径权限或重写规则没配对。关键不在“能不能装”，而在php.ini、composer、web/index.php三处是否真正对齐 Yii2 的运行契约。

PHP 扩展没开全，yii basic 启动就报 Class not found

Yii2 要求 openssl、mbstring、pdo_mysql（或对应数据库驱动）必须启用，XAMPP 默认是注释掉的。只改 php.ini 不够，还得确认 Apache 加载的是你改的那份。

• 用 php -v 和 php --ini 查真实加载路径，别信 XAMPP 控制面板显示的“配置文件”
• 打开 php.ini，取消这三行前的分号：extension=openssl、extension=mbstring、extension=pdo_mysql
• 若用 MySQLi 而非 PDO，还要加 extension=mysqli；Windows 下扩展名是 .dll，但 PHP 7.2+ 后多数已内置，无需手动指定路径
• 改完必须重启 Apache（不是仅“Restart”按钮，建议 Stop 再 Start），否则 phpinfo() 里仍显示 disabled

用 composer create-project 创建项目，却提示找不到 php.exe 或卡在 Installing dependencies

Composer 不是“点下一步就行”的安装器，它依赖系统 PATH 和网络策略。Windows 下最常卡在这两步：PHP 不在环境变量里，或国内源被墙。

• 先确认 php.exe 在 PATH 中：echo %PATH% 应含类似 C:\xampp\php 的路径；没加就去“系统属性 → 高级 → 环境变量”里手动添加
• 不要在任意目录下直接运行 composer create-project，先 cd C:\xampp\htdocs，否则项目建在用户目录，Apache 根本找不到
• 如果卡在 Installing dependencies，大概率是 packagist.org 响应超时，立即执行：composer config -g repo.packagist composer https://packagist.laravel-china.com（注意：不是 phpcomposer.com，该镜像已于 2023 年停更）
• 避免使用 --prefer-dist + 旧版 Composer，Yii2 的 asset 包依赖 fxp/composer-asset-plugin，新版 Composer（2.2+）已原生支持，无需额外插件

能访问 http://localhost/basic/web/，但路由 404、CSS 不加载、assets/ 目录空

这是 Windows 下最隐蔽的坑：Apache 默认不解析 .htaccess，且 basic/web 不是合法 DocumentRoot。URL 里带 /web/ 不仅丑，还会让 AssetManager 生成错误 URL，导致静态资源 404。

• 绝对不要把整个 basic/ 放进 htdocs 后直接访问 /basic/web/ —— 这会让 config/web.php 中的 baseUrl 计算错位，AssetBundle 发布路径变成 /basic/web/assets/xxx，而实际请求是 /assets/xxx
• 必须配虚拟主机：DocumentRoot 指向 C:/xampp/htdocs/basic/web，并在 块里加 AllowOverride All 和 Require all granted
• hosts 文件必须加 127.0.0.1 yii2.local，否则 Apache 不会匹配到你写的 VirtualHost
• 检查 runtime/ 和 web/assets/ 是否可写（右键 → 属性 → 安全 → 编辑 → 添加 Users 组并勾选“写入”）；Windows NTFS 权限比 Linux 更敏感，光“继承权限”不一定生效

init 脚本执行后，common/config/main-local.php 仍为空或数据库连不上

init 只复制模板，不自动填值。Windows 下路径分隔符、MySQL socket、密码特殊字符都会让连接失败，错误常静默吞掉，只显示白屏或 500 Internal Server Error。

• 运行 init 后，手动编辑 environments/dev/common/config/main-local.php（不是根目录下的 common/config），填入真实数据库配置
• MySQL 密码含 $、@、/ 时，必须用单引号包裹：'password' => 'my$pass@123'，否则 PHP 解析字符串时报错
• 本地 MySQL 若用 socket 连接（如 WAMP），connectionString 应写成 mysql:unix_socket=/tmp/mysql.sock;dbname=test，而非 host=localhost（Windows 下一般不用 socket）
• 首次访问前务必跑一次迁移：php yii migrate，否则 user 表不存在，登录页直接 500

跨平台开发时，Windows 的路径大小写不敏感、NTFS 权限模型、反斜杠转义，和 Linux/macOS 差异极大。哪怕代码完全一样，runtime/ 目录权限不对、assets/ 生成失败、vendor/autoload.php 加载路径错一位，都会让整个应用静默崩溃。别依赖“看起来能跑”，每次换环境后必须验证 php yii serve 能否启动、php yii migrate 是否成功、浏览器 Network 面板里有没有 404 的 JS/CSS。

终于介绍完啦！小伙伴们，这篇关于《Yii框架Windows开发环境配置方法》的介绍应该让你收获多多了吧！欢迎大家收藏或分享给更多需要学习的朋友吧~golang学习网公众号也会发布文章相关知识，快来关注吧！