خطای عدم نمایش محصولات در ووکامرس

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

محصولات نمایش داده نمی‌شوند — تفکیک نشانه‌ها

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

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

در عیب‌یابی نمایش محصولات، اولین سؤال این نیست که «محصول منتشر شده؟» بلکه این است «در کدام نقطه از چرخه رندر، محصول شما ناپدید می‌شود؟» — در سطح کوئری، در سطح template، در سطح کش، یا در سطح سرور. هرکدام لایه متفاوتی دارند.

ووکامرس محصولات را چطور روی فروشگاه نمایش می‌دهد؟

ووکامرس برای نمایش محصولات، از ترکیب چند مکانیزم استفاده می‌کند که درک آن‌ها برای عیب‌یابی ضروری است. اول، ووکامرس یک post type سفارشی به نام product تعریف می‌کند که ساختار خودش را دارد. دوم، صفحه فروشگاه و صفحات دسته‌بندی، از query سفارشی WP_Query با پارامترهای ووکامرس استفاده می‌کنند. سوم، خروجی نهایی محصولات از طریق فایل‌های template در مسیر templates/ افزونه ووکامرس تولید می‌شود که قالب شما می‌تواند آن‌ها را override کند. چهارم، ووکامرس از سیستمی به نام transient برای caching استفاده می‌کند که اگر نادرست باشد، محصولات را ناپدید می‌کند. اگر با معماری کلی افزونه‌های وردپرس آشنا نیستید، توصیه می‌کنم پیش از ادامه افزونه وردپرس چیست را بخوانید تا لایه‌بندی را در ذهن داشته باشید.

هر بار که صفحه فروشگاه یا آرشیو دسته‌بندی بارگذاری می‌شود، این چرخه طی می‌شود: ووکامرس پارامترهای query را از URL می‌خواند (مرتب‌سازی، فیلترها، صفحه جاری)، سپس WP_Query را با post type product اجرا می‌کند، نتایج را فیلتر می‌کند (قابلیت مشاهده، موجودی، تاریخ انتشار)، و در نهایت با فایل‌های template خروجی HTML تولید می‌کند. اگر در یکی از این مراحل شکستی رخ دهد — مثلاً فیلتر قابلیت مشاهده محصولاتی را که باید نمایش داده شوند رد کند، یا transient نسخه قدیمی query را برگرداند — نتیجه یک صفحه خالی است. برای مطالعه اصول ساخت و پیکربندی فروشگاه در ووکامرس، آموزش نصب و راه‌اندازی ووکامرس در وردپرس و تنظیمات اولیه ووکامرس برای ساخت فروشگاه را ببینید — این دو مقاله پیش‌زمینه خوبی برای درک رفتار پیش‌فرض ووکامرس هستند.

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

لایه اول — وضعیت، قابلیت مشاهده و موجودی محصول

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

وضعیت انتشار (Post Status)

محصولات در ووکامرس مثل نوشته‌های وردپرس وضعیت انتشار دارند. وضعیت‌های اصلی: publish (منتشر شده)، draft (پیش‌نویس)، pending (در انتظار بازبینی)، private (خصوصی)، و trash (زباله‌دان). فقط محصولات با وضعیت publish در فروشگاه نمایش داده می‌شوند. اگر محصولی را با وضعیت پیش‌نویس ذخیره کرده باشید، در پیشخوان می‌بینید ولی در فروشگاه نه. برای بررسی سریع، در پیشخوان به «محصولات ← همه محصولات» بروید و ستون وضعیت را بررسی کنید. برای مرور کامل افزودن محصول و وضعیت‌های آن، چگونه محصول جدید در ووکامرس ایجاد کنیم را ببینید. همچنین اگر با انواع مختلف محصول کار می‌کنید، انواع محصولات در ووکامرس و تفاوت آن‌ها دید خوبی درباره رفتار هرکدام می‌دهد.

قابلیت مشاهده در فهرست (Catalog Visibility)

هر محصول ووکامرس یک تنظیم به نام قابلیت مشاهده دارد که چهار مقدار می‌گیرد: visible (نمایش در فروشگاه و جستجو)، catalog (فقط فروشگاه بدون نتایج جستجو)، search (فقط در نتایج جستجو)، و hidden (مخفی در همه‌جا). اگر محصولی را روی حالت hidden ذخیره کنید، در فروشگاه نمایش داده نمی‌شود ولی لینک مستقیم آن همچنان کار می‌کند. این تنظیم در ویرایش محصول، زیر بخش «انتشار» قرار دارد. اشتباه رایج: زمانی که محصولی را از فروشگاه پنهان می‌کنید ولی دوباره آن را visible نمی‌کنید. راه‌حل: در ویرایش محصول، بخش «انتشار » را باز کنید و مقدار Catalog visibility را بررسی کنید. این تنظیم در بسیاری از مواردی که «محصول مشخصی ناپدید شده» مقصر است. همچنین برای حالت‌های مشابه در ووکامرس، مرور سفارشی‌سازی صفحه محصول در ووکامرس دید خوبی می‌دهد.

