必须传入 new wp_bootstrap_navwalker() 实例，否则无法生成 dropdown-menu、data-bs-toggle="dropdown" 等 bootstrap 必需结构；depth 需设为 2 才渲染下拉菜单，container_id 必须与按钮 data-bs-target 值严格一致，且 js 加载须声明 array('jquery') 依赖并置于页脚。
wp_nav_menu() 必须指定 WP_Bootstrap_Navwalker 实例
不传 walker 参数，或传错类名（比如写成 'walker' => 'WP_Bootstrap_Navwalker' 字符串），菜单就只是普通 HTML，不会生成 dropdown-menu、data-bs-toggle="dropdown" 这些 Bootstrap 必需结构。
正确写法是：
wp_nav_menu(array( 'theme_location' => 'primary', 'walker' => new WP_Bootstrap_Navwalker(), 'depth' => 2, 'container' => 'div', 'container_class'=> 'collapse navbar-collapse', 'container_id' => 'navbarNav', 'menu_class' => 'navbar-nav me-auto', ));
-
depth设为2才会渲染二级下拉；设为1就压根不输出子菜单 -
container_id必须和<button data-bs-target="#navbarNav"></button>中的#navbarNav严格一致，否则移动端折叠菜单点不开 - 如果主题已注册多个菜单位置（如
'secondary'），theme_location值要和register_nav_menus()里定义的 key 完全匹配，区分大小写
Bootstrap JS 必须在 jQuery 之后加载，且不能跳过依赖声明
WordPress 默认用 jQuery.noConflict()，而 Bootstrap 5 的 bootstrap.bundle.min.js 内部仍通过 jQuery 全局变量初始化组件。硬写 <script></script> 标签或漏传 array('jquery') 会导致 Uncaught TypeError: Cannot read properties of undefined (reading 'fn')。
必须在 functions.php 中这样注册：
function mytheme_enqueue_bootstrap() {
wp_enqueue_style('bootstrap-css', get_template_directory_uri() . '/css/bootstrap.min.css', array(), '5.3.3');
wp_enqueue_script('bootstrap-js', get_template_directory_uri() . '/js/bootstrap.bundle.min.js', array('jquery'), '5.3.3', true);
}
add_action('wp_enqueue_scripts', 'mytheme_enqueue_bootstrap');
- 第 4 个参数
array('jquery')是关键，它让 WordPress 确保jquery脚本先执行 -
$in_footer = true（最后一个参数）推荐设为true，避免 JS 在 DOM 就绪前执行，导致new bootstrap.Dropdown()失效 - 别用 CDN 链接混搭本地路径——例如 CSS 用 CDN、JS 用本地，容易因跨域或缓存策略不一致引发加载失败
class-wp-bootstrap-navwalker.php 文件路径和加载时机不能错
文件放错位置或加载太晚，PHP 会报 Fatal error: Uncaught Error: Class 'WP_Bootstrap_Navwalker' not found。
- 文件必须放在主题根目录下（如
/wp-content/themes/your-theme/class-wp-bootstrap-navwalker.php），不能放在子目录如/inc/里，除非你手动改require_once路径 - 要在
after_setup_theme钩子中加载，不是init或wp_enqueue_scripts—— 因为wp_nav_menu()在模板渲染早期就会用到这个类 - 加个存在性检查更稳妥：
if (file_exists(get_template_directory() . '/class-wp-bootstrap-navwalker.php')) { require_once ... }，避免部署遗漏时白屏
data-bs-* 属性被 WordPress 过滤？那是 wp_kses 搞的鬼
菜单项里带 data-bs-toggle="dropdown" 却不起作用，常见原因是 WordPress 后台编辑器或某些插件调用 wp_kses() 清洗了自定义属性。这不是 Navwalker 的 bug，而是输出环节被截断了。
- 检查是否在
wp_nav_menu()外层套了wp_kses_post()或类似过滤函数 - 确认没启用“纯文本模式”编辑器插件（如 Classic Editor 的某些配置），它们会主动剥离
data-属性 - 如果必须保留这些属性，可在
functions.php中扩展允许的 HTML 属性：add_filter('wp_kses_allowed_html', 'allow_data_bs_attributes');，然后定义该函数放开data-bs-*前缀
最常被忽略的一点：Bootstrap 5 的下拉菜单依赖 Popper 定位逻辑，但 bootstrap.bundle.min.js 已内置 Popper，所以只要 JS 加载顺序和依赖正确，定位问题基本不存在；真正卡住的，90% 是 walker 没传、container_id 不匹配、或 data-bs- 被过滤这三处。
