WordPress子主题中插件短码的Action hooks失效问题排查

我正在开发一个自定义WordPress插件，通过短码在特定页面展示内容。开发阶段本地启用Twenty Twenty-Four主题时功能正常，但切换到生产环境使用的Scapeshot子主题Scapeshot Wedding后，插件完全失效——所有入队的脚本和样式均未加载到DOM中，本地切换该主题也复现了相同问题。

为验证问题，我编写了极简测试插件：

<?php
/*
Plugin Name: Test Plugin
Description: A minimal plugin to test hooks.
Version: 1.0
Author: Test Author
*/

// Log after the header or footer
add_action('wp_head', function () {
  global $wp_scripts, $wp_styles;
  foreach ($wp_scripts->queue as $handle) {
      error_log('Script Enqueued: ' . $handle . ' (hook: wp_footer)');
  }
  foreach ($wp_styles->queue as $handle) {
      error_log('Style Enqueued: ' . $handle . ' (hook: wp_footer)');
  }
});

add_action('wp_enqueue_scripts', function(){
  error_log('Outside shortcode enqueue action');
});

// Add Shortcode for Registration Form with Nonce
function test_shortcode()
{
    error_log('test_shortcode');
    function enqueue_styles_and_scripts()
    {
        error_log('Enqueue1');
    }
    add_action('wp_enqueue_scripts', 'enqueue_styles_and_scripts', 0);

    // Enqueue JavaScript
    function enqueue_custom_registration_scripts()
    {
        error_log('Enqueue2');
    }
    add_action('wp_enqueue_scripts', 'enqueue_custom_registration_scripts', 0);   
}
add_shortcode('custom_registration_form', 'test_shortcode');

测试结果：

• 启用Twenty Twenty-Four主题时，日志正常记录test_shortcode、Enqueue1、Enqueue2；
• 启用Scapeshot Wedding主题时，仅test_shortcode被记录，Enqueue1和Enqueue2完全未触发，且wp_enqueue_scripts的外部动作执行时间早于短码。

核心问题 #

wp_enqueue_scripts钩子在短码执行前就已触发完毕，导致短码内部注册的动作钩子没有执行机会。

具体排查点 #

• 主题模板文件（header.php、页面模板）：

  • 检查header.php中是否在调用wp_head()函数之前就输出了大量内容，或者是否存在手动触发wp_enqueue_scripts、wp_print_scripts()/wp_print_styles()的代码，导致钩子提前执行。
  • 查看自定义页面模板（如page.php、自定义模板文件）是否跳过了WordPress标准钩子流程，比如未正确调用wp_enqueue_scripts相关动作。

• 主题functions.php（父/子主题）：

  • 排查是否有代码手动调用do_action('wp_enqueue_scripts')，强制提前触发钩子。
  • 检查是否存在remove_action或修改add_action优先级的代码，改变了wp_enqueue_scripts的默认执行顺序。
  • 查看子主题是否继承或覆盖了父主题的异常逻辑，比如父主题提前触发钩子，子主题未修正。

• 钩子流程中断：

  • 检查主题是否有自定义的wp_enqueue_scripts处理函数，是否使用了remove_all_actions等操作终止了钩子的后续执行。

• 短码解析时机差异：

  • 对比两个主题的短码解析时机：Twenty Twenty-Four可能在wp_enqueue_scripts触发前解析短码，而Scapeshot Wedding在钩子触发后才解析，导致短码内的钩子注册无效。

额外提示 #

你的测试代码存在写法问题：不要在短码函数内部定义子函数，多次调用短码会触发函数重复定义错误。正确做法是将脚本入队逻辑放在短码外部，通过判断页面是否包含目标短码来决定是否入队，或者直接在wp_enqueue_scripts钩子中完成入队操作。

内容的提问来源于stack exchange，提问作者Sjors Hijgenaar