وضعیت موجودی (Stock Status)

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

تاریخ انتشار آینده و محصولات زمان‌بندی‌شده

اگر محصولی را با تاریخ انتشار آینده ذخیره کرده باشید، در فروشگاه نمایش داده نمی‌شود تا آن تاریخ برسد. این رفتار مثل نوشته‌های زمان‌بندی‌شده وردپرس است. راه‌حل: در ویرایش محصول، بخش «انتشار» را باز کنید و اگر تاریخ آینده است، آن را به «فوراً» تغییر دهید. این حالت در پروژه‌هایی که از ابزارهای خودکار برای افزودن محصول استفاده می‌کنند شایع‌تر است.

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

لایه دوم — صفحه فروشگاه، دسته‌بندی و پیوندهای یکتا

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

پیکربندی صفحه فروشگاه در تنظیمات ووکامرس

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

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

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

دسته‌بندی‌های خالی و محصولات بدون دسته

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

فیلترهای پنهان از افزونه‌های دیگر

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

لایه سوم — کش، CDN و کوئری‌های سنگین

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

کش صفحه و transient ووکامرس

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

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

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

CDN و نسخه قدیمی HTML

اگر از CDN استفاده می‌کنید، ممکن است نسخه قدیمی صفحه فروشگاه در لبه شبکه ذخیره شده باشد. این مسئله در فروشگاه‌هایی که محصولات را زیاد تغییر می‌دهند شایع است. راه‌حل: کش CDN را پاک کنید و در تنظیمات آن، مسیر /shop/ و /product/ را از کش مستثنا کنید یا زمان TTL آن‌ها را کوتاه کنید. برای مطالعه دقیق نقش CDN در سرعت و رفتار آن، CDN چگونه سرعت سایت را بهبود می‌دهد را ببینید.

افزونه‌های بهینه‌ساز و حذف CSS/JS محصولات

گاهی افزونه‌های بهینه‌ساز مثل Autoptimize یا WP Rocket به‌دلیل تنظیمات نادرست، CSS یا JS مربوط به نمایش محصولات را حذف می‌کنند. نتیجه: محصولات در HTML هستند ولی بی‌استایل یا نامرئی به‌نظر می‌رسند. این حالت با «عدم نمایش» اشتباه گرفته می‌شود ولی در واقع مسئله استایل است. راه‌حل: در تنظیمات افزونه بهینه‌ساز، فایل‌های ووکامرس را از فرآیند minify یا combine استثنا کنید. این مسئله در بافت بزرگ‌تر در افزایش سرعت فروشگاه ووکامرس بحث شده است.

لایه چهارم — تعارض قالب و فایل‌های template override

لایه چهارم جایی است که ووکامرس محصولات را درست تولید می‌کند ولی قالب شما آن‌ها را نمایش نمی‌دهد. این لایه به فایل‌های template و overrideهای قالب مربوط می‌شود.

فایل‌های template قدیمی در قالب

ووکامرس فایل‌های template خود را در مسیر plugins/woocommerce/templates/ نگه می‌دارد. قالب شما می‌تواند با کپی این فایل‌ها در پوشه yourtheme/woocommerce/ آن‌ها را override کند. مشکل زمانی رخ می‌دهد که نسخه جدید ووکامرس ساختار فایل را تغییر دهد ولی قالب شما هنوز نسخه قدیمی را override کرده باشد. نتیجه: خطای PHP در رندر صفحه فروشگاه و در نتیجه صفحه خالی. نشانه: در بالای صفحه فروشگاه پیامی مثل Your theme (Your Theme) contains outdated copies of some WooCommerce template files می‌بینید. راه‌حل: یا فایل‌های override قالب را حذف کنید و از نسخه پیش‌فرض ووکامرس استفاده کنید، یا آن‌ها را با نسخه جدید به‌روز کنید. برای مرور کامل این مسئله و پروتکل به‌روزرسانی، رفع خطاهای رایج ووکامرس را ببینید. همچنین اگر با خطاهای template و قالب در بافت ووکامرس دست‌وپنجه نرم می‌کنید، خطای قالب در ووکامرس و راه حل آن به‌طور اختصاصی این موضوع را بررسی کرده است.

