مشتری روی دکمه «افزودن به سبد خرید» کلیک می‌کند، پیام موفقیت ظاهر می‌شود، روی آیکون سبد خرید می‌زند — و صفحه‌ای خالی یا پیام «سبد خرید شما خالی است» می‌بیند. یا حتی سبد خرید در سایت اصلاً وجود ندارد و مشتری نمی‌داند چطور به سبد خرید دسترسی داشته باشد. اگر با خطای عدم نمایش سبد خرید در ووکامرس روبرو هستید، این مقاله همان مسیری را طی می‌کند که در سال‌ها کار روی صدها فروشگاه اینترنتی ووکامرس بارها پیموده‌ام. این خطا از نظر تجاری یکی از گران‌ترین انواع خطا در فروشگاه‌های اینترنتی است چون مستقیماً جلوی فرآیند خرید را می‌گیرد. در عمل همیشه در یکی از پنج لایه مشخص ریشه دارد: پیکربندی نادرست صفحات سیستمی، کش و مدیریت نشست (session)، خطا در fragment AJAX و اسکریپت‌های ووکامرس، تعارض قالب و فایل‌های template override، و محدودیت‌های REST API و کوکی. اگر این پنج لایه را به ترتیب بررسی کنید، تقریباً همیشه به علت دقیق می‌رسید بدون آنکه ساعت‌ها وقت خود را صرف آزمون‌وخطا کنید.

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

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

نشانه دوم: آیکون سبد خرید در هدر وجود ندارد یا تعداد محصول در آن به‌روز نمی‌شود. این حالت به لایه سوم (fragment AJAX) یا به قالب مربوط می‌شود. نشانه سوم: مشتری محصول را اضافه می‌کند، روی سبد خرید می‌رود، محصول را می‌بیند، ولی وقتی روی «تسویه‌حساب» می‌زند، سبد خالی می‌شود. این نشانه به لایه دوم (نشست و کوکی) یا به لایه پنجم (REST API و محدودیت سرور) برمی‌گردد. نشانه چهارم: سبد خرید فقط در مرورگرهای خاصی خالی است — مثلاً در Chrome درست کار می‌کند ولی در Safari یا Firefox نه. این حالت تقریباً همیشه به کوکی‌ها یا SameSite مربوط می‌شود. نشانه پنجم: سبد خرید در حالت مهمان خالی است ولی برای کاربران واردشده درست کار می‌کند. این نشانه به کوکی‌های نشست مهمان یا به کش مربوط می‌شود. نشانه ششم: در پیش‌نمایش پیشخوان سبد خرید درست کار می‌کند ولی روی سایت زنده نه. این حالت دقیقاً نشانه کش یا محدودیت سرور است.

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

سیستم سبد خرید در ووکامرس چطور کار می‌کند؟

سیستم سبد خرید ووکامرس از چهار بخش مستقل تشکیل شده که باید با هم هماهنگ باشند. بخش اول: ذخیره‌سازی سبد که در دیتابیس ووکامرس انجام می‌شود و هر سبد با یک cart_hash یکتا در جدول wp_woocommerce_sessions ثبت می‌شود. بخش دوم: مدیریت نشست (session) که با کوکی ووکامرس کار می‌کند و ارتباط بین مرورگر مشتری و داده سبد در دیتابیس را برقرار می‌کند. بخش سوم: fragment AJAX که تعداد و خلاصه سبد را بدون رفرش صفحه در هدر به‌روز می‌کند. بخش چهارم: صفحات نمایش سبد — صفحه سبد خرید، صفحه تسویه‌حساب، و مینی‌کارت. اگر هر یک از این چهار بخش از کار بیفتد، مشتری نمی‌تواند محصول را ببیند یا خرید را کامل کند. برای مرور معماری کلی ووکامرس، تنظیمات اولیه ووکامرس برای ساخت فروشگاه پیش‌زمینه خوبی می‌دهد.

نکته حساس که در پروژه‌های واقعی بارها دیده‌ام: ووکامرس برای ذخیره سبد مهمان، به کوکی wp_woocommerce_session_* وابسته است. اگر این کوکی توسط افزونه‌های امنیتی، CSP یا تنظیمات SameSite مرورگر مسدود شود، سبد هر بار خالی می‌شود. مسئله ظریف دیگر: ووکامرس مدرن از fragment AJAX برای به‌روزرسانی تعداد سبد در هدر استفاده می‌کند و این درخواست AJAX به مسیر wc-ajax=get_refreshed_fragments می‌رود. اگر این مسیر بلاک شود، سبد خرید در هدر خالی می‌ماند حتی اگر سبد در دیتابیس پر باشد. برای مرور معماری REST API ووکامرس، اتصال ووکامرس به سرویس‌های خارجی با API دید خوبی می‌دهد.

