yii2的debug和gii模块必须同时满足三个前提才能启用：yii_env='dev'、写入bootstrap数组、显式配置allowedips（如['127.0.0.1','::1']），缺一即导致403或404；高级模板应配在frontend/backend/config/main-local.php中。
Yii2 的 debug 和 gii 模块不是默认启用的，哪怕项目处于开发环境（YII_ENV = 'dev'），也必须显式注册、配置 IP 白名单并加入启动引导，缺一不可。跳过任一环节，访问 /debug 或 /gii 会直接返回 403 或 404。
必须同时满足的三个前提条件
这是最常被忽略的底层逻辑：三者缺一，模块就不可用。
-
YII_ENV必须为'dev'—— 通常在web/index.php开头定义：defined('YII_ENV') or define('YII_ENV', 'dev'); -
debug和gii都要写入$config['bootstrap']数组，否则不会自动加载 -
allowedIPs必须显式设置，不能留空、不能写成['*']（Yii 会拒绝该写法）；本地开发推荐['127.0.0.1', '::1']
配置位置：优先用 main-local.php，别硬改 web.php
高级模板（advanced）中，gii 和 debug 的配置应放在 frontend/config/main-local.php 或 backend/config/main-local.php，而不是 web.php。因为 main-local.php 本身只在 YII_ENV_DEV 下加载，天然隔离生产环境。
正确写法示例（以 frontend 为例）：
return [
'bootstrap' => ['debug', 'gii'],
'modules' => [
'debug' => [
'class' => 'yii\debug\Module',
'allowedIPs' => ['127.0.0.1', '::1'],
],
'gii' => [
'class' => 'yii\gii\Module',
'allowedIPs' => ['127.0.0.1', '::1'],
],
],
];
注意：allowedIPs 是严格匹配，写错字段名（比如写成 allowIPs）或类型（比如传字符串而非数组）会导致整个模块静默失效。
访问路径和 URL 重写的影响
启用后，标准访问路径是 /gii 和 /debug，但前提是你的 Web 服务器支持 URL 重写（如 Apache 的 .htaccess 或 Nginx 的 try_files 配置）。如果没配好重写，必须带 index.php：
http://localhost/index.php?r=giihttp://localhost/index.php?r=debug
如果你用的是高级模板且访问后台 Gii，路径通常是 /backend/web/index.php/gii，不是根目录下的 /gii —— 这点容易因入口路径搞错而 404。
常见失败现象与对应检查点
遇到打不开、白屏、403、资产加载失败（如 JS/CSS 404），按顺序排查：
- 浏览器地址栏是否拼错？
/gii不是/gi，也不是/gii/（结尾斜杠有时触发路由异常） -
allowedIPs是否包含你当前请求的真实 IP？用$_SERVER['REMOTE_ADDR']打印确认，尤其在 Docker、WSL 或代理环境下 -
vendor/yiisoft/yii2-gii和vendor/yiisoft/yii2-debug目录是否存在？Composer 没装全会导致模块类找不到 - 是否误把配置写进了
common/config/main.php？这个文件会被前后台共用，但debug和gii应只出现在具体应用层（frontend/backend）的 local 配置里
最隐蔽的坑是：gii 模块加载了，但生成器列表为空——这往往是因为 generators 配置被覆盖或路径别名解析失败，此时要检查 gii 配置里有没有误删了 'class' => 'yii\gii\Module' 这一行。
