WordPress 的 body_class 过滤器必须在 wp_head() 执行前（即模板渲染前）注册，若在模板中通过 do_action() 延迟调用 add_filter()，此时 body_class 钩子早已执行完毕，导致动态添加失效。
wordpress 的 `body_class` 过滤器必须在 `wp_head()` 执行前（即模板渲染前）注册，若在模板中通过 `do_action()` 延迟调用 `add_filter()`，此时 `body_class` 钩子早已执行完毕，导致动态添加失效。
在 WordPress 主题开发中，常需根据页面上下文（如特定模板、自定义条件）动态向 <body> 标签注入 CSS 类。一个常见误区是：试图在模板文件（如 page.php 或 front-page.php）中触发某个 action，再于该 action 的回调函数内调用 add_filter( 'body_class', ... )——这本质上无法生效。
原因在于 WordPress 钩子的执行时序：body_class 过滤器由 get_body_class() 函数在 wp_head() 内部调用（通常位于 <head> 区域），而此时所有模板逻辑（包括 do_action()）大多尚未执行或已滞后。一旦 apply_filters( 'body_class', ... ) 完成，后续任何 add_filter() 都将被忽略。
✅ 正确做法是：提前注册过滤器，并在其中根据运行时条件动态判断是否添加类。例如：
// 在 functions.php 中一次性注册（推荐）
add_filter( 'body_class', 'pxlr_add_no_hero_class' );
function pxlr_add_no_hero_class( $classes ) {
// 检查是否处于目标模板或满足特定条件
if ( is_page_template( 'template-no-hero.php' ) ||
( is_singular() && get_post_meta( get_the_ID(), '_disable_hero', true ) ) ||
( defined( 'PXLR_DISABLE_HERO' ) && PXLR_DISABLE_HERO ) ) {
$classes[] = 'pxlr-site-no-hero';
}
return $classes;
}⚠️ 注意事项：
- 不要依赖模板中的 do_action() 触发 add_filter() —— 时序不可控；
- 条件判断应使用 WordPress 原生函数（如 is_front_page()、is_404()、has_term() 等），避免全局变量或未初始化状态；
- 若需基于 URL 参数或用户角色等复杂逻辑，仍应在 body_class 过滤器内部处理，而非延迟注册；
- 调试技巧：在过滤器函数中 error_log( print_r( $classes, true ) ) 可验证是否被调用。
总结：WordPress 钩子机制强调“注册时机”而非“调用时机”。add_filter() 必须在对应 apply_filters() 执行前完成注册。因此，所有 body_class 相关逻辑都应统一在 functions.php（或插件主文件）中提前声明，并通过条件分支控制类的添加，这才是可靠、可维护的实现方式。