بخشمسئولیتنشانه خطا
ذخیره‌سازی سبدجدول wp_woocommerce_sessionsسبد در دیتابیس پر ولی در صفحه خالی
مدیریت نشستکوکی wp_woocommerce_sessionسبد در هر بازدید خالی می‌شود
Fragment AJAXمسیر wc-ajax=get_refreshed_fragmentsتعداد سبد در هدر به‌روز نمی‌شود
صفحات نمایشصفحه سبد، تسویه، مینی‌کارتصفحه سبد خالی از ابتدا

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

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

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

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

ووکامرس برای نمایش سبد، به یک صفحه معتبر نیاز دارد که در آن شورت‌کد [woocommerce_cart] یا بلوک Cart قرار گرفته باشد. اگر این صفحه حذف شده باشد یا شورت‌کد در آن نباشد، سبد نمایش داده نمی‌شود. راه‌حل: به «ووکامرس ← تنظیمات ← پیشرفته» بروید و در بخش «صفحات» بررسی کنید که صفحه سبد خرید به یک صفحه معتبر اشاره می‌کند. اگر صفحه حذف شده، روی گزینه «نصب صفحات» کلیک کنید تا ووکامرس صفحات سیستمی را بازسازی کند. سپس در ویرایش همان صفحه، مطمئن شوید شورت‌کد [woocommerce_cart] در محتوا وجود دارد. برای مرور کامل تنظیمات، تنظیمات اولیه ووکامرس برای ساخت فروشگاه را ببینید.

فایل‌های template قالب و ووکامرس

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

Mini Cart و نمایش تعداد سبد در هدر

اگر سبد خرید در هدر یا به‌صورت mini cart نمایش داده نمی‌شود، ممکن است قالب شما از ویژگی «افزودن به سبد با AJAX» پشتیبانی نکند یا تنظیمات آن را غیرفعال کرده باشد. راه‌حل: در «ووکامرس ← تنظیمات ← محصولات»، گزینه «فعال‌سازی افزودن به سبد با AJAX در صفحات آرشیو» را فعال کنید. سپس در قالب فرزند، اطمینان حاصل کنید که فایل header.php و cart/mini-cart.php نسخه سفارشی یا ووکامرس را به‌درستی نمایش می‌دهند. اصول کار با قالب فرزند در قالب چایلد وردپرس چیست و چه زمانی به آن نیاز داریم توضیح داده شده است.

تعارض با صفحه‌سازها

اگر از صفحه‌ساز (Elementor، Divi یا WPBakery) برای طراحی صفحات فروشگاه استفاده می‌کنید، ممکن است صفحه سبد خرید با صفحه‌ساز بازنویسی شده و شورت‌کد ووکامرس در آن نباشد. نشانه: صفحه سبد خرید به‌جای نمایش سبد، بخش‌های طراحی‌شده صفحه‌ساز را نشان می‌دهد. راه‌حل: صفحه سبد خرید باید حتماً از شورت‌کد [woocommerce_cart] یا بلوک ووکامرس استفاده کند، نه از طراحی صفحه‌ساز. اگر با صفحه‌ساز طراحی کرده‌اید، در همان ویرایشگر، ویجت یا بلوک Cart ووکامرس را اضافه کنید. برای مرور سازگاری صفحه‌سازها با ووکامرس، بررسی سازگاری قالب با افزونه‌ها را ببینید.

در بافت سبد خرید، «صفحه‌ای که وجود دارد» همیشه «صفحه‌ای که کار می‌کند» نیست. حتی اگر صفحه سبد خرید در منو باشد و لینک آن کار کند، اگر شورت‌کد یا بلوک ووکامرس در محتوایش نباشد، سبد نمایش داده نمی‌شود.

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

لایه دوم جایی است که صفحه سبد خرید درست پیکربندی شده ولی سبد همیشه خالی است. این حالت تقریباً همیشه به مدیریت نشست و کوکی‌ها برمی‌گردد که خودشان تحت تأثیر کش، افزونه‌های امنیتی، و تنظیمات SameSite مرورگر هستند.

کش صفحه و ذخیره‌سازی نشست

