صفحه فروشگاه را باز می‌کنید، می‌خواهید فیلتر قیمت یا فیلتر دسته‌بندی یا فیلتر رنگ را اعمال کنید و هیچ اتفاقی نمی‌افتد. روی گزینه کلیک می‌کنید، لودینگ می‌چرخد و ناپدید می‌شود، ولی لیست محصولات همان است که بود. یا حتی ویجت فیلتر در سایدبار وجود ندارد و چیزی برای فیلتر کردن در دسترس نیست. اگر با خطای عدم کارکرد فیلترهای ووکامرس روبرو هستید، این مقاله همان مسیری را طی می‌کند که در سال‌ها کار روی صدها فروشگاه اینترنتی ووکامرس بارها پیموده‌ام. فیلترهای ووکامرس از نظر فنی پیچیده‌تر از آنچه به‌نظر می‌رسند: ترکیبی از ویجت‌های وردپرس، کوئری‌های سفارشی ووکامرس، درخواست‌های AJAX، و پارامترهای URL که باید با هم هماهنگ باشند. وقتی یکی از این چهار بخش از کار می‌افتد، نتیجه یک فیلتر ظاهراً سالم است که هیچ کاری نمی‌کند. در عمل این خطا همیشه در یکی از پنج لایه مشخص ریشه دارد: ثبت و نمایش نادرست ویجت‌های فیلتر، خطا در اجرای فیلترهای AJAX و جاوااسکریپت، ساختار URL و پیوندهای یکتا، داده‌های نادرست ویژگی و دسته‌بندی محصول، و تعارض با قالب، کش یا افزونه‌های دیگر. اگر این پنج لایه را به ترتیب بررسی کنید، تقریباً همیشه به علت دقیق می‌رسید بدون آنکه ساعت‌ها وقت خود را صرف آزمون‌وخطا کنید.

فیلترهای ووکامرس کار نمی‌کنند — تفکیک نشانه‌ها

قبل از هر اقدامی باید مشخص کنید کدام یک از این شش نشانه را می‌بینید، چون هرکدام جهت عیب‌یابی را به لایه متفاوتی هدایت می‌کند. نشانه اول: هیچ ویجت فیلتری در سایدبار فروشگاه دیده نمی‌شود. این حالت مستقیماً به لایه اول (ثبت و نمایش ویجت) اشاره دارد. اگر با معماری کلی فروشگاه ووکامرس آشنایی ندارید، پیش از ادامه نگاهی به ووکامرس چیست و چگونه فروشگاه اینترنتی بسازیم بیندازید تا لایه‌بندی و رفتار ووکامرس را در ذهن داشته باشید.

نشانه دوم: ویجت فیلتر در سایدبار هست، ولی وقتی روی گزینه‌ای کلیک می‌کنید، هیچ اتفاقی نمی‌افتد یا صفحه ریلود می‌شود ولی لیست محصولات تغییر نمی‌کند. این حالت به لایه دوم (AJAX و JS) یا لایه سوم (URL و پیوند یکتا) برمی‌گردد. نشانه سوم: فیلتر روی محصولات اعمال می‌شود ولی نتیجه خالی است — یعنی صفحه‌ای باز می‌شود با پیام «هیچ محصولی یافت نشد». این نشانه معمولاً به لایه چهارم (داده‌های ویژگی و دسته‌بندی) مربوط می‌شود. نشانه چهارم: فیلتر در برخی مرورگرها کار می‌کند و در برخی دیگر نه. این حالت به لایه دوم (AJAX و JS) یا لایه پنجم (کش) اشاره دارد. نشانه پنجم: فیلتر کار می‌کند ولی نتیجه‌اش با انتظار شما فرق دارد — مثلاً فیلتر قیمت، محصولاتی با قیمت خارج از بازه را نشان می‌دهد. این نشانه به لایه چهارم (داده‌های ویژگی) یا به فیلتر سفارشی قالب برمی‌گردد. نشانه ششم: فیلتر در نسخه دسکتاپ کار می‌کند ولی در موبایل نه، یا برعکس. این حالت معمولاً به CSS قالب یا اسکریپت‌های موبایل مربوط می‌شود.

در عیب‌یابی فیلترهای ووکامرس، اولین سؤال این نیست که «چرا فیلتر اعمال نمی‌شود» بلکه این است «فیلتر در کدام مرحله از چرخه، از کار می‌افتد؟» — در زمان نمایش ویجت، در زمان کلیک کاربر، در زمان ساخت query، یا در زمان رندر نتیجه. هر مرحله، لایه متفاوتی دارد.

سیستم فیلتر در ووکامرس چطور کار می‌کند؟

فیلترهای ووکامرس از چهار لایه مستقل تشکیل شده‌اند که باید با هم هماهنگ باشند. لایه اول: ویجت‌های وردپرس که در سایدبار ثبت می‌شوند و گزینه‌های فیلتر (دسته‌بندی، قیمت، ویژگی، امتیاز) را نمایش می‌دهند. لایه دوم: پارامترهای URL که به‌صورت ?filter_color=red&min_price=100000 در آدرس صفحه ظاهر می‌شوند. لایه سوم: کوئری سفارشی ووکامرس که این پارامترها را می‌خواند و WP_Query را با فیلترهای اضافی اجرا می‌کند. لایه چهارم: HTML خروجی که فایل‌های template ووکامرس و قالب تولید می‌کنند. اگر هر یک از این چهار لایه به‌درستی کار نکند، نتیجه یک فیلتر ظاهراً سالم است که اثر عملی ندارد. برای مرور معماری کلی ووکامرس، تنظیمات اولیه ووکامرس برای ساخت فروشگاه پیش‌زمینه خوبی می‌دهد.

نکته مهم که در پروژه‌های واقعی بارها دیده‌ام: فیلترهای پیش‌فرض ووکامرس فقط با فیلترهای «پایه» کار می‌کنند که شامل دسته‌بندی، ویژگی‌های محصول، قیمت، و امتیاز هستند. اگر محصولات شما ویژگی‌های سفارشی دارند که در ووکامرس به‌عنوان «ویژگی» ثبت نشده‌اند (مثلاً فیلدهای Custom Fields)، فیلتر ووکامرس آن‌ها را نمی‌بیند. این مسئله یکی از شایع‌ترین سوءتفاهم‌های فروشگاه‌های تازه‌کار است و در بخش لایه چهارم به تفصیل به آن می‌پردازم. همچنین باید توجه کنید که فیلترهای ووکامرس از مکانیزم «taxonomy» وردپرس استفاده می‌کنند، نه از متادیتای محصول. اگر با مفهوم ساخت طبقه‌بندی سفارشی در وردپرس آشنا نیستید، مرور آن به درک این مکانیزم کمک می‌کند.