تعارض قالب با ووکامرس

گاهی قالب شما به‌دلیل طراحی خاص، بخش محصولات ووکامرس را به‌طور کامل مخفی می‌کند. مثلاً قالب‌هایی که صفحه فروشگاه اختصاصی دارند و از شورت‌کد [products] ووکامرس پشتیبانی نمی‌کنند. نشانه: در View Source، HTML محصولات وجود دارد ولی با CSS مخفی شده. راه‌حل: قالب را به یک قالب سازگار با ووکامرس تغییر دهید. برای انتخاب قالب مناسب، بهترین قالب‌های سازگار با ووکامرس و در بافت وسیع‌تر قالب‌های وردپرس مناسب ووکامرس چه ویژگی‌هایی دارند را ببینید.

افزونه‌های قالب که query ووکامرس را تغییر می‌دهند

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

گوتنبرگ و بلوک‌های Query Loop

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

لایه پنجم — خطاهای خاموش دیتابیس و محدودیت منابع

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

خطاهای دیتابیس در کوئری محصولات

اگر جدول‌های ووکامرس یا جدول‌های پست‌های وردپرس آسیب دیده باشند یا کوئری محصولات به‌دلیل خطای SQL شکست بخورد، ووکامرس بی‌سروصدا نتیجه خالی برمی‌گرداند. برای تشخیص، افزونه WP_DEBUG را فعال کنید و لاگ wp-content/debug.log را بررسی کنید. اگر خطای MySQL server has gone away یا Table ... is marked as crashed می‌بینید، باید جدول‌های دیتابیس را تعمیر کنید. برای مرور این نوع خطاها، چگونه خطای اتصال به دیتابیس را حل کنیم و خطاهای رایج MySQL را ببینید.

محدودیت منابع هاست و کوئری‌های زمان‌بر

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

افزونه‌های مشکل‌ساز و خطاهای بی‌صدا

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

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

چک‌لیست دیباگ گام‌به‌گام خطای نمایش محصولات

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

1. بررسی وضعیت و قابلیت مشاهده محصول: در «محصولات ← همه محصولات»، ستون‌های وضعیت، قابلیت مشاهده و موجودی را بررسی کنید. محصولی با وضعیت draft یا hidden در فروشگاه نمایش داده نمی‌شود.
2. بررسی صفحه فروشگاه در تنظیمات ووکامرس: به «ووکامرس ← تنظیمات ← پیشرفته» بروید و مطمئن شوید صفحه فروشگاه به یک صفحه معتبر با شورت‌کد [products] اشاره می‌کند.
3. ذخیره مجدد پیوندهای یکتا: به «تنظیمات ← پیوندهای یکتا» بروید و بدون تغییر، ذخیره کنید. سپس در ووکامرس، ابزار «بازسازی پیوندهای یکتا» را اجرا کنید.
4. پاک کردن کش‌ها: کش افزونه کش، transientهای ووکامرس، کش CDN و کش مرورگر را پاک کنید. برای transientها از «ووکامرس ← وضعیت ← ابزارها» استفاده کنید.
5. فعال‌سازی WP_DEBUG: در wp-config.php مقادیر WP_DEBUG، WP_DEBUG_LOG و WP_DEBUG_DISPLAY را تنظیم کنید و لاگ wp-content/debug.log را بررسی کنید.
6. تست با قالب پیش‌فرض: قالب Twenty Twenty-Five را موقتاً فعال کنید. اگر محصولات نمایش داده شدند، مسئله در قالب است. برای بررسی سازگاری قالب با ووکامرس، بهترین قالب‌های سازگار با ووکامرس را ببینید.
7. غیرفعال کردن افزونه‌های دیگر: همه افزونه‌ها را غیرفعال کنید، فقط ووکامرس را فعال کنید و تست بگیرید. سپس یکی‌یکی افزونه‌ها را فعال کنید تا مقصر پیدا شود.
8. بررسی template override: پوشه yourtheme/woocommerce/ را بررسی کنید و اگر فایل‌های قدیمی دارد، آن‌ها را حذف یا به‌روز کنید.
9. بررسی log و error دیتابیس: اگر خطای MySQL در debug.log دیدید، جداول را با REPAIR TABLE یا از پیشخوان هاست تعمیر کنید.
10. تست روی محیط استجینگ: اگر روی محیط محلی کار می‌کند ولی روی سرور نه، تفاوت‌های محیطی (نسخه PHP، محدودیت‌های سرور، افزونه‌های نصب‌شده) را مقایسه کنید. ساخت محیط استجینگ در توسعه وردپرس با محیط لوکال توصیه می‌شود.

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