ووکامرس برای ذخیره سبد مهمان، از کوکی wp_woocommerce_session_* استفاده می‌کند. اگر افزونه کش صفحه، صفحات سبد خرید و تسویه‌حساب را کش کند، مشتری ممکن است نسخه کش‌شده بدون نشست را دریافت کند و سبدش خالی به نظر برسد. راه‌حل: صفحات سبد خرید، تسویه‌حساب، و حساب کاربری باید حتماً از کش صفحه مستثنا شوند. در افزونه‌های کش مثل WP Rocket و LiteSpeed، این تنظیمات در بخش «ووکامرس» به‌طور پیش‌فرض فعال است. برای مرور دقیق این تنظیمات، بهترین افزونه‌های کش وردپرس را ببینید.

کوکی SameSite و مرورگرهای مدرن

از سال ۲۰۲۰، مرورگرها به‌طور پیش‌فرض کوکی‌ها را با SameSite=Lax ذخیره می‌کنند که در بافت ووکامرس می‌تواند باعث شود کوکی نشست ارسال نشود و سبد خالی به نظر برسد. این مسئله در فروشگاه‌هایی که روی زیر‌دامنه یا با ریدایرکت HTTPS کار می‌کنند شایع‌تر است. راه‌حل: در فایل functions.php قالب فرزند، این فیلتر را اضافه کنید:

add_filter( 'wc_session_cookie_params', function( $params ) {
    $params['samesite'] = 'Lax';
    return $params;
} );

نکته مهم: اگر فروشگاه شما روی دامنه‌ای کار می‌کند که کاربران از ساب‌دامین‌های مختلف وارد می‌شوند، ممکن است لازم باشد مقدار را روی None و secure = true تنظیم کنید. اما این کار فقط روی HTTPS امکان‌پذیر است و اگر نادرست انجام شود، می‌تواند امنیت فروشگاه را پایین بیاورد.

افزونه‌های امنیتی و مسدودسازی کوکی‌ها

افزونه‌های امنیتی مثل Wordfence در حالت سختگیرانه ممکن است درخواست‌های AJAX ووکامرس (مثل wc-ajax=get_refreshed_fragments) یا کوکی‌های نشست را مسدود کنند. نشانه: در تب Network مرورگر، درخواست AJAX با کد ۴۰۳ یا ۴۰۱ برمی‌گردد. راه‌حل: در تنظیمات افزونه امنیتی، مسیر /wp-admin/admin-ajax.php?action=wc-ajax و مسیر /?wc-ajax= را استثنا کنید. برای مرور رفتار افزونه‌های امنیتی، بهترین افزونه‌های امنیتی وردپرس را ببینید.

مدت اعتبار نشست و رفتار کاربر

ووکامرس به‌طور پیش‌فرض نشست کاربران مهمان را برای ۴۸ ساعت نگه می‌دارد. اگر این مقدار به‌دلیل تنظیمات نادرست کاهش یابد، سبد مشتری ممکن است در همان سشن از دست برود. راه‌حل: در «ووکامرس ← تنظیمات ← محصولات»، گزینه «مدت اعتبار سبد خرید» را روی مقدار مناسب (معمولاً ۴۸ ساعت یا بالاتر) تنظیم کنید. همچنین در فایل php.ini سرور، مقدار session.gc_maxlifetime باید با این تنظیم هم‌خوانی داشته باشد. اگر این دو هم‌خوانی نداشته باشند، PHP می‌تواند نشست را پیش از موعد مقرر پاک کند و سبد خالی به نظر برسد.

لایه سوم — Fragment AJAX و اسکریپت‌های ووکامرس

لایه سوم جایی است که سبد در دیتابیس پر است و صفحه سبد به‌درستی رندر می‌شود، ولی تعداد سبد در هدر به‌روز نمی‌شود یا mini cart خالی است. این لایه به fragment AJAX و اسکریپت‌های ووکامرس مربوط می‌شود.

فراخوانی get_refreshed_fragments

ووکامرس از یک مکانیزم به نام fragment AJAX استفاده می‌کند که با فراخوانی wc-ajax=get_refreshed_fragments، تعداد و خلاصه سبد را از دیتابیس می‌خواند و بخش‌های مشخصی از صفحه را به‌روز می‌کند. اگر این درخواست شکست بخورد، سبد خرید در هدر به‌روز نمی‌شود. راه تشخیص: در تب Network مرورگر، فیلتر admin-ajax.php را اعمال کنید و روی دکمه «افزودن به سبد» کلیک کنید. ببینید آیا درخواست با کد ۲۰۰ برمی‌گردد و در پاسخش داده JSON دارد یا نه. اگر کد خطا داشت یا پاسخ خالی بود، مسئله در این لایه است. برای مرور دقیق رفتار AJAX ووکامرس، خطای عدم بارگذاری JS افزونه را ببینید.

بارگذاری نادرست wc-cart-fragments