نوع فیلترمبنای دادهنمونه پارامتر URL
دسته‌بندیtaxonomy product_cat?product_cat=shoes
برچسبtaxonomy product_tag?product_tag=sale
ویژگی (attribute)taxonomy pa_{name}?filter_color=red
قیمتمتادیتا _price?min_price=100000
موجودیمتادیتا _stock_status?stock_status=instock
امتیازمتادیتا _wc_average_rating?rating_filter=4

این جدول نشان می‌دهد هر فیلتر به کدام منبع داده متصل است. اگر فیلتر دسته‌بندی کار می‌کند ولی فیلتر ویژگی نه، احتمالاً مسئله در ثبت ویژگی‌ها به‌عنوان taxonomy است. اگر فیلتر قیمت کار نمی‌کند، احتمالاً مسئله در ساختار URL یا در کوئری سفارشی قالب است. تشخیص دقیق اینکه فیلتر به کدام لایه متصل است، نیمی از عیب‌یابی است.

لایه اول — ثبت و نمایش ویجت‌های فیلتر

شایع‌ترین علت عدم کارکرد فیلترهای ووکامرس، نبود ویجت‌ها در سایدبار است. اگر در صفحه فروشگاه شما بخشی برای فیلتر وجود ندارد، نمی‌توانید انتظار داشته باشید فیلترها کار کنند. سه زیرگروه مهم در این لایه وجود دارد.

ثبت سایدبار در قالب فروشگاهی

ووکامرس برای نمایش ویجت‌های فیلتر، به یک سایدبار نیاز دارد که قالب شما باید ثبت کرده باشد. اگر قالب شما فقط یک سایدبار عمومی دارد که در صفحه فروشگاه نمایش داده نمی‌شود، ویجت‌های فیلتر هیچ‌جا ظاهر نمی‌شوند. راه‌حل: ابتدا بررسی کنید که قالب شما سایدبار اختصاصی ووکامرس دارد یا نه. اگر ندارد، می‌توانید یک سایدبار سفارشی برای صفحه فروشگاه ثبت کنید:

add_action( 'widgets_init', 'mytheme_register_shop_sidebar' );

function mytheme_register_shop_sidebar() {
    register_sidebar( array(
        'name'          => 'سایدبار فروشگاه',
        'id'            => 'shop-sidebar',
        'description'   => 'ویجت‌های فیلتر محصولات ووکامرس',
        'before_widget' => '<div id="%1$s" class="widget %2$s">',
        'after_widget'  => '</div>',
        'before_title'  => '<h3 class="widget-title">',
        'after_title'   => '</h3>',
    ) );
}

سپس در فایل archive-product.php قالب فرزند، این سایدبار را نمایش دهید:

<?php if ( is_active_sidebar( 'shop-sidebar' ) ) : ?>
    <aside class="shop-filters">
        <?php dynamic_sidebar( 'shop-sidebar' ); ?>
    </aside>
<?php endif; ?>

نکته مهم: این کد باید در قالب فرزند قرار گیرد نه قالب والد. اگر فایل‌های قالب والد را مستقیماً ویرایش کنید، با اولین به‌روزرسانی قالب، تغییرات شما پاک می‌شود. اصول کار با قالب فرزند در قالب چایلد وردپرس چیست و چه زمانی به آن نیاز داریم توضیح داده شده است.

قابلیت پشتیبانی ووکامرس در قالب

قالب‌های وردپرس که رسماً از ووکامرس پشتیبانی نمی‌کنند، معمولاً سایدبار فروشگاه را نمایش نمی‌دهند حتی اگر شما ویجت فیلتر را در پیشخوان به سایدبار اضافه کنید. راه تشخیص: در پیشخوان به «نمایش ← ابزارک‌ها» بروید و ببینید آیا سایدبار فروشگاه در فهرست سایدبارها وجود دارد یا نه. اگر وجود ندارد، قالب شما پشتیبانی از ووکامرس را اعلام نکرده. راه‌حل: قالب خود را به یک قالب سازگار با ووکامرس تغییر دهید یا از طریق قالب فرزند، سایدبار اختصاصی ووکامرس را به قالب اضافه کنید. فهرست قالب‌های تأییدشده در بهترین قالب‌های سازگار با ووکامرس آمده است. تفاوت‌های فنی قالب‌های سازگار با ووکامرس در قالب‌های وردپرس مناسب ووکامرس چه ویژگی‌هایی دارند توضیح داده شده است.

ثبت نشدن ویجت‌های ووکامرس در ابزارک‌ها

گاهی ویجت‌های ووکامرس (مثل فیلتر قیمت، فیلتر ویژگی، فیلتر دسته‌بندی) در فهرست ابزارک‌های پیشخوان دیده نمی‌شوند. این مسئله معمولاً به دو علت برمی‌گردد: اول، ووکامرس به‌درستی لود نشده یا نسخه‌اش قدیمی است که با نسخه وردپرس ناسازگاری دارد. دوم، افزونه‌ای که مدیریت ویجت‌ها را برعهده دارد (مثل برخی افزونه‌های امنیتی یا مدیریتی) ویجت‌های ووکامرس را مخفی کرده است. راه‌حل: ابتدا ووکامرس را به آخرین نسخه به‌روز کنید، سپس افزونه‌های اخیر را یک‌به‌یک غیرفعال و تست کنید. اگر با این مشکل روبرو هستید، مرور رفع خطاهای رایج ووکامرس دید کامل‌تری می‌دهد.

تعارض با ویرایشگر بلوکی گوتنبرگ

از وردپرس ۵.۸ به بعد، ویرایشگر ویجت‌ها به سیستم بلوکی گوتنبرگ منتقل شد. در این ویرایشگر، ویجت‌های کلاسیک ووکامرس به‌عنوان بلوک «Legacy Widget» نمایش داده می‌شوند. اگر این تبدیل به‌درستی انجام نشود یا ووکامرس با نسخه فعلی وردپرس سازگار نباشد، فیلترها در ویرایشگر جدید ظاهر نمی‌شوند. راه‌حل: نسخه‌های وردپرس و ووکامرس را هم‌راستا کنید. اگر می‌خواهید فیلترها را به‌صورت بومی بلوکی داشته باشید، افزونه‌های فیلتر مدرن که در بهترین افزونه‌های کاربردی برای ووکامرس معرفی کرده‌ام، این امکان را دارند.

