ThinkPHP6 出现 Class not found 报错通常是 PSR-4 自动加载失败，需检查命名空间与文件路径是否严格一致，并执行 composer dump-autoload 刷新映射。

命令速用版

在项目根目录执行以下命令刷新自动加载映射并清理缓存：

composer dump-autoload -o
rm -rf runtime/*

为什么会这样

ThinkPHP6 不再使用框架自带的文件扫描机制，完全依赖 Composer 的 PSR-4 自动加载规范。

如果类文件的物理路径、命名空间声明与 composer.json 中的 autoload 配置三者未对齐，Composer 生成的映射表中就没有该类，PHP 运行时自然无法加载。此外，runtime 目录下的容器缓存若未清理，也会干扰类解析。

分步处理

1. 检查命名空间与路径：打开报错的类文件，确认顶部 namespace 声明与文件所在目录一致，例如 app/controller/Index.php 必须声明 namespace app\controller;。

2. 检查文件名大小写：Linux 服务器下 Index.php 与 index.php 是不同文件，确保类名与文件名完全一致，包括大小写。

3. 刷新自动加载：在项目根目录运行 composer dump-autoload -o，确保 vendor/composer/autoload_psr4.php 中生成最新映射。

4. 清理运行缓存：删除 runtime/container/ 和 runtime/cache/ 目录，避免旧容器缓存干扰类解析。

怎么验证是否生效

查看 vendor/composer/autoload_psr4.php 文件，搜索报错的命名空间前缀，确认路径映射已存在。

重新访问页面或执行命令，若报错消失且业务逻辑正常，说明自动加载已恢复。

使用 php -l 检查类文件语法，排除因语法错误导致类注册中断的情况。

常见坑

1. Loader::addNamespace 失效：ThinkPHP6 已移除或忽略 Loader::addNamespace()，自定义命名空间必须通过 composer.json 配置。

2. extend 目录不自动扫描：将 SDK 放入 extend/ 目录不会自动加载，需在 composer.json 中显式声明 psr-4 映射。

3. 门面调用配置：Db::name() 在 ThinkPHP6 默认配置下不可用，需开启 use_facade 或改用依赖注入。

4. 命令行类定义：命令行指令类必须继承 think\console\Command 且实现 configure 和 execute 方法，否则报 Class not found for command。

常见问题

Db::name('user') 报 Call to undefined method 怎么办？

ThinkPHP6 默认关闭了门面支持，需在 config/app.php 中设置 use_facade => true 或改用依赖注入方式调用。

第三方 SDK 放入 extend 目录后找不到类？

extend 目录不是自动加载源，需在 composer.json 的 autoload 段添加该目录的 psr-4 映射并运行 dump-autoload。

Windows 开发正常部署到 Linux 报错？

Linux 文件系统区分大小写，需检查文件名与类名的大小写是否完全一致，避免 Index.php 写成 index.php。

参考来源

ThinkPHP 常见报错解决方案

ThinkPHP 故障排查怎么做_ThinkPHP 常见错误调试解答【操作】

ThinkPHP 自动加载失败怎么办_自动加载失败排查【教程】

ThinkPHP 提示 Class not found 的常见原因及自动加载检查技巧

ThinkPHP 项目升级引发的报错解决_错误日志排查技巧

如何解决 PHP 报错 Class not found 问题_检查命名空间与自动加载

ThinkPHP 命令行报错_Console 指令定义与参数传递技巧

ThinkPHP 集成第三方 SDK 报 Class not found 的 Composer 自动加载修复

PHP 框架报错 Class not found_类找不到错误排查与解决【教程】

PHP 环境故障排查：解决"Class not found"与路径错误的公式