yii2高级模板添加新模块404问题

类文件物理存在，但Yii自动加载找不到，高级模板新建独立api应用，99%是缺少 @api 别名，Yii autoload靠别名映射，不是composer psr‑4。

根因说明

Yii2高级模板：

• @frontend、@backend 在 common/config/bootstrap.php 预先注册别名。
• 你手动新建的api应用，没有注册 @api 别名。
  当解析 api\controllers\TemplateController：
  Yii自动加载逻辑：@api/controllers/TemplateController.php，别名@api不存在 → 直接放弃加载，class_exists返回false，哪怕磁盘上文件真实存在。

修复步骤

1、注册@api别名（必须）

打开 common/config/bootstrap.php，追加一行：

Yii::setAlias('@api', dirname(__DIR__) . '/api');

frontend/backend就是在这里注册别名，api同样需要这里注册，不是写在api/config/main.php里面，main.php的aliases不参与引导阶段自动加载。

2、核对 api/config/main.php

return [
    'id' => 'api',
    'basePath' => dirname(__DIR__),
    // 这里命名空间严格 api\controllers
    'controllerNamespace' => 'api\controllers',
    // 这里不要写 aliases 数组做@api，此处加载时机太晚，autoload阶段还没执行
    // ...其余配置
];

3、验证调试代码，放到 api/web/index.php 最顶部

<?php
// 打印别名路径，看是否指向正确api目录
var_dump(Yii::getAlias('@api'));

$cls = 'api\controllers\TemplateController';
var_dump($cls, class_exists($cls));

// 手动拼装Yii预期的文件路径
$file = Yii::getAlias('@api/controllers/TemplateController.php');
var_dump($file, file_exists($file));

die;

• Yii::getAlias('@api') 如果抛出异常：别名没注册，就是上面bootstrap漏写。
• file_exists($file)=true，但是class_exists=false：确认别名生效，Yii自动加载器依然不去include该文件。

4、其他踩坑点

1. 大小写严格：TemplateController.php文件名、类名完全一致；Linux区分大小写，Windows会掩盖问题。
2. 控制器文件第一行 namespace api\controllers; 末尾分号不能丢。
3. opcache缓存：修改bootstrap.php后，重启php‑fpm，清除opcache，否则旧别名常驻内存。
4. 不要用frontend入口访问api，浏览器访问必须是 api/web/index.php。

临时快速验证（强制类映射，用来确认问题）

在api/config/main.php配置加入，写死类映射，如果访问正常，100%确认是别名/autoload问题：

return [
    // ...
    'classMap' => [
        'api\controllers\TemplateController' => '@api/controllers/TemplateController.php',
        'api\controllers\DefaultController' => '@api/controllers/DefaultController.php',
    ],
];

加上classMap之后访问正常，说明物理文件完全没问题，就是Yii自动加载阶段找不到@api别名。

排查顺序

1. common/config/bootstrap.php 是否添加 Yii::setAlias('@api',xxx)
2. 重启php‑fpm，清除opcache
3. index.php调试代码看Yii::getAlias('@api')输出路径
4. 确认访问入口是api/web/index.php，不是frontend入口

高级模板独立应用，不是靠composer psr‑4自动加载，是Yii别名机制，很多人踩这个坑，文件放对，忘记注册别名，class_exists直接false。

版权属于：Joyber

本文链接：https://blog.qqvbc.com/default/yii2-404.html

转载时须注明出处及本声明