در بافت ویجت‌ها، «نبودن» همیشه یک باگ نیست؛ گاهی نبودن به‌معنی نبود جای نمایش است. اگر قالب شما سایدبار فروشگاه را نمایش نمی‌دهد، افزودن ویجت فیلتر هم کمکی نمی‌کند — باید ابتدا جای نمایش را در قالب درست کنید.

لایه دوم — فیلترهای AJAX و خطاهای جاوااسکریپت

لایه دوم جایی است که ویجت‌های فیلتر در سایدبار نمایش داده می‌شوند ولی وقتی کاربر روی گزینه‌ای کلیک می‌کند، فیلتر اعمال نمی‌شود. این لایه در فروشگاه‌هایی که از فیلترهای AJAX استفاده می‌کنند شایع‌تر است.

خطاهای JavaScript در فیلترهای AJAX

فیلترهای AJAX برای اعمال فیلتر، از JavaScript استفاده می‌کنند. اگر خطایی در این کد رخ دهد، کلیک کاربر پردازش نمی‌شود و لیست محصولات تغییر نمی‌کند. اولین گام برای تشخیص، باز کردن کنسول مرورگر و بررسی خطاهای JavaScript است:

  1. در مرورگر، کلید F12 را بزنید تا Developer Tools باز شود.
  2. به تب Console بروید و سپس روی فیلتر کلیک کنید.
  3. هر خطای قرمز که ظاهر می‌شود، سرنخ اصلی است.

خطاهای رایج شامل این موارد است: Uncaught TypeError: Cannot read property of undefined که نشان می‌دهد jQuery یا داده‌های فیلتر به‌درستی بارگذاری نشده‌اند، Uncaught ReferenceError: wc_add_to_cart_params is not defined که نشان می‌دهد اسکریپت ووکامرس پیش از اسکریپت فیلتر لود نشده، و Uncaught SyntaxError که نشان می‌دهد فایل JS فیلتر شما به‌دلیل minify تهاجمی شکسته است. برای مرور دقیق این نوع خطاها، خطای عدم بارگذاری JS افزونه را ببینید — همان اصول در بافت فیلترهای ووکامرس هم صادق است.

بارگذاری نادرست jQuery و اسکریپت‌های وابسته

فیلترهای ووکامرس به jQuery وابسته‌اند و اگر این کتابخانه پیش از اسکریپت فیلتر بارگذاری نشود، همه فیلترهای AJAX از کار می‌افتند. راه‌حل: در کد فیلتر خود، وابستگی‌ها را صریح تعریف کنید:

wp_enqueue_script(
    'my-ajax-filter',
    plugins_url( 'assets/js/filter.js', __FILE__ ),
    array( 'jquery', 'wc-add-to-cart' ), // وابستگی‌های صریح
    '1.0.0',
    true
);

نکته مهم: در ووکامرس، اسکریپت‌های مربوط به صفحه فروشگاه با handleهای خاصی مثل wc-add-to-cart، wc-cart-fragments و woocommerce ثبت می‌شوند. اگر فیلتر شما به یکی از این‌ها وابسته است، باید handle دقیق را در آرایه وابستگی‌ها بیاورید. اصول دقیق هوک‌ها و ترتیب بارگذاری در نحوه استفاده صحیح از هوک‌های وردپرس و اشتباهات رایج در اشتباهات رایج هنگام استفاده از هوک‌ها توضیح داده شده است.

تعارض با افزونه‌های بهینه‌ساز JS

افزونه‌های بهینه‌ساز مثل Autoptimize یا WP Rocket که JS را combine، minify یا defer می‌کنند، می‌توانند اسکریپت فیلتر ووکامرس را به‌طور ناخواسته بشکنند. نشانه: در کنسول مرورگر، خطای Uncaught ReferenceError مربوط به یک تابع فیلتر یا Unexpected token در فایل ترکیب‌شده. راه‌حل: در تنظیمات افزونه بهینه‌ساز، اسکریپت‌های فیلتر ووکامرس را از فرآیند combine و defer استثنا کنید. برای مرور کامل رفتار افزونه‌های کش و بهینه‌ساز در بافت ووکامرس، بهترین افزونه‌های کش وردپرس را ببینید.

درخواست AJAX نادرست یا مسدودشده

در فروشگاه‌های ووکامرس، فیلترها معمولاً با درخواست به admin-ajax.php یا در نسخه‌های مدرن به wp-json/wc/store/v1/products کار می‌کنند. اگر این مسیرها توسط افزونه امنیتی، فایل .htaccess یا قوانین سرور مسدود شده باشند، فیلترها کار نمی‌کنند. راه تشخیص: در تب Network مرورگر، روی فیلتر کلیک کنید و ببینید درخواست AJAX با چه کد وضعیتی برمی‌گردد. اگر کد ۴۰۳ یا ۴۰۱ دیدید، مسیر مسدود است. اگر کد ۲۰۰ ولی بدنه خالی، مسئله در کد سمت سرور است. برای مرور کامل این نوع مسائل، چگونه افزونه مشکل‌ساز وردپرس را پیدا کنیم را ببینید.

لایه سوم — ساختار URL و پیوندهای یکتا

لایه سوم جایی است که ویجت‌ها و اسکریپت‌ها درست کار می‌کنند ولی وقتی فیلتر اعمال می‌شود، URL نادرست ساخته می‌شود و query ووکامرس پارامترها را نمی‌خواند. این لایه به ساختار پیوندهای یکتا و بازنویسی rewrite مربوط می‌شود.

پیوندهای یکتا و بازنویسی rewrite

ووکامرس برای فیلترها، پارامترهای URL را با ساختار خاصی می‌خواند. اگر پیوندهای یکتا درست تنظیم نشده باشند یا فایل .htaccess نادرست باشد، پارامترهای URL به کوئری ووکامرس نمی‌رسند. راه‌حل ساده و شایع: در پیشخوان به «تنظیمات ← پیوندهای یکتا» بروید، بدون تغییر چیزی روی دکمه «ذخیره تغییرات» کلیک کنید. سپس در «ووکامرس ← وضعیت ← ابزارها» گزینه «بازسازی پیوندهای یکتا» را اجرا کنید. در بیشتر موارد، این دو اقدام ساده مشکل را حل می‌کند. اگر با مفهوم پیوندهای یکتا آشنا نیستید، URL را حرفه‌ای بسازید: ساختار و سئو را ببینید.

