主题与 WooCommerce 商店页布局冲突：模板覆盖与钩子调整

引言：商店页比文章页宽一截，侧边栏掉到了下面

装完 WooCommerce 后最常见的视觉事故：文章页是正常的「内容区 + 右栏」，商店页却变成全宽，或者反过来把侧边栏挤到了内容下方。商品列表的卡片宽度也不对，一行三个变成一行两个，间距错乱。还有的主题会出现两个 <main>、两个 <h1>，页面结构直接重复。

这类问题不是 CSS 写错，而是容器结构冲突：主题自己有一套「打开容器—输出内容—关闭容器」的包装逻辑，WooCommerce 也有一套。两边都往 woocommerce_before_main_content / woocommerce_after_main_content 上挂了输出，结果是嵌套或重复。另一种情况是主题压根没声明 WooCommerce 支持，WooCommerce 会回退到 page.php，而 page.php 的容器结构又是为普通页面设计的。本文按「声明支持 → 统一容器 → 调整循环元素 → 覆盖模板」的顺序处理。

原理分析：两套容器机制怎么打架

WooCommerce 默认用 woocommerce_output_content_wrapper()（挂在 woocommerce_before_main_content，优先级 10）和 woocommerce_output_content_wrapper_end()（挂在 woocommerce_after_main_content，优先级 10）输出 <div class="woocommerce"> 之类的包装层。

主题侧有两种接入方式：

• 方式 A：woocommerce.php。主题根目录放一个 woocommerce.php，它的优先级高于 page.php 和 archive-product.php 的容器部分，所有 WooCommerce 页面都走它。缺点是所有商店页共用一个外壳，商品详情页想换版式就得在文件里加条件分支。
• 方式 B：钩子 + 模板覆盖。用 add_theme_support( 'woocommerce' ) 声明支持，再用 remove_action 摘掉 WooCommerce 自带的包装函数，换成主题自己的容器；具体列表结构通过子主题 woocommerce/ 目录下的模板文件覆盖。

声明支持时还可以传参数指定图片宽度和网格默认值，这些值会影响生成的缩略图尺寸与 product_grid 布局。另外 is_shop()、is_product_category()、is_product() 这组条件标签是做分支的依据，别用 is_page() 去猜。

模板覆盖的目录规范与查找顺序见 WooCommerce 模板覆盖规范，这里只处理容器与钩子部分。

保姆级实操

1. 声明主题支持：在子主题 after_setup_theme 里调用 add_theme_support( 'woocommerce' )，并传入缩略图宽度与商品网格默认参数。注意：声明之后 WooCommerce 后台「状态 → 主题支持」会显示为「已声明」。
2. 摘掉插件默认包装：用 remove_action 移除 woocommerce_output_content_wrapper 与对应的结束函数，优先级必须写 10，与注册时一致。
3. 挂上主题自己的容器：换成主题自己的 content-area / site-main 结构，保证和文章页完全一致。
4. 处理侧边栏：如果主题在商店页也想带侧边栏，把 woocommerce_sidebar 上的 woocommerce_get_sidebar 移除，改成调用主题侧边栏；不需要则直接移除。
5. 调整循环元素：商品卡片里的缩略图、标题、价格、按钮分别挂在 woocommerce_before_shop_loop_item_title、woocommerce_shop_loop_item_title、woocommerce_after_shop_loop_item_title 上，按需移除或调整优先级。
6. 重新生成缩略图：改完图片宽度后到「WooCommerce → 状态 → 工具」里执行「重新生成缩略图」，否则旧图仍是老尺寸。

<?php
// 子主题 functions.php：声明 WooCommerce 支持
add_action( 'after_setup_theme', function() {
    add_theme_support( 'woocommerce', array(
        'thumbnail_image_width' => 400,
        'single_image_width'    => 800,
        'product_grid'          => array(
            'default_rows'    => 3,
            'min_rows'        => 2,
            'max_rows'        => 8,
            'default_columns' => 3,
            'min_columns'     => 2,
            'max_columns'     => 4,
        ),
    ) );
} );