ووکامرس برای fragment AJAX از اسکریپتی به نام wc-cart-fragments استفاده می‌کند که به jQuery وابسته است. اگر این اسکریپت به‌دلیل تنظیمات نادرست افزونه بهینه‌ساز بارگذاری نشود یا defer شود، fragment AJAX کار نمی‌کند. راه‌حل: در تنظیمات افزونه بهینه‌ساز (مثل Autoptimize یا WP Rocket)، اسکریپت wc-cart-fragments را از فرآیند minify، combine و defer استثنا کنید. این اسکریپت باید حتماً در head یا ابتدای footer بارگذاری شود.

defer و async روی اسکریپت‌های ووکامرس

افزونه‌های بهینه‌ساز به‌طور پیش‌فرض ممکن است روی اسکریپت‌های ووکامرس، defer یا async اعمال کنند. این می‌تواند ترتیب بارگذاری را به‌هم بزند و fragment AJAX را از کار بیندازد. راه‌حل: در تنظیمات افزونه بهینه‌ساز، فایل‌های cart-fragments.js، add-to-cart.js و cart.js ووکامرس را از هر نوع defer/async استثنا کنید. اگر افزونه بهینه‌ساز این امکان را ندارد، می‌توانید این فایل‌ها را به‌طور کامل از فرآیند بهینه‌سازی حذف کنید.

خطاهای JavaScript در کنسول

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

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

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

فایل‌های template override قدیمی

اگر قالب شما فایل‌های سبد خرید ووکامرس (مثل cart/cart.php، cart/mini-cart.php، cart/cart-empty.php) را override کرده و این فایل‌ها با نسخه جدید ووکامرس هم‌خوانی نداشته باشند، ممکن است سبد به‌درستی رندر نشود یا خطای PHP در هنگام نمایش رخ دهد. نشانه: در پیشخوان پیام Your theme contains outdated copies of some WooCommerce template files می‌بینید. راه‌حل: فایل‌های override را با نسخه جدید به‌روز کنید یا آن‌ها را حذف کنید. اگر با مشکل template و قالب در بافت ووکامرس دست‌وپنجه نرم می‌کنید، خطای قالب در ووکامرس و راه حل آن به‌طور اختصاصی این موضوع را بررسی کرده است.

تعارض با mini cart قالب

بسیاری از قالب‌های ووکامرس، mini cart اختصاصی خودشان را دارند که با fragment AJAX ووکامرس کار می‌کند. اگر قالب شما نسخه قدیمی این mini cart را override کرده باشد یا از کلاس‌های CSS متفاوتی استفاده کند، mini cart به‌روز نمی‌شود. نشانه: در HTML صفحه، mini cart وجود دارد ولی تعداد سبد در آن همیشه صفر یا نادرست است. راه‌حل: فایل mini-cart.php قالب فرزند را با نسخه ووکامرس مقایسه کنید و کلاس‌های CSS را با fragment AJAX ووکامرس هم‌راستا کنید.

صفحه‌سازها و ساختار HTML

صفحه‌سازها مثل Elementor Pro یا Divi Builder، برای طراحی صفحات فروشگاه، ساختار HTML متفاوتی تولید می‌کنند که ممکن است با fragment AJAX ووکامرس سازگار نباشد. نشانه: در صفحه سبد خرید، بخش‌های طراحی‌شده صفحه‌ساز ظاهر می‌شوند ولی سبد ووکامرس نمایش داده نمی‌شود. راه‌حل: صفحات سبد و تسویه‌حساب باید از بلوک یا شورت‌کد اصلی ووکامرس استفاده کنند، نه از طراحی صفحه‌ساز. اگر مجبور به استفاده از صفحه‌ساز هستید، از ویجت‌ها یا بلوک‌های رسمی ووکامرس که صفحه‌ساز ارائه می‌دهد استفاده کنید.

استایل‌های CSS قالب

گاهی سبد خرید در HTML وجود دارد ولی با CSS قالب مخفی شده است. نشانه: در Developer Tools، محصولات سبد در DOM هستند ولی با display: none پنهان شده‌اند. راه‌حل: در Inspect Element، ببینید چه کلاسی روی سبد اعمال شده و در قالب فرزند، CSS مناسب اضافه کنید. اگر مشکل در مدیاکوئری موبایل است، ممکن است سبد در موبایل پنهان شده باشد. مسئله CSS معمولاً به‌راحتی حل می‌شود ولی مهم است که با مسئله «سبد خالی» اشتباه گرفته نشود.