ساختار URL پیش‌فرض ووکامرس

ووکامرس به‌طور پیش‌فرض از ساختار /product-category/ برای دسته‌بندی و ?filter_{attribute}={value} برای ویژگی‌های محصول استفاده می‌کند. اگر قالب یا افزونه‌ای این ساختار را تغییر داده باشد و ساختار جدید با فیلترهای شما ناسازگار باشد، فیلتر کار نمی‌کند. راه تشخیص: در مرورگر، روی فیلتر کلیک کنید و URL نهایی را بررسی کنید. اگر URL با ساختار پیش‌فرض ووکامرس تفاوت داشت، مسئله در بازنویسی است. راه‌حل: در تنظیمات ووکامرس، بخش «محصولات ← پیوندهای یکتا» را بررسی کنید و اگر قالبی این ساختار را تغییر داده، آن را به حالت پیش‌فرض ووکامرس برگردانید.

سازگاری با سئوی دوستانه

بعضی افزونه‌های سئو و بازنویسی URL، پارامترهای ووکامرس را حذف یا تغییر می‌دهند. مثلاً یک افزونه که URLهای «تمیز» تولید می‌کند، ممکن است پارامترهای فیلتر را به ساختار متفاوتی تبدیل کند. نتیجه: فیلتر ظاهراً اعمال می‌شود ولی query ووکامرس پارامترها را نمی‌شناسد. راه‌حل: اگر از افزونه‌ای استفاده می‌کنید که بازنویسی URL انجام می‌دهد، در تنظیمات آن، مسیر /shop/ و /product-category/ را استثنا کنید یا نسخه افزونه را با ووکامرس تست کنید. اصول سئوی فروشگاه در سئو فروشگاه ووکامرس چگونه انجام می‌شود آمده است.

سازگاری با CDN و پارامترهای query string

برخی CDNها، پارامترهای query string را در فرآیند caching نادیده می‌گیرند و همیشه نسخه اول صفحه را برمی‌گردانند. نتیجه: فیلتر در ظاهر اعمال می‌شود ولی صفحه هیچ‌وقت تغییر نمی‌کند. راه‌حل: در تنظیمات CDN، پارامترهای query ووکامرس (مثل filter_*، min_price، max_price، orderby) را در فهرست پارامترهای کش-محور قرار دهید تا هر ترکیب، نسخه جداگانه‌ای از صفحه را کش کند. برای مرور نقش CDN در بافت ووکامرس، CDN چگونه سرعت سایت را بهبود می‌دهد را ببینید.

لایه چهارم — داده‌های ویژگی و دسته‌بندی محصول

لایه چهارم جایی است که همه چیز از نظر فنی درست است ولی داده‌های محصول به‌گونه‌ای است که فیلتر نمی‌تواند به آن‌ها اعمال شود. این لایه در فروشگاه‌هایی که محصولات زیادی دارند یا ساختار دسته‌بندی پیچیده‌ای دارند شایع‌تر است.

ویژگی‌های محصول و taxonomy

فیلتر ویژگی ووکامرس فقط روی ویژگی‌هایی کار می‌کند که به‌عنوان «ویژگی جهانی» (Global Attribute) ثبت شده باشند. اگر ویژگی محصول شما در ویرایش محصول، به‌عنوان «ویژگی سفارشی» (Custom Product Attribute) وارد شده باشد، در فیلتر نمایش داده نمی‌شود. این مسئله یکی از شایع‌ترین خطاهای فروشگاه‌های تازه‌کار است.

راه‌حل: به «محصولات ← ویژگی‌ها» بروید و ویژگی مورد نظر را به‌عنوان ویژگی جهانی ثبت کنید. سپس در ویرایش محصول، از پنل «ویژگی‌ها»، مقدار مورد نظر را از همان ویژگی جهانی انتخاب کنید. برای مرور ساختار ویژگی‌ها و تفاوت آن‌ها با فیلدهای سفارشی، چگونه محصول جدید در ووکامرس ایجاد کنیم و انواع محصولات در ووکامرس و تفاوت آن‌ها را ببینید.

محصولات متغیر و فیلتر ویژگی

در محصولات متغیر (variable products)، ویژگی‌های variation به‌عنوان پایه ساخت variationها استفاده می‌شوند و باید به‌عنوان ویژگی جهانی ثبت شده باشند. اگر با variationها کار می‌کنید و فیلتر ویژگی کار نمی‌کند، احتمالاً یکی از دو مسئله است: اول، ویژگی به‌عنوان ویژگی سفارشی ثبت شده به‌جای ویژگی جهانی. دوم، ویژگی روی variation اعمال شده ولی روی محصول اصلی (parent) نه. فیلتر ووکامرس روی محصول اصلی اعمال می‌شود، پس ویژگی باید در سطح parent هم نمایش داده شود. راه‌حل: در ویرایش محصول متغیر، مطمئن شوید ویژگی در بخش «ویژگی‌ها» (نه فقط در پنل variationها) ثبت شده است. مرور کامل در ساخت محصول متغیر در ووکامرس آمده است.

دسته‌بندی‌های خالی و درخت دسته‌بندی

اگر دسته‌بندی‌های محصولات خالی باشند یا محصولات در دسته‌های فرزند (child categories) قرار گرفته باشند، فیلتر دسته‌بندی ممکن است نتایج نادرست بدهد. مثلاً اگر یک محصول در دسته «کفش مردانه» باشد که زیرمجموعه «کفش» است، وقتی فیلتر «کفش» را انتخاب می‌کنید، ووکامرس به‌طور پیش‌فرض محصول را در نتایج نمایش می‌دهد ولی برخی قالب‌ها یا افزونه‌ها این رفتار را تغییر می‌دهند. راه‌حل: تنظیمات فیلتر دسته‌بندی را بررسی کنید و اطمینان حاصل کنید که «نمایش محصولات زیردسته» فعال است.

موجودی و وضعیت محصول