پرسش‌های پرتکرار درباره عدم نمایش محصولات ووکامرس

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

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

چهار علت شایع. اول، وضعیت محصول پیش‌نویس یا در انتظار بازبینی است — باید منتشر شود. دوم، قابلیت مشاهده محصول روی hidden تنظیم شده — باید visible شود. سوم، صفحه فروشگاه در تنظیمات ووکامرس نادرست تنظیم شده یا شورت‌کد [products] در آن نیست. چهارم، کش نسخه قدیمی یا خالی صفحه را سرو می‌کند — باید کش و transientها پاک شوند. برای بررسی سریع، ابتدا وضعیت محصول را در پیشخوان چک کنید و سپس کش را پاک کنید.

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

این نشانه معمولاً به پیکربندی صفحه فروشگاه برمی‌گردد. ممکن است صفحه فروشگاه در تنظیمات ووکامرس به صفحه‌ای اشاره کند که شورت‌کد [products] در آن نیست، یا محصولات بدون دسته‌بندی در صفحه فروشگاه حالت «دسته‌بندی» نمایش داده نمی‌شوند. راه‌حل: صفحه فروشگاه را بررسی کنید و محصولات را به یک دسته اضافه کنید یا صفحه فروشگاه را روی حالت «همه محصولات» تنظیم کنید.

چرا بعد از افزودن محصول جدید، محصولات قدیمی ناپدید می‌شوند؟

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

چرا محصول من با اینکه منتشر شده، در فروشگاه نیست؟

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

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

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

آیا افزونه‌های کش می‌توانند محصولات را از فروشگاه حذف کنند؟

بله، به‌طور غیرمستقیم. افزونه‌های کش که صفحه فروشگاه را کش می‌کنند، اگر با ووکامرس و transientهای آن هماهنگ نباشند، ممکن است نسخه خالی یا قدیمی صفحه را سرو کنند. راه‌حل: در تنظیمات افزونه کش، مسیر /shop/، /product/ و /product-category/ را از کش مستثنا کنید یا زمان TTL آن‌ها را کوتاه کنید. رفتار دقیق افزونه‌های کش در این زمینه در بهترین افزونه‌های کش وردپرس توضیح داده شده است.

چرا محصولات متغیر در فروشگاه نمایش داده نمی‌شوند؟

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

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

بله. ووکامرس مدرن به نسخه PHP 7.4 یا بالاتر نیاز دارد. اگر سرور شما روی PHP 7.2 یا پایین‌تر اجرا می‌شود، ممکن است ووکامرس به‌درستی کار نکند و محصولات نمایش داده نشوند. راه‌حل: نسخه PHP سرور را به 8.0 یا بالاتر ارتقا دهید. توجه کنید که ارتقای نسخه PHP می‌تواند روی سایر افزونه‌ها و قالب‌ها اثر بگذارد، پس ابتدا روی محیط استجینگ تست کنید. پیش از ارتقا، از سایت بکاپ بگیرید.

آیا مسدود شدن ajax-admin.php در ووکامرس محصولات را مخفی می‌کند؟

بله. ووکامرس برای بارگذاری برخی بخش‌های صفحه از admin-ajax.php استفاده می‌کند. اگر این مسیر توسط افزونه امنیتی یا فایل .htaccess مسدود شده باشد، محصولات ممکن است در برخی حالت‌ها (مثل فیلتر AJAX یا صفحه‌بندی) نمایش داده نشوند. راه‌حل: بررسی کنید که مسیر /wp-admin/admin-ajax.php از سمت front-end قابل دسترسی باشد. در مرورگر، در تب Network بررسی کنید که درخواست‌های AJAX با کد 200 پاسخ می‌گیرند یا نه.

چرا محصولات در صفحه فروشگاه با ترتیب اشتباه یا فقط بخشی نمایش داده می‌شوند؟

این رفتار معمولاً به دو علت برمی‌گردد: اول، ترتیب مرتب‌سازی در تنظیمات ووکامرس نادرست تنظیم شده؛ دوم، فیلترهای سفارشی قالب یا افزونه‌های دیگر روی query ووکامرس اعمال می‌شوند. راه‌حل: در «ووکامرس ← تنظیمات ← محصولات»، ترتیب مرتب‌سازی پیش‌فرض را بررسی کنید. اگر مسئله از فیلترهای قالب است، فایل‌های قالب را بررسی کنید یا به قالب پیش‌فرض تغییر دهید.

