Zsens Admin 插件生命周期钩子"挂不上"的六种隐蔽场景与我的断点排查笔记

写插件这么久，最烦的不是逻辑写崩，是钩子明明写了、函数明明存在，执行时却像空气。这篇不聊钩子基础用法，只记我踩过的那些"代码对了但就是不跑"的隐蔽坑，以及我怎么用最低成本定位的。

一、优先级陷阱：你以为的"先执行"其实是"被覆盖"

WordPress 的 `add_action` 默认优先级是 10。但很多人没意识到，同优先级下的执行顺序等于加载顺序，而插件加载顺序又受目录名、激活时间影响。我曾在一个 `admin_init` 钩子中注册菜单，结果另一个插件也在 `admin_init/10` 里清空了菜单数组——我的代码先跑，它的后跑，直接白干。

调试方法：临时把优先级改成 5 或 15，看行为是否突变。如果变了，说明存在同钩子竞争。

// 别信默认优先级，关键钩子显式声明
add_action('admin_init', [$this, 'registerMenus'], 5); // 抢在前面
add_action('admin_init', [$this, 'lateCleanup'], 999); // 等别人搞完

二、条件挂载的"短路"：钩子注册在了永远为 false 的分支里

常见写法：在构造函数里判断 `is_admin()` 然后挂载。但构造函数执行时，WordPress 还没跑完 `wp_loaded`，`is_admin()` 可能返回错误结果（某些 AJAX 场景尤其诡异）。

我的习惯是延迟判断：钩子先挂上，回调里再判断环境。

// 危险：构造函数阶段 is_admin() 不可靠
public function __construct() {
    // 别在这里做环境判断！
    if (is_admin()) {  // ← 可能误判
        add_action('init', [$this, 'setup']);
    }
}

// 安全：钩子先挂，回调里再决定干不干活
public function __construct() {
    add_action('init', [$this, 'setup']);
}

public function setup() {
    if (!is_admin()) return; // 延迟判断，准确
    // 实际逻辑...
}

三、类实例化时机：钩子绑在了"幽灵对象"上

PHP 里 `$obj = new MyClass(); add_action('hook', [$obj, 'method']);` 这个 `$obj` 如果是局部变量，后续事件触发时它可能已经被销毁，或者你挂的是另一个实例。

最隐蔽的一次：我用依赖注入容器获取单例，但容器配置写错，每次 `get()` 都 new 一个新实例。A 实例挂了钩子，B 实例执行了方法，两边状态完全对不上。

调试技巧：在回调第一行打 `spl_object_id($this)`，看多次触发时 ID 是否一致。

public function onSavePost($postId) {
    error_log('instance: ' . spl_object_id($this) . ', post: ' . $postId);
    // 如果同一次请求里 instance ID 乱跳，说明实例化有问题
}

四、钩子名拼写与动态拼接：肉眼根本看不出来

`save_post` 还是 `save_post_{$post_type}`？`wp_insert_post` 和 `save_post` 差在哪？更坑的是动态拼接的钩子名：

// 拼写灾难：下划线数量、单复数、前缀后缀
do_action("zsens_{$module}_config_saved");  // 触发
add_action("zsens_{$module}_config_save", ...);  // 监听，少了个 d，沉默失败

我的防御做法：所有自定义钩子名用类常量定义，触发和监听引用同一个常量。

class HookNames {
    public const CONFIG_SAVED = 'zsens_config_saved';
}

// 两边都用 HookNames::CONFIG_SAVED，拼写错误直接语法报错

五、调试手段：当 `error_log` 不够用时

钩子不执行，首先要确认是没挂上还是挂了没触发还是触发了但回调崩了。我用的三层排查：

第一层：全局钩子清单

// 丢进 mu-plugin 或临时加到 wp-config.php
add_action('all', function($tag) {
    static $log = [];
    if (!in_array($tag, $log)) {
        $log[] = $tag;
        error_log('HOOK_FIRED: ' . $tag);
    }
});

这会记录所有触发的钩子名。如果你的钩子名没出现，说明触发端有问题；如果出现了但你的回调没跑，继续往下查。

第二层：回调注册确认

// 在任意位置执行，查看某个钩子的全部注册回调
global $wp_filter;
error_log(print_r($wp_filter['admin_init']->callbacks, true));

看优先级数组里有没有你的回调，以及对应的 callable 是否有效（类名对不对、方法是否 public）。

第三层：回调内部断点

如果上面两层都过了，回调第一行加 `die('I AM HERE')`。没 die 说明前面某层过滤掉了；die 了说明回调内部后续逻辑崩了，逐行往下挪定位。

六、一个让我挠头两小时的案例：AJAX 钩子的"命名空间"骗局

WordPress AJAX 的 `wp_ajax_{$action}` 和 `wp_ajax_nopriv_{$action}`，我前端请求的 action 是 `zsens_save_config`，后端却写了 `add_action('wp_ajax_zsens_config_save', ...)`。两边差了两个单词顺序，没有任何报错，前端永远收到 0。

最后是用第一层那个 `all` 钩子发现的：`wp_ajax_zsens_save_config` 确实触发了，但我的回调挂在 `wp_ajax_zsens_config_save` 上，完美错过。

现在我的 AJAX 路由统一走一个分发器，action 只传模块名和方法名，不再直接暴露底层钩子名：

// 前端统一 action=zsens_api，参数里带 module=Config&method=save
add_action('wp_ajax_zsens_api', [$this, 'dispatch']);
add_action('wp_ajax_nopriv_zsens_api', [$this, 'dispatch']);

public function dispatch() {
    $module = sanitize_key($_REQUEST['module'] ?? '');
    $method = sanitize_key($_REQUEST['method'] ?? '');
    // 内部映射，不再依赖字符串匹配
}

小结

钩子调试的核心是分层确认：钩子触发了没 → 回调注册了没 → 回调执行了没 → 回调内部崩了没。每层都有对应的排查工具，别在"代码看起来对"的层面打转。如果你有其他"钩子装死"的诡异案例，欢迎丢出来一起解剖。