如何追踪MediaWiki扩展中自定义钩子事件的源定义？

架构老林

2026-5-20

排查MediaWiki扩展钩子未找到定义的方法

我之前调试MediaWiki扩展时也遇到过类似的困扰——明明看到代码里调用了某个钩子，却找不到它的注册或定义记录。针对你提到的PageForms::BeforeFreeTextSubst钩子以及其他同类问题，给你几个实用的排查方向：

检查扩展的静态注册配置
MediaWiki扩展最常见的钩子注册方式是在extension.json文件的Hooks字段里声明，格式大概是：
```
"Hooks": {
  "PageForms::BeforeFreeTextSubst": "MyExtensionHooks::handleBeforeFreeTextSubst"
}
```
你可以先搜索扩展目录下的extension.json，看看有没有这个钩子的条目。
查找动态注册的代码
有些钩子会通过HookRegistry::register方法在运行时动态注册，比如在扩展的初始化函数里：
```
HookRegistry::register( 'PageForms::BeforeFreeTextSubst', [ MyExtensionHooks::class, 'handleBeforeFreeTextSubst' ] );
```
可以全局搜索整个扩展目录里的HookRegistry::register或者直接搜索钩子名称BeforeFreeTextSubst，不要漏掉注释、文档或者测试文件里的提及。
确认钩子是否为预留/内部未实现的钩子
部分扩展会提前添加钩子调用，为第三方扩展预留扩展点，而自身并没有实现对应的处理函数——这种情况下你自然找不到它的定义。可以查看调用Hooks::run的上下文，看看传递的参数类型和作用，判断它的预期用途。
检查提交历史或版本分支
如果你用的是开发分支或者较新的版本，可能这个钩子是刚被添加的，开发者只写了调用代码还没来得及添加注册逻辑或文档。可以用Git命令查看相关提交：
```
git log --grep="BeforeFreeTextSubst"
```
看看提交记录里有没有关于这个钩子的说明。
排除拼写或命名规范问题
虽然你提到多个钩子都有问题，但还是可以确认下钩子名称的大小写、命名空间（比如PageForms::前缀是否正确）是否和扩展的规范一致，避免因为拼写失误导致找不到定义。