“Class not found”源于自动加载机制失效，需验证spl_autoload_register是否注册并触发、路径是否用ROOT锚定绝对路径、命名空间/目录/PSR-4映射三者严格一致，最后用require_once直连文件快速定位问题。
“Class not found”不是文件丢了，而是 PHP 根本没去加载它——问题出在自动加载机制卡在了路径、命名空间、注册时机这三道关上。修复不靠猜，靠验证链。
确认 autoload 是否真正注册并执行
写了 spl_autoload_register() 不等于它被调用了。常见陷阱是：在 require autoload.php 之前就 new 了类，或多个 loader 注册顺序混乱导致前一个直接 exit/die 而阻断后续。
- 在 autoload 函数开头加
error_log("[AUTOLOAD] {$className}");，查日志看是否触发 - 运行
print_r(spl_autoload_functions());，确认你的函数已列在回调列表中 - 确保入口文件（如
public/index.php）顶部先引入 autoload，再执行任何 new 或 use
路径必须锚定根目录，不能依赖当前工作目录
用 is_file('app/Controllers/UserController.php') 是高危写法——'app/' 是相对 getcwd() 的路径，而 CLI 运行位置、Web 服务器 DocumentRoot、甚至 phpEnv 切换版本后的环境变量都可能让 getcwd() 指向 public/、vendor/ 或其他任意目录。
- 统一用绝对路径：在 autoload.php 开头定义
define('ROOT', dirname(__DIR__));（指向项目根，即含 composer.json 的目录） - 加载时拼接：
$file = ROOT . '/app/Controllers/' . str_replace('\', '/', $className) . '.php'; - Windows/Linux 兼容性无需额外处理，PHP 会自动转换
/分隔符
命名空间、文件路径、composer.json 三者必须严格对齐
PSR-4 不是模糊匹配，是精确映射。错一个字母、少一个反斜杠、大小写不一致、目录名多一级，全部失败。
立即学习“PHP免费学习笔记（深入）”；
- 类声明为
namespace AppControllers;→ 文件必须存为app/Controllers/UserController.php（注意大小写，Linux 区分） -
composer.json中写"App\": "app/"（双反斜杠转义，结尾有斜杠），不是"App": "app"或"app": "app/" - 执行
composer dump-autoload -o后，打开vendor/composer/autoload_psr4.php，手动搜索'App\'确认映射已写入
绕过 autoload 快速定位真实瓶颈
当怀疑是 autoload 链路中断，而非类本身问题时，跳过自动加载直连文件，能快速收窄范围。
- 在报错行前加：
require_once __DIR__ . '/../app/Controllers/UserController.php'; - 如果此时不报错，说明类文件存在、语法合法、权限正常——问题 100% 出在 autoload 配置或触发环节
- 再配合
get_declared_classes()查看当前已加载的类列表，确认目标类是否缺席
