ClassNotFoundException vs "找不到类"的十二种真身：一份按报错位置速查的排查地图

写插件时最怕的不是报错，是报错说"Class not found"，但 autoload 明明配好了。我整理了一份按报错发生位置分类的排查清单，覆盖我过去一年踩过的真坑。

一、入口文件层：类还没加载就急着 new

典型场景：你在插件主文件顶部直接 new MyPlugin();，但那个类在 includes/class-my-plugin.php 里。

// ❌ 错误示范：autoload 还没注册
require_once __DIR__ . '/vendor/autoload.php'; // 甚至这行都没有
$plugin = new MyPlugin\Bootstrap(); // ClassNotFoundException

真因：WordPress 的插件加载顺序里，你的入口文件被执行时，PSR-4 的 autoload 规则可能还没被 PHP 解析到。或者更常见——你用了 Composer，但 vendor/autoload.php 的路径写成了相对路径，在某些符号链接部署的场景下直接断裂。

速查：在 new 之前加一行 var_dump(class_exists('MyPlugin\Bootstrap'));，false 就说明加载链断了，别盯着类名死磕。

二、钩子回调层：字符串写错，IDE 不会报错

add_action('init', ['MyPlugin\Hook\Initilizer', 'run']); // 注意 Initilizer

类名拼错一个字母，PHP 到执行 init 时才抛 Class 'MyPlugin\Hook\Initilizer' not found。这种错在 IDE 里不会红线，因为字符串里写啥 IDE 都认。

我的土办法：回调数组统一用 ::class 常量：

add_action('init', [\MyPlugin\Hook\Initializer::class, 'run']); // 拼错就红线

三、多版本 PHP 层：匿名类、union type 的静默死亡

你本地 PHP 8.1，线上 7.4。代码里用了 new class { ... } 做简单策略对象，或者参数类型写了 string|int。7.4 解析文件时直接白屏，error log 里可能是 Class not found 的变体——因为语法解析失败导致整个文件没被加载，里面的类自然"不存在"。

速查：不是看报错行，是报错行的前一个文件有没有语法错误。用 php -l 扫一遍比猜快。

四、WordPress 多站点层：插件在不同 context 被激活

网络激活 vs 站点激活，WP_PLUGIN_DIR 和 WPMU_PLUGIN_DIR 路径不同。你的 autoload 如果硬编码了 WP_PLUGIN_DIR . '/my-plugin/'，放到 mu-plugins 下直接失效。

真坑：有人把插件丢进 mu-plugins 做"必须启用"，但你的 plugin_dir_path(__FILE__) 在子目录嵌套时会多一层或少一层。

// 相对安全的做法：永远以当前文件为锚点
$base_dir = dirname(__DIR__); // 如果当前文件在 includes/ 下

五、缓存层：Opcode 缓存记住了旧的 autoload 映射

改了类名、移动了文件目录，但 OPcache 没刷新。PHP 8 的 opcache.revalidate_freq 默认 2 秒，某些面板环境设成了 60 秒甚至更久。

症状：文件系统里明明有这个类，class_exists 就是 false。重启 PHP-FPM 或者 touch 一下 autoload 文件的时间戳。

六、Composer 层：optimize-autoloader 的"静态映射陷阱"

生产环境常用 composer dump-autoload -o，生成 classmap。之后你新增了一个类文件，但没重新 dump。本地开发用 PSR-4 动态加载，能跑；线上 classmap 里没有，直接炸。

我的 CI 脚本：

composer install --no-dev --optimize-autoloader
# 加一行防御：如果 src/ 目录有变更，强制重新 dump
git diff --name-only HEAD~1 | grep '^src/' && composer dump-autoload -o

七、WordPress 自身类的"假不存在"

想用 WP_Block_Type_Registry 或 WP_REST_Server，但你的代码在 plugins_loaded 之前就执行了。这些类是随着 WordPress 核心加载顺序逐步出现的，不是一开始就存在。

速查表（我打印贴在显示器边上的）：

八、最隐蔽的一种：大小写敏感文件系统

Mac/Windows 开发，类文件叫 class-AdminMenu.php，代码里写 new MyPlugin\AdminMenu()。autoload 规则映射到 AdminMenu.php，本地不区分大小写，能跑；Linux 线上严格区分，文件找不到，类自然不存在。

根治：CI 里加一步 find src/ -name '*.php' | sort，和 composer.json 里的 PSR-4 映射逐行比对。或者更狠，开发容器直接跑 Linux。

一个快速定位的决策树

报错: Class 'X' not found
  │
  ├─ 本地能跑，线上不行？ → 检查大小写、PHP 版本、OPcache
  │
  ├─ 特定钩子才报错？ → 检查类在 WordPress 生命周期中的可用时机
  │
  ├─ 新增类后第一次部署？ → 重新 dump-autoload，检查 classmap
  │
  ├─ 移动/重命名后？ → 检查所有字符串引用，优先换成 ::class
  │
  └─ 完全随机、时有时无？ → 检查是否多站点路径问题，或对象缓存污染了类存在性检查

你们还遇到过哪种"类找不到"但原因特别离谱的情况？我目前最高记录是客户服务器上另一个插件也 Composer 依赖了同名不同版本的包，导致 autoload 冲突，报错类名是对的，但加载的是错版本的文件。