HTML模板转换为Wordpress后Ekko-Lightbox无法正常工作问题咨询

• 资源加载顺序&依赖检查
  Ekko-Lightbox 依赖 jQuery 与 Bootstrap 核心JS，注册引入时必须明确声明依赖，确保加载顺序为 jQuery → Bootstrap JS → Ekko-Lightbox JS，CSS 资源需在头部加载。示例正确的functions.php注册写法：

  // 注册加载样式
  add_action('wp_enqueue_scripts', 'custom_enqueue_assets');
  function custom_enqueue_assets() {
    // 先加载Bootstrap CSS
    wp_enqueue_style('bootstrap-css', get_template_directory_uri() . '/css/bootstrap.min.css', array(), '5.3.0');
    // 再加载灯箱CSS
    wp_enqueue_style('ekko-lightbox-css', get_template_directory_uri() . '/css/ekko-lightbox.css', array('bootstrap-css'), '5.3.0');
    
    // 加载JS，最后一个参数设为true表示放在页脚加载
    wp_enqueue_script('jquery'); // 调用WordPress自带jQuery
    wp_enqueue_script('bootstrap-js', get_template_directory_uri() . '/js/bootstrap.bundle.min.js', array('jquery'), '5.3.0', true);
    wp_enqueue_script('ekko-lightbox-js', get_template_directory_uri() . '/js/ekko-lightbox.min.js', array('jquery', 'bootstrap-js'), '5.3.0', true);
  }
  

  若使用子主题，需将get_template_directory_uri替换为get_stylesheet_directory_uri避免路径错误。
• DOM节点属性检查
  Ekko-Lightbox 不会自动识别图片链接，需要给包裹图片的<a>标签添加指定属性：
  • 必须加data-toggle="lightbox"属性
  • 链接href属性必须指向原图地址，不能是缩略图地址
  • 多图分组需加data-gallery="分组名"属性
    若你是通过WordPress动态输出文章/图库内容，需要在循环输出时手动给图片链接追加上述属性，不能直接沿用静态HTML的默认输出逻辑。
• 初始化脚本配置
  仅引入资源不会自动触发灯箱功能，需额外添加初始化JS代码，可追加到主题自带的自定义JS文件中，也可以通过钩子输出到页脚：

  // 适配WordPress jQuery noConflict模式，用jQuery代替$符号避免报错
  jQuery(document).on('click', '[data-toggle="lightbox"]', function(event) {
    event.preventDefault();
    jQuery(this).ekkoLightbox();
  });
  

• 冲突排查
  1. 打开浏览器F12控制台，查看是否有$ is not defined、ekkoLightbox is not a function类报错，前者是jQuery未正确加载/符号冲突，后者是灯箱JS加载顺序错误
  2. 检查是否存在其他灯箱插件、主题自带灯箱功能冲突，临时停用其他相关插件测试
  3. 检查灯箱容器样式的z-index值，若被其他固定定位元素遮挡，可手动添加CSS将.ekko-lightbox-container的z-index设为9999以上

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