在本地使用XAMPP搭建Yii2高级版（Advanced Template）开发环境，并不只是把文件丢进htdocs那么简单。Yii2高级模板采用前后端分离的多应用结构，每个应用都有自己的入口目录和专属域名需求，而XAMPP自带的Apache配置默认只支持单根目录访问。如果不做针对性调整，就会出现首页能开、后台报404，或者命令行无法初始化数据库连接等问题。
一、XAMPP与Yii2高级版的基础准备
首先确保从官方渠道获取XAMPP，并选择包含对应PHP版本的套装。Yii2高级版目前要求PHP 7.4以上，因此XAMPP中的PHP版本不能过低。安装时建议将XAMPP装在纯英文路径下，例如 C:xampp，避免后期Composer因空格或中文路径报错。
随后通过Composer创建Yii2高级项目。在命令行进入XAMPP的htdocs目录，执行创建指令。Composer会自动拉取vendor依赖，这一步需要网络通畅且PHP开启了openssl扩展。若卡在下载环节，多半是XAMPP的php.ini中未取消对php_openssl.dll的注释。
# 进入htdocs cd C:xampphtdocs # 使用Composer创建Yii2高级版项目 composer create-project yiisoft/yii2-app-advanced myproject
二、Apache虚拟主机配置
Yii2高级版的目录结构中，frontend和backend各自拥有web文件夹作为公开入口。若直接通过 http://localhost/myproject/frontend/web 访问，虽然能跑但URL丑陋且易触发安全限制。正确做法是在Apache中配置两个VirtualHost，分别绑定不同本地域名。
打开 XAMPPapacheconfextrahttpd-vhosts.conf，添加如下配置。注意其中的DocumentRoot必须精确到web目录，并赋予Directory授权，否则Apache会返回403。配置完后还需编辑系统hosts文件，将自定义域名指向127.0.0.1。
<VirtualHost *:80>
ServerName frontend.test
DocumentRoot "C:/xampp/htdocs/myproject/frontend/web"
<Directory "C:/xampp/htdocs/myproject/frontend/web">
AllowOverride All
Require all granted
</Directory>
</VirtualHost>
<VirtualHost *:80>
ServerName backend.test
DocumentRoot "C:/xampp/htdocs/myproject/backend/web"
<Directory "C:/xampp/htdocs/myproject/backend/web">
AllowOverride All
Require all granted
</Directory>
</VirtualHost>
三、PHP扩展与php.ini关键参数
XAMPP虽集成了多数扩展，但php.ini默认关闭了部分Yii2必需的组件。打开 XAMPPphpphp.ini，搜索并去掉前面分号：extension=intl、extension=mbstring、extension=curl、extension=gd。intl扩展支撑多语言格式化，缺失时Yii2的Formatter会抛出异常；mbstring则关乎字符串安全处理。
另外，Yii2后台常需上传图片或Excel，默认的upload_max_filesize=2M过小。建议调整为20M，同时post_max_size设为24M，memory_limit保持128M以上。改完重启Apache，通过phpinfo()页面确认扩展状态。
; 修改前 ;extension=intl ;extension=mbstring ; 修改后 extension=intl extension=mbstring extension=curl extension=gd upload_max_filesize=20M post_max_size=24M memory_limit=256M
四、Yii2初始化与权限处理
高级版需要执行初始化脚本以生成环境变量和入口定义。在项目根目录运行 init 命令，选择Development环境。该操作会拷贝env模板并设定cookie校验密钥，切勿在Production模式下来回切换导致配置混乱。
若访问页面提示日志或缓存目录不可写，需将runtime及web/assets设为可写。Windows下XAMPP一般以管理员身份运行Apache即可解决，Linux或macOS则需chmod -R 777对应目录（仅限本地）。
# 项目根目录初始化 cd C:xampphtdocsmyproject php init # 本地开发设置runtime可写（Windows可忽略） chmod -R 777 runtime chmod -R 777 frontend/runtime chmod -R 777 backend/runtime
五、数据库与Debug模块对接
在XAMPP中启动MySQL后，于Yii2的 common/config/main-local.php 填写db配置。注意XAMPP的MySQL 8默认使用caching_sha2_password鉴权，老版Yii2的PDO可能连不上，需在XAMPP的MySQL命令行将root改为mysql_native_password。
推荐安装Yii2-debug与Gii模块辅助开发。在backend的config里开启gii，并通过backend.test/gii访问代码生成器。但正式提交代码前，务必在prod环境关闭这些模块，防止暴露结构。
// common/config/main-local.php 数据库示例
return [
'components' => [
'db' => [
'class' => 'yiidbConnection',
'dsn' => 'mysql:host=127.0.0.1;dbname=yii2_advanced',
'username' => 'root',
'password' => '',
'charset' => 'utf8mb4',
],
],
];
六、常见部署误区与排查
一个典型误区是以为把整个项目放htdocs就能跑，结果暴露了vendor源码。正确思路永远是只暴露各应用的web目录。另一个坑是启用了Apache的mod_rewrite却忘了在web目录放.htaccess，Yii2的漂亮路由会失效，全部退回index.php?r=路径。
当报出class not found时，先想是不是Composer未执行dump-autoload，或XAMPP用了不同PHP版本。可在命令行用 XAMPPphpphp.exe 明确指定版本执行，避免系统PATH里的PHP造成错位。
# 使用XAMPP自带PHP执行Composer重载 C:xamppphpphp.exe composer.phar dump-autoload
经过上述XAMPP虚拟主机、PHP扩展、初始化与数据库适配的步骤，Yii2高级版就能在本地稳定运转。后续若需团队协同，可将php.ini与vhost配置写入项目文档，保证每人环境一致。
XAMPPYii2PHP_configuration修改时间：2026-08-06 09:21:35