فیلترهای ووکامرس به‌طور پیش‌فرض محصولات ناموجود را در نتایج فیلتر نشان نمی‌دهند. اگر محصول شما موجودی صفر دارد و فیلتر روی «موجود در انبار» تنظیم شده، محصول در نتایج ظاهر نمی‌شود. این رفتار در تنظیمات ووکامرس قابل تغییر است. راه‌حل: در «ووکامرس ← تنظیمات ← محصولات ← موجودی»، گزینه «خارج از موجودی» را روی مقدار مناسب تنظیم کنید. برای مرور کامل رفتار موجودی، مدیریت موجودی محصولات در ووکامرس را ببینید.

محصولات با قیمت متغیر و فیلتر قیمت

فیلتر قیمت ووکامرس، بازه قیمت را بر اساس محصولات موجود محاسبه می‌کند. اگر محصولات شما قیمت متغیر دارند (مثلاً از ۱۰۰ هزار تا ۵۰۰ هزار تومان)، فیلتر قیمت بازه را بر اساس کمترین و بیشترین قیمت variationها محاسبه می‌کند، نه بر اساس قیمت نمایشی. این رفتار می‌تواند باعث شود نتایج فیلتر قیمت با انتظار شما فرق داشته باشد. راه‌حل: در ویرایش محصول، قیمت نمایشی (Regular Price) را درست تنظیم کنید تا فیلتر قیمت بازه درست را نشان دهد. مرور کامل در همان مقاله ساخت محصول متغیر در ووکامرس آمده است.

در بافت فیلترها، «داده» به‌اندازه «کد» مهم است. حتی بهترین کد فیلتر هم نمی‌تواند روی داده‌ای که ساختار درستی ندارد، کار کند. اگر فیلتر ویژگی کار نمی‌کند، اول مطمئن شوید ویژگی به‌عنوان Global Attribute ثبت شده، بعد سراغ کد بروید.

لایه پنجم — کش، CDN و تعارض با افزونه‌ها

لایه پنجم جایی است که همه‌چیز از نظر فنی و داده‌ای درست است ولی کش یا افزونه‌ای دیگر، فیلتر را مختل می‌کند. این لایه، دشوارترین لایه برای تشخیص است چون رفتار سیستم در ظاهر سالم به‌نظر می‌رسد.

کش صفحه و نتیجه فیلتر

افزونه‌های کش صفحه، محتوای HTML صفحه را ذخیره می‌کنند. اگر فیلتر شما با AJAX کار می‌کند و کش صفحه فعال است، ممکن است کش نسخه فیلترشده صفحه را برای همه کاربران سرو کند — یا برعکس، نسخه کش‌شده بدون فیلتر را همیشه نمایش دهد. راه‌حل: صفحه فروشگاه و صفحات دسته‌بندی باید از کش صفحه استثنا شوند یا از مکانیزمهایی مثل fragment cache استفاده کنند. در افزونه‌های کش مثل WP Rocket و LiteSpeed، این تنظیمات در بخش «ووکامرس» وجود دارد. برای مرور رفتار افزونه‌های کش در بافت ووکامرس، بهترین افزونه‌های کش وردپرس را ببینید.

Transientهای ووکامرس

ووکامرس از transient برای caching خودکار برخی کوئری‌ها استفاده می‌کند. اگر transient نادرست یا منقضی شده باشد، فیلترها نتایج قدیمی برمی‌گردانند. راه‌حل: در «ووکامرس ← وضعیت ← ابزارها»، گزینه «پاک کردن transientهای ووکامرس» را اجرا کنید. این کار امن است و هیچ داده‌ای را حذف نمی‌کند؛ فقط کش داخلی ووکامرس را بازسازی می‌کند.

تعارض با افزونه‌های فیلتر دیگر

اگر دو افزونه فیلتر روی سایت نصب باشند (مثلاً یکی ووکامرس پیش‌فرض و یکی افزونه YITH)، این دو می‌توانند با هم تعارض داشته باشند. نشانه: هر افزونه جداگانه کار می‌کند ولی با هم نه. راه‌حل: یکی از افزونه‌ها را غیرفعال کنید و از یک فیلتر واحد استفاده کنید. اگر افزونه فیلتر ووکامرس پیش‌فرض کافی نیست، به‌جای نصب افزونه دوم، از افزونه فیلتر پیشرفته‌ای مثل YITH یا WooCommerce Product Filter استفاده کنید و فیلتر پیش‌فرض را غیرفعال کنید. فهرست گزینه‌ها در بهترین افزونه‌های کاربردی برای ووکامرس آمده است.

تعارض با افزونه‌های امنیتی

افزونه‌های امنیتی مثل Wordfence در حالت سختگیرانه ممکن است درخواست‌های AJAX فیلتر را به‌عنوان رفتار مشکوک تلقی کنند و مسدود کنند. نشانه: در تب Network مرورگر، درخواست AJAX فیلتر با کد ۴۰۳ برمی‌گردد. راه‌حل: در تنظیمات افزونه امنیتی، مسیر /wp-admin/admin-ajax.php را با پارامترهای ووکامرس استثنا کنید. برای مرور رفتار افزونه‌های امنیتی، بهترین افزونه‌های امنیتی وردپرس را ببینید.

کوئری‌های سنگین و محدودیت سرور

در فروشگاه‌های بزرگ، کوئری فیلتر می‌تواند سنگین شود و به‌دلیل محدودیت منابع سرور، نیمه‌کاره اجرا شود. نشانه: فیلتر ساده کار می‌کند ولی فیلترهای ترکیبی (مثلاً دسته + ویژگی + قیمت) با خطای 500 یا 502 مواجه می‌شوند. راه‌حل: کوئری‌های فیلتر را بهینه کنید، از indexهای دیتابیس استفاده کنید، یا هاست خود را ارتقا دهید. مسیر کامل در بهینه‌سازی دیتابیس ووکامرس چگونه انجام می‌شود و در بافت سرعت فروشگاه در افزایش سرعت فروشگاه ووکامرس آمده است.

چک‌لیست دیباگ گام‌به‌گام فیلترهای ووکامرس