در بافت سبد خرید، «نبودن در DOM» و «مخفی بودن با CSS» دو دنیای متفاوت هستند. اولی مسئله سرور است، دومی مسئله استایل. Inspect Element اولین ابزاری است که این دو را از هم تفکیک می‌کند.

لایه پنجم — REST API، Block Cart و محدودیت‌های سرور

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

REST API و Store API ووکامرس

از ووکامرس ۶.۸ به بعد، بلوک‌های ووکامرس (از جمله بلوک Cart) از REST API استفاده می‌کنند نه از fragment AJAX سنتی. اگر سایت شما مسیر /wp-json/wc/store/v1/ را مسدود کرده باشد یا افزونه امنیتی این مسیر را بلاک کند، بلوک سبد کار نمی‌کند. نشانه: در کنسول مرورگر، خطای Failed to fetch یا 403 Forbidden برای درخواست‌های REST API. راه‌حل: مسیر /wp-json/wc/store/ را در تنظیمات افزونه امنیتی استثنا کنید و مطمئن شوید فایل .htaccess این مسیر را بلاک نمی‌کند. برای مرور معماری REST API ووکامرس، اتصال ووکامرس به سرویس‌های خارجی با API را ببینید.

PHP Session و محدودیت‌های سرور

ووکامرس از PHP Session به‌طور پیش‌فرض استفاده نمی‌کند، ولی برخی افزونه‌ها و قالب‌ها ممکن است این کار را انجام دهند. اگر PHP Session در سرور شما تنظیم نباشد یا مسیر ذخیره‌سازی آن قابل نوشتن نباشد، سبد خرید نمی‌تواند کار کند. نشانه: در لاگ PHP، خطای session_start(): Failed to read session data یا Unable to write session data. راه‌حل: با پشتیبانی هاست تماس بگیرید و از آن‌ها بخواهید مسیر ذخیره‌سازی Session را بررسی کنند. اصول مدیریت منابع سرور در کاهش مصرف منابع هاست آمده است.

محدودیت تعداد کوکی‌ها

مرورگرها محدودیتی روی تعداد و حجم کوکی‌ها دارند (معمولاً ۵۰ کوکی و ۴ کیلوبایت برای هر کوکی). اگر فروشگاه شما کوکی‌های زیادی داشته باشد (از افزونه‌های مختلف مثل آنالیتیکس، تبلیغات، امنیت و…)، ممکن است کوکی نشست ووکامرس ذخیره نشود و سبد خالی به نظر برسد. نشانه: در تب Application در Developer Tools، کوکی‌های فعلی سایت را بررسی کنید و ببینید آیا کوکی wp_woocommerce_session_* وجود دارد یا نه. اگر وجود ندارد ولی کوکی‌های دیگر پر است، مسئله از این لایه است. راه‌حل: تعداد کوکی‌های اضافی را کاهش دهید یا از ساب‌دامین اختصاصی برای فروشگاه استفاده کنید.

Block Cart و Block Checkout

از ووکامرس ۷.۰ به بعد، بلوک‌های Cart و Checkout به‌طور پیش‌فرض ارائه می‌شوند که بر پایه React و REST API کار می‌کنند. اگر سایت شما از این بلوک‌ها استفاده می‌کند ولی با قالب یا افزونه‌ای تعارض داشته باشد، سبد نمایش داده نمی‌شود. نشانه: در کنسول مرورگر، خطای React یا خطای بارگذاری chunk. راه‌حل: نسخه ووکامرس، وردپرس و قالب را هم‌راستا کنید. اگر با بلوک‌های ووکامرس مشکل دارید، می‌توانید به حالت شورت‌کد سنتی برگردید: در ویرایش صفحه سبد، بلوک Cart را حذف و شورت‌کد [woocommerce_cart] را جایگزین کنید.

محدودیت منابع سرور

در فروشگاه‌های بزرگ، فرآیند به‌روزرسانی fragment AJAX و کوئری‌های سبد خرید می‌تواند سنگین شود و به‌دلیل محدودیت منابع سرور نیمه‌کاره اجرا شود. نشانه: سبد در ساعات کم‌ترافیک کار می‌کند ولی در ساعات شلوغی خالی می‌شود. راه‌حل: کوئری‌های سبد خرید را بهینه کنید، از object cache (مثل Redis) استفاده کنید، یا هاست خود را ارتقا دهید. مسیر کامل در افزایش سرعت فروشگاه ووکامرس و در بافت دیتابیس در بهینه‌سازی دیتابیس ووکامرس چگونه انجام می‌شود آمده است.

