ThinkPHP事件类必须继承thinkEvent，否则监听静默失效；监听器handle参数须与事件public属性严格匹配；配置需用全限定名；异步需手动dispatch队列任务。
事件类定义必须继承 thinkEvent，否则监听不触发
ThinkPHP 的事件机制依赖类型判断，Event 类本身是空基类，但框架内部用 instanceof hinkEvent 做校验。如果自定义事件类没继承它，event('MyEvent', $data) 会静默失败，没有任何报错，日志里也看不到记录。
常见错误是直接写个普通类当事件，比如：
class UserRegistered {} // ❌ 不会触发监听
正确写法：
use thinkEvent;
class UserRegistered extends Event {} // ✅
- 事件类建议放在
appevent目录下，命名与文件名严格一致（如UserRegistered.php） - 构造函数里不要做耗时操作，事件实例化发生在触发时刻，影响响应速度
- 事件类中不建议存状态或依赖容器，它只是数据载体；复杂逻辑应交给监听器处理
监听器类的 handle 方法参数必须匹配事件类属性
ThinkPHP 会自动把事件对象的 public 属性作为参数传给 handle()，不是传整个对象。比如：
立即学习“PHP免费学习笔记（深入）”；
class UserRegistered extends Event
{
public $userId;
public $email;
}
那么监听器必须写成：
public function handle($userId, $email)
{
// ✅ 参数顺序和名称需与事件类 public 属性完全一致
}
- 少一个参数、多一个参数、名字拼错（如写成
$user_id），都会导致handle不执行，且无任何提示 - 如果事件类有默认值（
public $status = 'active';），监听器对应参数可设默认值，但不推荐——容易掩盖字段变更问题 - 不支持类型声明（如
handle(int $userId)），PHP 8+ 下会因参数不匹配直接报TypeError
event.php 配置里监听器路径写错，会导致“监听器已注册但永不调用”
配置文件 appevent.php 中的键是事件类完整命名空间，值是监听器类数组。常见错误包括：
- 事件类路径写成别名或短名（如
'UserRegistered' => [...]），必须是全限定名：'appeventUserRegistered' - 监听器类名漏了命名空间（如写成
'SendWelcomeEmail'而非'applistenerSendWelcomeEmail'） - 监听器类未实现
thinkContractsEventHandleInterface，虽然框架不强制检查，但 IDE 和后续维护容易出错
示例正确配置：
return [
'app\event\UserRegistered' => [
'app\listener\SendWelcomeEmail',
'app\listener\RecordUserActivity',
],
];
注意：Windows 下反斜杠要双写或改用正斜杠，否则 autoload 失败。
异步监听需手动启用队列，event() 默认始终同步执行
很多人以为加个 @async 注解或配个开关就能异步，其实 ThinkPHP 的 event() 函数本身不涉及队列。所谓“异步监听”，本质是监听器自己把任务推到队列里去。
- 监听器内不能直接调用耗时操作（如发邮件、调外部 API），否则阻塞主流程
- 正确做法是在
handle()中 dispatch 一个 Job，例如：dispatch(new SendWelcomeEmailJob($this->userId)); - 别忘了在
config/queue.php配好驱动，并确保队列服务（Redis / database / beanstalkd）已启动 - 开发环境默认不跑队列，要用
php think queue:listen手动启，否则监听器里的 job 永远不执行
事件解耦的关键不在“是否异步”，而在于监听器能否被独立替换、测试、关闭。哪怕全是同步，只要逻辑拆开了，就算解耦成功。
最容易被忽略的一点：事件类和监听器类的自动加载依赖 composer 的 autoload 配置。删了 composer.json 里的 "app\" 映射，或者没跑 composer dump-autoload，就会出现类找不到却报“监听器未注册”的假象。