این ترتیبی است که در پروژه‌های واقعی طی می‌کنم. اگر ترتیب را حفظ کنید، از ارزان‌ترین و سریع‌ترین راه به پیچیده‌ترین می‌رسید:

  1. بررسی وجود ویجت‌های فیلتر: در «نمایش ← ابزارک‌ها» بررسی کنید آیا ویجت‌های ووکامرس (فیلتر قیمت، فیلتر ویژگی) در فهرست ابزارک‌ها دیده می‌شوند یا نه. اگر نه، به لایه اول بروید.
  2. بررسی سایدبار فروشگاه: آیا سایدبار فروشگاه در قالب شما ثبت شده و ویجت‌ها در آن قرار گرفته‌اند؟ اگر سایدبار وجود ندارد، قالب شما پشتیبانی ووکامرس را اعلام نکرده — به لایه اول.
  3. بررسی کنسول مرورگر: روی فیلتر کلیک کنید و خطاهای JavaScript را در کنسول بررسی کنید. هر خطای قرمز، سرنخ اصلی لایه دوم است.
  4. بررسی تب Network: در Developer Tools، تب Network را باز کنید و روی فیلتر کلیک کنید. اگر درخواست AJAX با کد ۲۰۰ برگشت ولی نتیجه خالی، مسئله در پاسخ سرور است. اگر کد ۴۰۳ یا ۴۰۴ دیدید، مسئله در مسیر یا احراز است.
  5. ذخیره مجدد پیوندهای یکتا: به «تنظیمات ← پیوندهای یکتا» بروید، بدون تغییر، ذخیره کنید. سپس در «ووکامرس ← وضعیت ← ابزارها»، «بازسازی پیوندهای یکتا» را اجرا کنید.
  6. بررسی ساختار ویژگی‌ها: در «محصولات ← ویژگی‌ها»، اطمینان حاصل کنید که ویژگی‌های فیلترشده به‌عنوان Global Attribute ثبت شده‌اند، نه Custom Product Attribute.
  7. پاک کردن کش‌ها: کش افزونه کش، transientهای ووکامرس (از «ووکامرس ← وضعیت ← ابزارها»)، کش CDN و کش مرورگر را پاک کنید.
  8. غیرفعال کردن افزونه‌های فیلتر دیگر: اگر چند افزونه فیلتر دارید، همه را به‌جز یک افزونه غیرفعال کنید و تست بگیرید.
  9. تست با قالب پیش‌فرض: قالب Twenty Twenty-Five را موقتاً فعال کنید (با ووکامرس تست بگیرید). اگر فیلتر کار کرد، مسئله در قالب است.
  10. غیرفعال کردن افزونه‌های دیگر: همه افزونه‌ها را غیرفعال کنید، فقط ووکامرس را فعال کنید، و تست بگیرید. سپس یکی‌یکی فعال کنید تا مقصر پیدا شود. الگوی کامل در چگونه افزونه مشکل‌ساز وردپرس را پیدا کنیم آمده است.
  11. فعال‌سازی WP_DEBUG: در wp-config.php مقادیر WP_DEBUG، WP_DEBUG_LOG و WP_DEBUG_DISPLAY را تنظیم کنید و لاگ را در wp-content/debug.log بررسی کنید.
  12. تست روی محیط استجینگ: اگر روی محیط محلی کار می‌کند ولی روی سرور نه، تفاوت‌های محیطی را بررسی کنید. ساخت محیط استجینگ در توسعه وردپرس با محیط لوکال توصیه می‌شود.

این ترتیب در تست و دیباگ پروژه‌های توسعه وردپرس به‌عنوان پروتکل عیب‌یابی معرفی شده است. در بیشتر موارد، مسئله در گام دوم یا ششم تشخیص داده می‌شود، پس قبل از رفتن به سراغ کش و قالب، همان دو گام اول را جدی بگیرید. اگر با خطاهای عمومی ووکامرس روبرو شدید، رفع خطاهای رایج ووکامرس و در بافت قالب، خطای قالب در ووکامرس و راه حل آن را ببینید.

پرسش‌های پرتکرار درباره خطای فیلترهای ووکامرس

این بخش به پرسش‌هایی اختصاص دارد که در انجمن‌ها و تیکت‌های پشتیبانی بیشترین تکرار را دارند و در نتایج جستجو به‌عنوان پاسخ کوتاه ارزشمندند.

چرا ویجت‌های فیلتر ووکامرس در پیشخوان نمایش داده نمی‌شوند؟

چهار علت رایج. اول، نسخه ووکامرس شما قدیمی است و با نسخه فعلی وردپرس سازگاری ندارد — ابتدا ووکامرس را به‌روز کنید. دوم، افزونه‌ای مدیریت ویجت‌ها را محدود کرده — افزونه‌های اخیر را غیرفعال و تست کنید. سوم، قالب شما سایدبار ووکامرس را ثبت نکرده و ویجت‌ها هیچ‌جا قابل قرار گرفتن نیستند. چهارم، در ویرایشگر بلوکی گوتنبرگ، ویجت‌های کلاسیک ووکامرس به‌عنوان بلوک «Legacy Widget» نمایش داده می‌شوند و اگر مرورگر شما مشکل جاوااسکریپت داشته باشد، نمایش داده نمی‌شوند. برای بررسی دقیق، ابتدا ووکامرس را به‌روز کنید، سپس در یک مرورگر دیگر تست کنید.

چرا فیلتر روی محصولات اعمال می‌شود ولی لیست تغییر نمی‌کند؟

سه علت رایج. اول، نتیجه فیلتر در HTML صفحه رندر می‌شود ولی با CSS مخفی شده — در Developer Tools، Inspect Element کنید و ببینید محصولات جدید در DOM هستند یا نه. دوم، افزونه کش صفحه، نسخه قدیمی را سرو می‌کند — کش را پاک کنید. سوم، درخواست AJAX با کد ۴۰۳ یا ۴۰۴ برمی‌گردد — در تب Network مرورگر بررسی کنید. راه‌حل سریع: در پنجره ناشناس سایت را باز کنید و با فیلتر تست کنید؛ اگر در پنجره ناشناس کار کرد، مسئله کش مرورگر است.

چرا فیلتر ویژگی کار می‌کند ولی فیلتر قیمت نه؟

دو مکانیزم متفاوت در کار است. فیلتر ویژگی بر مبنای taxonomy و فیلتر قیمت بر مبنای متادیتا کار می‌کند. اگر فیلتر ویژگی کار می‌کند ولی قیمت نه، احتمالاً محصولات شما قیمت نمایشی (Regular Price) ندارند و فقط در variationها قیمت دارند. راه‌حل: در ویرایش محصول، قیمت Regular Price را تنظیم کنید. راه‌حل دیگر: از افزونه‌های فیلتر پیشرفته‌ای که از ساختار variationهای ووکامرس پشتیبانی می‌کنند استفاده کنید.