چک‌لیست دیباگ گام‌به‌گام عدم نمایش سبد خرید

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

  1. بررسی صفحات سیستمی ووکامرس: در «ووکامرس ← تنظیمات ← پیشرفته»، بررسی کنید که صفحه سبد خرید به یک صفحه معتبر اشاره می‌کند و شورت‌کد [woocommerce_cart] در آن وجود دارد.
  2. تست در پنجره ناشناس: با پنجره Incognito یا مرورگر دیگر، محصولی به سبد اضافه کنید و ببینید سبد نمایش داده می‌شود یا نه. اگر در پنجره ناشناس کار کرد، مسئله کش مرورگر است.
  3. بررسی تب Application: در Developer Tools، تب Application را باز کنید و کوکی‌های سایت را ببینید. کوکی wp_woocommerce_session_* باید وجود داشته باشد. اگر وجود ندارد، مسئله در کوکی یا SameSite است.
  4. بررسی تب Network: فیلتر admin-ajax.php یا wc-ajax را اعمال کنید و روی دکمه «افزودن به سبد» کلیک کنید. ببینید آیا درخواست‌ها با کد ۲۰۰ پاسخ می‌گیرند و داده JSON دارند یا نه.
  5. بررسی کنسول مرورگر: خطاهای JavaScript را بررسی کنید. اگر خطای wc_cart_fragments_params is not defined یا مشابه دیدید، مسئله در بارگذاری نادرست اسکریپت‌هاست.
  6. پاک کردن کش‌ها: کش افزونه کش، transientهای ووکامرس (از «ووکامرس ← وضعیت ← ابزارها»)، کش CDN و کش مرورگر را پاک کنید.
  7. فعال‌سازی WP_DEBUG: در wp-config.php مقادیر WP_DEBUG، WP_DEBUG_LOG و WP_DEBUG_DISPLAY را تنظیم کنید و لاگ wp-content/debug.log را بررسی کنید.
  8. غیرفعال کردن افزونه‌های امنیتی و کش: افزونه‌های امنیتی و کش را موقتاً غیرفعال کنید و تست بگیرید. اگر سبد کار کرد، در تنظیمات همان افزونه، مسیر /wp-admin/admin-ajax.php?action=wc-ajax و /wp-json/wc/store/ را استثنا کنید.
  9. تست با قالب پیش‌فرض: قالب Twenty Twenty-Five را موقتاً فعال کنید (با ووکامرس تست بگیرید). اگر سبد کار کرد، مسئله در قالب است.
  10. بررسی template override: پوشه yourtheme/woocommerce/cart/ را بررسی کنید و اگر فایل‌های قدیمی دارد، آن‌ها را حذف یا به‌روز کنید.
  11. غیرفعال کردن افزونه‌های دیگر: همه افزونه‌ها را غیرفعال کنید، فقط ووکامرس را فعال کنید، و تست بگیرید. سپس یکی‌یکی فعال کنید تا مقصر پیدا شود. الگوی کامل در چگونه افزونه مشکل‌ساز وردپرس را پیدا کنیم آمده است.
  12. تست روی محیط استجینگ: اگر روی محیط محلی کار می‌کند ولی روی سرور نه، تفاوت‌های محیطی را بررسی کنید. ساخت محیط استجینگ در توسعه وردپرس با محیط لوکال توصیه می‌شود.

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

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

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

چرا سبد خرید ووکامرس همیشه خالی است؟

سه علت رایج. اول، افزونه کش صفحه سبد خرید را کش می‌کند و نسخه بدون نشست سرو می‌شود — صفحه سبد را از کش مستثنا کنید. دوم، کوکی wp_woocommerce_session_* ذخیره نمی‌شود، معمولاً به‌دلیل تنظیمات SameSite یا افزونه امنیتی — تنظیمات کوکی و امنیتی را بررسی کنید. سوم، مشکل در fragment AJAX است — در تب Network مرورگر درخواست wc-ajax=get_refreshed_fragments را بررسی کنید.

چرا سبد خرید فقط در حالت مهمان خالی است؟

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

چرا سبد خرید در مرورگر Chrome کار می‌کند ولی در Safari نه؟

این تفاوت معمولاً به سیاست SameSite یا ITP (Intelligent Tracking Prevention) در Safari برمی‌گردد. Safari در سال‌های اخیر کوکی‌های ثالث و کوکی‌های با عمر بلند را محدود کرده است. راه‌حل: کوکی نشست ووکامرس را روی SameSite=Lax و secure=true تنظیم کنید و در صورت امکان، مدت اعتبار آن را کوتاه کنید. اصول مدیریت کوکی و حریم خصوصی در بافت مرورگرهای مدرن در مقالات مربوط به امنیت وردپرس آمده است.

