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、其他踩坑点
- 大小写严格：
TemplateController.php文件名、类名完全一致；Linux区分大小写，Windows会掩盖问题。 - 控制器文件第一行
namespace api\controllers;末尾分号不能丢。 - opcache缓存：修改bootstrap.php后，重启php‑fpm，清除opcache，否则旧别名常驻内存。
- 不要用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别名。排查顺序
- common/config/bootstrap.php 是否添加
Yii::setAlias('@api',xxx) - 重启php‑fpm，清除opcache
- index.php调试代码看
Yii::getAlias('@api')输出路径 - 确认访问入口是api/web/index.php，不是frontend入口
高级模板独立应用，不是靠composer psr‑4自动加载，是Yii别名机制，很多人踩这个坑，文件放对，忘记注册别名，class_exists直接false。