چرا فیلتر در فروشگاه کار می‌کند ولی در موبایل نه؟

سه علت اصلی. اول، قالب شما در مدیاکوئری موبایل، سایدبار فیلتر را مخفی می‌کند یا با display: none پنهان می‌کند. دوم، اسکریپت فیلتر در موبایل به‌دلیل خطای JavaScript یا تنظیمات خاص اجرا نمی‌شود. سوم، افزونه کش نسخه موبایل و دسکتاپ را متفاوت سرو می‌کند. راه تشخیص: با Developer Tools به حالت موبایل بروید و ببینید آیا ویجت فیلتر در HTML وجود دارد یا نه. اگر وجود دارد ولی دیده نمی‌شود، مسئله CSS است؛ اگر وجود ندارد، مسئله سرور یا JS است.

چرا پس از فعال‌سازی افزونه فیلتر جدید، فیلترهای قبلی از کار افتادند؟

این نشانه تعارض بین دو افزونه فیلتر است. برخی افزونه‌های فیلتر، فیلتر پیش‌فرض ووکامرس را غیرفعال می‌کنند و فیلتر خودشان را جایگزین می‌کنند. اگر دو افزونه این کار را بکنند، نتیجه یک فیلتر شکسته است. راه‌حل: یکی از افزونه‌ها را غیرفعال کنید و از یک فیلتر واحد استفاده کنید. اگر افزونه‌های فیلتر را برای کارهای مختلف (مثلاً فیلتر رنگ و فیلتر سایز) نصب کرده‌اید، بهتر است از یک افزونه جامع استفاده کنید که همه فیلترها را پوشش دهد.

چرا فیلتر AJAX پس از تغییر قالب از کار افتاد؟

سه علت اصلی. اول، قالب جدید سایدبار ووکامرس را نمایش نمی‌دهد یا اسکریپت‌های فیلتر را enqueue نمی‌کند. دوم، ساختار HTML قالب جدید با کد JavaScript فیلتر سازگار نیست (مثلاً کلاس‌های CSS متفاوت). سوم، قالب جدید خودش یک سیستم فیلتر اختصاصی دارد که با افزونه فیلتر شما تعارض می‌کند. راه‌حل: مطمئن شوید قالب جدید رسماً ووکامرس را پشتیبانی می‌کند و اسکریپت‌های فیلتر شما در آن قالب بارگذاری می‌شوند. برای انتخاب قالب مناسب، بهترین قالب‌های سازگار با ووکامرس را ببینید.

آیا مشکل فیلتر می‌تواند به لایسنس افزونه مربوط باشد؟

بله، در برخی افزونه‌های تجاری، اگر لایسنس منقضی یا فعال نباشد، برخی قابلیت‌ها (از جمله فیلترهای پیشرفته) غیرفعال می‌شوند یا با پیام خطا کار نمی‌کنند. راه‌حل: وضعیت لایسنس افزونه فیلتر خود را در پیشخوان بررسی کنید و در صورت نیاز، آن را تجدید کنید. همچنین برای اطمینان از امن بودن نسخه نصب‌شده، راهنمای دانلود افزونه مطمئن وردپرس را بررسی کنید.

چرا فیلتر دسته‌بندی محصولات زیردسته را نشان نمی‌دهد؟

این رفتار به‌طور پیش‌فرض در ووکامرس وجود دارد: فیلتر دسته‌بندی فقط محصولاتی را نمایش می‌دهد که مستقیماً در دسته انتخابی قرار دارند. اگر محصولات شما در زیردسته‌ها هستند، به‌طور پیش‌فرض نمایش داده نمی‌شوند. راه‌حل: در برخی قالب‌ها و افزونه‌ها، گزینه «نمایش محصولات زیردسته» وجود دارد. اگر افزونه فیلتر شما این گزینه را ندارد، می‌توانید از فیلترهای سفارشی استفاده کنید. مرور ساختار دسته‌بندی در ساخت طبقه‌بندی سفارشی در وردپرس کمک می‌کند.

آیا مشکل فیلتر می‌تواند به نسخه PHP مربوط باشد؟

بله. ووکامرس مدرن به PHP 7.4 یا بالاتر نیاز دارد. اگر سرور شما روی PHP 7.2 یا پایین‌تر اجرا می‌شود، ممکن است فیلترها به‌دلیل ناسازگاری با کد ووکامرس کار نکنند. همچنین در PHP 8.x، برخی افزونه‌های فیلتر قدیمی با تغییرات syntax سازگار نیستند و خطای فاتال می‌دهند. راه‌حل: نسخه PHP را به 8.0 یا بالاتر ارتقا دهید و افزونه‌های فیلتر خود را به آخرین نسخه به‌روز کنید. پیش از ارتقا، از سایت بکاپ بگیرید و روی محیط استجینگ تست کنید.

چرا فیلتر قیمت بازه‌اش را اشتباه نشان می‌دهد؟

فیلتر قیمت ووکامرس بازه را بر اساس کمترین و بیشترین قیمت محصولات موجود در دسته محاسبه می‌کند. اگر بازه نادرست است، سه علت ممکن دارد: اول، محصولات با قیمت‌های outlier (خیلی ارزان یا خیلی گران) بازه را کشیده‌اند. دوم، محصولات ناموجود بازه را تحت تأثیر قرار داده‌اند. سوم، در محصولات متغیر، بازه بر اساس variationها محاسبه می‌شود نه قیمت نمایشی. راه‌حل: تنظیمات فیلتر قیمت را در ویجت بررسی کنید و اگر لازم است، بازه دستی را محدود کنید. مسیر کامل در همان مقالات ووکامرس که پیش‌تر لینک شده‌اند آمده است.

آیا می‌توانم فیلترها را برای موبایل به‌صورت drawer طراحی کنم؟

بله و این الگو در فروشگاه‌های مدرن رایج است. سایدبار فیلتر در موبایل به‌صورت drawer (کشویی) باز می‌شود تا فضای صفحه را نگیرد. برای پیاده‌سازی این الگو، معمولاً قالب‌های سازگار با ووکامرس قابلیت drawer را به‌صورت پیش‌فرض دارند. اگر قالب شما ندارد، می‌توانید با قالب فرزند و CSS اختصاصی این کار را انجام دهید. اما توجه کنید که هر تغییر در ساختار قالب ممکن است با کد JavaScript فیلتر شما تعارض داشته باشد — پس پس از پیاده‌سازی، تست کامل انجام دهید.