<?php
// 用主题自己的容器替换 WooCommerce 默认包装层
remove_action( 'woocommerce_before_main_content', 'woocommerce_output_content_wrapper', 10 );
remove_action( 'woocommerce_after_main_content', 'woocommerce_output_content_wrapper_end', 10 );

add_action( 'woocommerce_before_main_content', 'mimangfei_wrapper_start', 10 );
function mimangfei_wrapper_start() {
    echo '<div id="primary" class="content-area"><main id="main" class="site-main woocommerce-main">';
}

add_action( 'woocommerce_after_main_content', 'mimangfei_wrapper_end', 10 );
function mimangfei_wrapper_end() {
    echo '</main></div>';
}

<?php
// 侧边栏：移除插件默认侧边栏，改用主题侧边栏
remove_action( 'woocommerce_sidebar', 'woocommerce_get_sidebar', 10 );
add_action( 'woocommerce_sidebar', function() {
    if ( is_shop() || is_product_category() || is_product_tag() ) {
        get_sidebar( 'shop' ); // 对应 sidebar-shop.php
    }
}, 10 );

// 商品卡片：去掉循环里的评分，改价格与按钮顺序
remove_action( 'woocommerce_after_shop_loop_item_title', 'woocommerce_template_loop_rating', 5 );
remove_action( 'woocommerce_after_shop_loop_item', 'woocommerce_template_loop_add_to_cart', 10 );
add_action( 'woocommerce_after_shop_loop_item_title', 'woocommerce_template_loop_add_to_cart', 15 );

<?php
// 用 body_class 针对商店页做精细样式
add_filter( 'body_class', function( $classes ) {
    if ( is_shop() || is_product_category() ) {
        $classes[] = 'has-shop-sidebar';
    }
    if ( is_product() ) {
        $classes[] = 'product-full-width';
    }
    return $classes;
} );

常见踩坑

• remove_action 优先级写错：注册时是 10，移除时不填或填 1 都摘不掉。移除优先级必须与注册时一致。
• 移除时机太早：在插件函数注册之前就调用 remove_action，等于没删。包在 after_setup_theme 或 wp_loaded 里执行最稳。
• 同时用 woocommerce.php 和钩子替换：二者叠加会输出两层容器，页面出现重复的 <main>。二选一。
• 声明支持后没重新生成缩略图：thumbnail_image_width 改大，但已有图片仍是旧尺寸，前台看着模糊。
• 用 is_page( 'shop' ) 判断商店页：商店页是由 WooCommerce 动态生成的归档页，正确写法是 is_shop()。
• 案例：一个外贸站换了新主题后，商品详情页出现两个 <h1>，Google Search Console 报「重复的标题标签」。排查发现主题的 woocommerce.php 输出了一次页面标题，WooCommerce 的 woocommerce_single_product_summary 又输出了一次商品标题。最终删掉 woocommerce.php 里的标题输出，改用 woocommerce_before_main_content 钩子统一控制，结构重复问题解决。
• 改完没清缓存：开了页面缓存的站点，改钩子后必须先清缓存再验证，否则会误判为「改动无效」。缓存刷新做法见 WordPress 更新后缓存未刷新处理。

总结

遇到商店页布局冲突，先看主题有没有声明 add_theme_support('woocommerce')，这一条能解决一半问题；再看是否出现双重容器，有就摘掉一方；最后才动循环元素和模板覆盖。判断标准很直接：把商店页和文章页的 DOM 结构放在一起对比，<main> 只能有一个，容器类名应当完全一致。整个改动都应该写在子主题里，父主题升级不会丢。若只是调整某一段文案而不想复制整份模板，优先用钩子挂载，这比覆盖模板的长期维护成本低得多，具体原则见 WooCommerce 模板覆盖规范。