چرا سبد خرید در موبایل خالی است ولی در دسکتاپ نه؟

سه علت اصلی. اول، قالب شما در موبایل، ساختار mini cart را متفاوت می‌سازد و fragment AJAX نمی‌تواند آن را پیدا کند. دوم، افزونه کش، نسخه موبایل و دسکتاپ را متفاوت سرو می‌کند و نسخه موبایل خالی است. سوم، اسکریپت‌های ووکامرس در موبایل به‌دلیل تنظیمات بهینه‌ساز بارگذاری نمی‌شوند. راه تشخیص: در Chrome DevTools، حالت موبایل را فعال کنید و تب Network را بررسی کنید.

چرا پس از نصب افزونه کش، سبد خرید خالی شد؟

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

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

این تفاوت معمولاً به دو علت برمی‌گردد. اول، کش صفحه روی محیط زنده فعال است ولی روی محیط پیش‌نمایش نه. دوم، تفاوت در تنظیمات HTTPS، HTTPS+HSTS یا CSP بین محیط پیش‌نمایش و زنده. راه‌حل: با پاک کردن کش و تست در پنجره ناشناس شروع کنید. اگر مشکل ادامه داشت، تفاوت‌های تنظیمات HTTPS و هدرها را بررسی کنید.

چرا آیکون سبد خرید تعداد محصول را به‌روز نمی‌کند؟

این نشانه مشخص fragment AJAX است. ووکامرس از مسیر wc-ajax=get_refreshed_fragments برای به‌روزرسانی تعداد سبد استفاده می‌کند. اگر این مسیر بلاک شود یا اسکریپت wc-cart-fragments درست بارگذاری نشود، تعداد به‌روز نمی‌شود. راه‌حل: در تب Network مرورگر، این درخواست را بررسی کنید و در تنظیمات افزونه بهینه‌ساز، اسکریپت wc-cart-fragments را از defer/minify استثنا کنید.

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

در برخی موارد بله، ولی خودش چالش‌های جدیدی دارد. بلوک Cart از REST API ووکامرس استفاده می‌کند (مسیر /wp-json/wc/store/v1/) که باید در تنظیمات افزونه امنیتی استثنا شود. اگر می‌خواهید به بلوک Cart مهاجرت کنید، ابتدا روی محیط استجینگ تست کنید و مطمئن شوید همه افزونه‌های ووکامرس شما با آن سازگارند. اگر با خطای مهاجرت روبرو شدید، می‌توانید به شورت‌کد سنتی [woocommerce_cart] برگردید.

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

این نشانه به دو علت برمی‌گردد. اول، کوکی نشست در ریدایرکت بین صفحه سبد و تسویه‌حساب ارسال نمی‌شود (معمولاً به‌دلیل HTTPS یا SameSite). دوم، افزونه کش صفحه تسویه‌حساب را کش می‌کند. راه‌حل: صفحه تسویه‌حساب را از کش مستثنا کنید و در صورت لزوم، تنظیمات کوکی را به SameSite=Lax یا None (با HTTPS) تغییر دهید. همچنین اطمینان حاصل کنید که صفحات سبد، تسویه و حساب کاربری همه روی HTTPS یکسان کار می‌کنند.

آیا افزونه‌های نال می‌توانند باعث خالی شدن سبد شوند؟

بله و به‌طور مستقیم. افزونه‌های نال معمولاً کد اضافی در فایل‌های JS خود دارند که می‌تواند با fragment AJAX ووکامرس تعارض کند یا کوکی‌های نشست را مختل کند. اگر مطمئن نیستید افزونه‌های فروشگاه شما از منبع امن آمده یا نه، راهنمای دانلود افزونه مطمئن وردپرس را بررسی کنید. تجربه من از صدها پرونده پاکسازی، نشان می‌دهد نیمی از موارد عجیب، ریشه در یک افزونه یا قالب نال داشته است.

آیا استفاده از CDN می‌تواند باعث خالی شدن سبد شود؟

بله، اگر CDN به‌درستی با ووکامرس پیکربندی نشده باشد. CDN باید کوکی‌های ووکامرس را در کش خود نادیده بگیرد و صفحات سبد، تسویه‌حساب و حساب کاربری را از کش مستثنا کند. راه‌حل: در تنظیمات CDN خود، مسیرهای /cart/، /checkout/ و /my-account/ را از کش حذف کنید و مطمئن شوید که کوکی‌های نشست به مبدأ اصلی forward می‌شوند. برای مرور دقیق نقش CDN در بافت ووکامرس، CDN چگونه سرعت سایت را بهبود می‌دهد را ببینید.

