自定义WordPress插件短代码JavaScript入队异常求助

核心问题：脚本入队时机错误 #

你当前的写法是在短代码回调里绑定wp_enqueue_scripts钩子，但这个钩子在WordPress渲染页面模板之前就已经触发完成——短代码是在模板渲染过程中才执行的，此时再绑定wp_enqueue_scripts已经晚了，脚本根本不会被加入加载队列。

你自己环境看似正常，大概率是浏览器缓存了之前测试时加载的脚本，并非当前代码的作用。

其他可能的cPanel环境因素 #

除了入队逻辑错误，cPanel托管环境的这些特性也可能导致问题：

• 文件名大小写敏感：cPanel基于Linux系统，文件名严格区分大小写。如果本地文件是js-test.js，上传后变成JS-Test.js，代码里的路径就会找不到文件，返回404，脚本自然无法执行。
• 主机缓存机制：很多cPanel主机自带OPcache、页面缓存或静态资源缓存，可能导致旧缓存未更新，新脚本没被加载。
• 优化插件干扰：部分主机预装LiteSpeed Cache、WP Rocket等优化插件，脚本合并、压缩过程中可能出错，导致脚本失效。

正确的脚本入队方案（仅在短代码存在时加载） #

方案一：全局变量标记加载需求（推荐） #

这种方法能覆盖短代码出现在任何位置（包括自定义字段、嵌套短代码）的场景：

<?php
/*
Plugin Name:  JS Test
Description:  JS Test
Version:      1.0
License:      MIT
License URI:  https://opensource.org/license/mit
*/

// 全局变量标记是否需要加载脚本
$js_test_needs_script = false;

add_shortcode( 'js_test', function( $atts, $content, $tag ) {
    global $js_test_needs_script;
    $js_test_needs_script = true;
    return "<div id='js-test'></div>";                                                
});

// 在wp_enqueue_scripts钩子中检查标记，决定是否入队
add_action('wp_enqueue_scripts', function() {
    global $js_test_needs_script;
    if ($js_test_needs_script) {
        // 最后一个参数true表示在footer加载脚本，确保DOM元素已存在
        wp_enqueue_script('js-test', plugin_dir_url(__FILE__) . 'js-test.js', array(), '1.0', true);
    }
});

方案二：检测页面内容中的短代码 #

如果短代码只出现在文章/页面的主内容里，可以用has_shortcode直接检测：

<?php
/*
Plugin Name:  JS Test
Description:  JS Test
Version:      1.0
License:      MIT
License URI:  https://opensource.org/license/mit
*/

add_action('wp_enqueue_scripts', function() {
    global $post;
    // 检查当前页面内容是否包含目标短代码
    if (isset($post) && has_shortcode($post->post_content, 'js_test')) {
        wp_enqueue_script('js-test', plugin_dir_url(__FILE__) . 'js-test.js', array(), '1.0', true);
    }
});

add_shortcode( 'js_test', function( $atts, $content, $tag ) {
    return "<div id='js-test'></div>";                                                
});

额外排查步骤 #

1. 让你的朋友打开浏览器开发者工具（F12），切换到「网络」标签，刷新页面后查看js-test.js的请求状态：如果是404，检查文件名和路径是否匹配。
2. 查看「控制台」标签，是否有脚本语法错误、加载错误的提示。
3. 暂时关闭cPanel主机的缓存插件或优化功能，测试脚本是否正常执行。

内容的提问来源于stack exchange，提问作者Paul I