معماری پایدار برای نمایش مطمئن محصولات

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

1. بازبینی دوره‌ای وضعیت محصولات: هر ماه، فهرست محصولات را با فیلتر وضعیت بررسی کنید و مطمئن شوید هیچ محصولی به‌اشتباه در وضعیت پیش‌نویس یا مخفی نمانده است.
2. پیکربندی درست صفحه فروشگاه: صفحه فروشگاه باید شورت‌کد [products] داشته باشد، در منوی سایت قرار گیرد، و در تنظیمات ووکامرس به‌درستی ثبت شده باشد.
3. مدیریت پیوندهای یکتا: پس از هر به‌روزرسانی ووکامرس، پیوندهای یکتا را بازسازی کنید. اگر با تغییر ساختار URL کار می‌کنید، ابتدا روی محیط استجینگ تست کنید.
4. استثنا کردن فروشگاه از کش تهاجمی: مسیر /shop/ و /product-category/ را از کش تهاجمی صفحه مستثنا کنید یا از کش اختصاصی ووکامرس استفاده کنید. برای مرور دقیق، بهترین افزونه‌های کش وردپرس را ببینید.
5. به‌روزرسانی فایل‌های template override: در قالب فرزند، فایل‌های override ووکامرس را دوره‌ای بازبینی کنید و در صورت نیاز با نسخه جدید به‌روز کنید.
6. پایش خودکار نمایش محصولات: یک اسکریپت ساده بنویسید که هر ساعت صفحه فروشگاه را بررسی کند و در صورت خالی بودن، به شما هشدار دهد. این کار جلوی «ماه‌ها فروش صفر» را می‌گیرد.
7. پشتیبان‌گیری منظم از دیتابیس: اگر خطاهای دیتابیس رخ دهد، بکاپ تازه می‌تواند بازگردانی سریع را ممکن کند. اصول پشتیبان‌گیری در بافت فروشگاه در بکاپ‌گیری از فروشگاه ووکامرس آمده است.
8. تست روی محیط استجینگ: پیش از هر به‌روزرسانی ووکامرس یا قالب، روی محیط استجینگ با داده‌های واقعی تست کنید. مراحل ساخت و استفاده از استجینگ در تست و دیباگ پروژه‌های توسعه وردپرس آمده است.
9. استفاده از قالب سازگار با ووکامرس: قالب شما باید رسماً با ووکامرس سازگار باشد. فهرست گزینه‌های تأییدشده در بهترین قالب‌های سازگار با ووکامرس آمده است.
10. رعایت استانداردهای کدنویسی: اگر کد سفارشی روی query ووکامرس می‌نویسید، اصول استاندارد را رعایت کنید. مرور اصول در استانداردهای کدنویسی وردپرس چیست و در بافت ووکامرس، سئو فروشگاه ووکامرس دید کلی می‌دهد.

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

سخن پایانی

خطای عدم نمایش محصولات در ووکامرس، در نگاه اول ممکن است یکی از دلهره‌آورترین انواع خطا باشد چون مستقیم به فروش و اعتبار برند آسیب می‌زند — ولی در عمل همیشه در یکی از پنج لایه‌ای که در این مقاله بررسی کردیم ریشه دارد: تنظیمات وضعیت و قابلیت مشاهده محصول، پیکربندی صفحه فروشگاه و پیوندهای یکتا، کش و CDN، تعارض قالب و template override، و خطاهای خاموش دیتابیس یا محدودیت منابع. ابزار اصلی عیب‌یابی در این بافت، ترکیب سه چیز است: بررسی وضعیت محصول در پیشخوان، تست با قالب پیش‌فرض، و پاک کردن کش‌ها (افزونه، transient ووکامرس، و CDN). مسیر عیب‌یابی که در چک‌لیست ارائه کردم، همان ترتیبی است که در پروژه‌های واقعی مرا سریع به علت رسانده؛ نکته کلیدی این است که از ارزان‌ترین گام شروع کنید و به گران‌ترین برسید. در بلندمدت، انضباط در بازبینی دوره‌ای محصولات، مدیریت درست کش، استفاده از قالب سازگار با ووکامرس، و پایش خودکار صفحه فروشگاه، مهم‌تر از هر راه‌حل لحظه‌ای است — چون این انضباط است که اجازه نمی‌دهد صفحه‌ای که باید فروشگاه شما باشد، خالی بماند.

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