معماری پایدار برای سبد خرید مطمئن

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

  1. صفحات سبد را از کش مستثنا کنید: صفحات سبد، تسویه‌حساب و حساب کاربری باید همیشه از کش صفحه مستثنا باشند. این تنظیم در همه افزونه‌های کش محبوب به‌طور پیش‌فرض فعال است؛ اگر غیرفعال است، فعالش کنید.
  2. اسکریپت‌های ووکامرس را از بهینه‌سازی تهاجمی مستثنا کنید: فایل‌های cart-fragments.js، add-to-cart.js و cart.js باید از minify، combine و defer استثنا شوند تا fragment AJAX کار کند.
  3. کوکی SameSite را درست تنظیم کنید: مقدار SameSite=Lax برای اکثر فروشگاه‌ها کافی است. اگر فروشگاه روی چند دامنه کار می‌کند، مقدار None با HTTPS الزامی است.
  4. افزونه‌های امنیتی را برای ووکامرس تنظیم کنید: مسیر /wp-admin/admin-ajax.php?action=wc-ajax و /wp-json/wc/store/ باید در تنظیمات افزونه امنیتی استثنا شوند.
  5. فایل‌های template override را به‌روز نگه دارید: در قالب فرزند، فایل‌های override ووکامرس را دوره‌ای بازبینی کنید و با نسخه جدید هم‌راستا کنید.
  6. پایش خودکار سبد خرید: یک اسکریپت ساده بنویسید که هر ساعت یک محصول را به سبد اضافه کند، صفحه سبد را باز کند، و بررسی کند که محصول در سبد هست یا نه. اگر شکست خورد، به شما هشدار دهد. این کار جلوی «ماه‌ها فروش صفر» را می‌گیرد.
  7. پشتیبان‌گیری منظم از دیتابیس: اگر فروشگاه شما به مشکل خورد، بکاپ تازه بازگردانی سریع را ممکن می‌کند. اصول پشتیبان‌گیری در بکاپ‌گیری از فروشگاه ووکامرس آمده است.
  8. تست روی مرورگرهای مختلف: سبد خرید را در Chrome، Safari، Firefox و در حالت موبایل تست کنید. تفاوت‌های مرورگرها می‌تواند مشکلات را زودتر آشکار کند.
  9. تست روی محیط استجینگ: پیش از هر تغییر در افزونه کش، امنیتی یا قالب، روی محیط استجینگ با همان پیکربندی سرور تست کنید. مراحل ساخت و استفاده از استجینگ در تست و دیباگ پروژه‌های توسعه وردپرس آمده است.
  10. رعایت استانداردهای کدنویسی: اگر کد سفارشی روی fragment AJAX ووکامرس می‌نویسید، اصول استاندارد را رعایت کنید. مرور اصول در استانداردهای کدنویسی وردپرس چیست و کاربرد عملی در استفاده از WordPress Coding Standards در پروژه‌ها آمده است.

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

سخن پایانی

خطای عدم نمایش سبد خرید در ووکامرس، در نگاه اول یکی از پرهزینه‌ترین انواع خطا در فروشگاه‌های اینترنتی است چون مستقیم جلوی فرآیند خرید را می‌گیرد. این خطا در عمل همیشه در یکی از پنج لایه‌ای که در این مقاله بررسی کردیم ریشه دارد: پیکربندی نادرست صفحات سیستمی و شورت‌کد سبد، مشکل در کش و مدیریت نشست و کوکی، خطا در fragment AJAX و اسکریپت‌های ووکامرس، تعارض قالب و template override، و محدودیت‌های REST API و کوکی و منابع سرور. ابزار اصلی عیب‌یابی در این بافت، ترکیب سه چیز است: تب Application مرورگر برای بررسی کوکی‌های نشست، تب Network برای بررسی درخواست‌های AJAX، و تست با قالب پیش‌فرض ووکامرس برای تفکیک مسئله قالب از مسئله افزونه. مسیر عیب‌یابی که در چک‌لیست ارائه کردم، همان ترتیبی است که در پروژه‌های واقعی مرا سریع به علت رسانده؛ نکته کلیدی این است که از ارزان‌ترین گام شروع کنید و به گران‌ترین برسید. در بلندمدت، انضباط در استثنا کردن صفحات سبد از کش، تنظیم درست کوکی SameSite، استثنای اسکریپت‌های ووکامرس از بهینه‌سازی تهاجمی، و پایش خودکار سبد خرید، مهم‌تر از هر راه‌حل لحظه‌ای است — چون این انضباط است که اجازه نمی‌دهد سبد خرید، قلب فروشگاه شما، از کار بیفتد.

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