معماری پایدار برای فیلترهای مطمئن

پس از حل مشکل، ارزش دارد معماری فروشگاه را طوری تنظیم کنید که این نوع خطا در آینده تکرار نشود. فهرستی از اصول که در پروژه‌های فروشگاهی خودم به‌طور منظم رعایت می‌کنم:

  1. استفاده از قالب سازگار با ووکامرس: قالب شما باید رسماً ووکامرس را پشتیبانی کند و سایدبار فروشگاه را به‌درستی نمایش دهد. فهرست گزینه‌های تأییدشده در بهترین قالب‌های سازگار با ووکامرس آمده است.
  2. ویژگی‌ها را به‌عنوان Global Attribute ثبت کنید: هر ویژگی که می‌خواهید فیلتر شود، باید به‌عنوان ویژگی جهانی ووکامرس ثبت شده باشد، نه به‌عنوان ویژگی سفارشی محصول.
  3. یک افزونه فیلتر، نه چند تا: از یک افزونه فیلتر جامع استفاده کنید و فیلتر پیش‌فرض ووکامرس را غیرفعال کنید تا تعارض ایجاد نشود.
  4. کش اختصاصی ووکامرس: اگر از افزونه کش استفاده می‌کنید، تنظیمات مخصوص ووکامرس را فعال کنید و صفحه فروشگاه را از کش تهاجمی مستثنا کنید. برای مرور دقیق، بهترین افزونه‌های کش وردپرس را ببینید.
  5. پیوندهای یکتا را دوره‌ای بازسازی کنید: پس از هر به‌روزرسانی ووکامرس یا تغییر ساختار، پیوندهای یکتا را در «تنظیمات ← پیوندهای یکتا» و «ووکامرس ← وضعیت ← ابزارها» بازسازی کنید.
  6. تست AJAX و JavaScript: فیلترهای خود را در مرورگرهای مختلف (Chrome، Firefox، Safari) و دستگاه‌های مختلف (دسکتاپ، موبایل) تست کنید.
  7. پایش خودکار فیلترها: یک اسکریپت ساده بنویسید که هر ساعت فیلترهای اصلی را تست کند و در صورت شکست، به شما هشدار دهد. این کار جلوی «ماه‌ها فروش صفر» را می‌گیرد.
  8. پشتیبان‌گیری منظم: اگر تغییری در فیلترها به مشکل خورد، بکاپ تازه بازگردانی سریع را ممکن می‌کند. اصول پشتیبان‌گیری در بکاپ‌گیری از فروشگاه ووکامرس آمده است.
  9. امنیت افزونه فیلتر: از منبع معتبر افزونه فیلتر نصب کنید و در صورت شک به امنیت، دانلود افزونه مطمئن وردپرس را بررسی کنید.
  10. رعایت استانداردهای کدنویسی: اگر فیلتر سفارشی می‌نویسید، اصول استاندارد را رعایت کنید. مرور اصول در استانداردهای کدنویسی وردپرس چیست و کاربرد عملی در استفاده از WordPress Coding Standards در پروژه‌ها آمده است.

یک نکته از تجربه شخصی در فروشگاه‌های بزرگ: فیلترها مستقیماً روی نرخ تبدیل اثر می‌گذارند. اگر مشتری نتواند محصولی را پیدا کند که دنبالش است، از فروشگاه خارج می‌شود. یک فیلتر شکسته یعنی یک فرصت فروش از دست رفته. به همین دلیل، تست منظم و پایش خودکار، مهم‌تر از واکنش سریع در زمان بحران است. رویکرد کلی مدیریت این موضوع در CRO برای فروشگاه‌های ووکامرس و در بافت فروش در چگونه فروش فروشگاه ووکامرس را افزایش دهیم آمده است.

سخن پایانی

خطای عدم کارکرد فیلترهای ووکامرس، در نگاه اول ممکن است یک مسئله پیچیده به‌نظر برسد، ولی در عمل همیشه در یکی از پنج لایه‌ای که در این مقاله بررسی کردیم ریشه دارد: ثبت و نمایش نادرست ویجت‌های فیلتر، خطا در اجرای فیلترهای AJAX و جاوااسکریپت، ساختار URL و پیوندهای یکتا، داده‌های نادرست ویژگی و دسته‌بندی محصول، و تعارض با کش یا افزونه‌های دیگر. ابزار اصلی عیب‌یابی در این بافت، ترکیب سه چیز است: کنسول مرورگر برای دیدن خطاهای JavaScript، تب Network برای بررسی درخواست‌های AJAX، و تست با قالب پیش‌فرض ووکامرس برای تفکیک مسئله قالب از مسئله افزونه. مسیر عیب‌یابی که در چک‌لیست ارائه کردم، همان ترتیبی است که در پروژه‌های واقعی مرا سریع به علت رسانده؛ نکته کلیدی این است که از ارزان‌ترین گام شروع کنید و به گران‌ترین برسید. در بلندمدت، انضباط در استفاده از قالب سازگار با ووکامرس، ثبت ویژگی‌ها به‌عنوان Global Attribute، استفاده از یک افزونه فیلتر جامع، و کش مخصوص ووکامرس، مهم‌تر از هر راه‌حل لحظه‌ای است — چون این انضباط است که اجازه نمی‌دهد مشتری نتواند محصول مورد نظرش را پیدا کند و از فروشگاه خارج شود.

اگر این خطا را در یک پروژه واقعی تجربه کرده‌اید و به علت غیرمنتظره‌ای برخوردید — مثلاً افزونه فیلتری که فقط روی هاست‌های اشتراکی با محدودیت SQL پیچیده کار نمی‌کرد، یا قالبی که فیلتر ووکامرس را با فیلتر اختصاصی خودش جایگزین می‌کرد، یا CDN که پارامترهای query را در کش نادیده می‌گرفت — خوشحال می‌شوم تجربه‌تان را در دیدگاه‌ها بنویسید. به‌ویژه اگر ترفند خلاقانه‌ای برای تشخیص سریع‌تر پیدا کرده‌اید، آن تجربه برای نفر بعدی که با همین خطا روبرو می‌شود، ارزشمندتر از هر مستند رسمی است. 🛍️