راهنمای علت‌یابی و رفع مشکل کار نکردن کد کوتاه وردپرس
شورت‌کد در محتوا به‌جای رندر شدن، به‌صورت متن خام روی صفحه ظاهر می‌شود، در سایدبار کار می‌کند ولی در نوشته نه، یا بعد از تغییر قالب و افزونه غیب میشو
کد کوتاه وردپرس کار نمی کند و این خطا یکی از سردرگم‌کننده‌ترین مشکلاتی است که هم برای مبتدی و هم برای توسعه‌دهنده پیش می‌آید، چون رفتار ظاهری آن ساده است ولی ریشه‌هایش بسیار متنوع. شورت‌کد (Shortcode) به‌جای اینکه رندر شود، به‌صورت متن خام روی صفحه ظاهر می‌شود. سال‌هاست روی سایت‌های وردپرسی با این مشکل مواجه می‌شوم و در تجربه‌ام، ریشه‌ی این خطا تقریباً همیشه در یک لایه‌ی ناپیدا پنهان است: ترتیب اجرای هوک‌ها، محل قرار گرفتن کد ثبت‌کننده، یا ناسازگاری با بلوک‌های گوتنبرگ و صفحه‌سازها.
این مقاله را برای عیب‌یابی نظام‌مند نوشته‌ام، نه برای وصل کردن راه‌حل‌های آماده. اگر شورت‌کد یک افزونه در نوشته‌ی شما کار نمی‌کند، اگر کد کوتاه داخل ویجت یا فیلد سفارشی نمایش داده نمی‌شود، یا اگر بعد از مهاجرت یا تغییر قالب، شورت‌کدهای قبلی از کار افتاده‌اند، ترتیب بخش‌ها همان مسیری است که در بحران‌های واقعی اجرا می‌کنم.
شورت‌کد در وردپرس دقیقاً چه چیزی است؟
شورت‌کد یا کد کوتاه، یک میان‌بر ساده در محتوای وردپرس است که با علامت براکت مشخص می‌شود؛ مثل [gallery] یا [contact-form-7 id="123"]. توضیح تکمیلی این مفهوم در ویکی‌پدیا موجود است، ولی جان ماجرا در این نکته است که شورت‌کد، به‌تنهایی هیچ معنایی ندارد: باید یک افزونه یا قالب، تابعی با آن نام را ثبت کرده باشد تا وردپرس بتواند آن را با خروجی درست جایگزین کند.
وقتی وردپرس محتوای یک نوشته یا برگه را رندر می‌کند، تابع do_shortcode روی متن اعمال می‌شود. این تابع، شورت‌کدها را پیدا می‌کند و به تابع ثبت‌کننده‌ی آن‌ها می‌فرستد و نتیجه‌ی خروجی را در متن جایگزین می‌کند. اگر تابع ثبت‌کننده در آن لحظه در دسترس نباشد، شورت‌کد به‌صورت متن خام باقی می‌ماند. همین رفتار ساده، ریشه‌ی همه‌ی خطاهای مربوط به کد کوتاه است. مباحث پایه‌ای ساختار وردپرس در وردپرس چیست و چگونه شروع کنیم باز شده است.
نکته‌ی مهمی که در پروژه‌های واقعی بارها دیده‌ام این است که مشکل «کار نکردن شورت‌کد» دو معنی کاملاً متفاوت دارد: در یک حالت، شورت‌کد اصلاً ثبت نشده و متن خام نمایش داده می‌شود. در حالت دیگر، شورت‌کد ثبت شده ولی خروجی آن به‌درستی رندر نمی‌شود. تفکیک این دو، اولین گام در تشخیص است. اگر متن خام می‌بینید، ریشه در ثبت یا اولویت است. اگر خروجی ناقص می‌بینید، ریشه در رندر است. مباحث مرتبط در ساخت شورت‌کد در وردپرس باز شده است.
شورت‌کد، یک قرارداد است نه یک قابلیت ذاتی. اگر طرف دوم قرارداد (تابع ثبت‌کننده) در لحظه‌ی اجرای قرارداد حاضر نباشد، وردپرس آن را به‌عنوان متن خام می‌بیند.
انواع خطای شورت‌کد و نشانه‌ی هرکدام
خطاهای شورت‌کد در وردپرس، نشانه‌های متنوعی دارند که هرکدام به ریشه‌ی متفاوتی اشاره می‌کنند:
| نشانه در نمایش سایت | ریشه‌ی احتمالی | اقدام اولیه |
|---|---|---|
متن خام [myshortcode] روی صفحه | تابع ثبت‌کننده در دسترس نیست | بررسی افزونه یا کد سفارشی |
| شورت‌کد در نوشته کار می‌کند ولی در ویجت نه | تنظیم نادرست do_shortcode در ویجت | فعال‌سازی پردازش شورت‌کد در ویجت |
| شورت‌کد در متن کار می‌کند ولی در فیلد سفارشی نه | عدم استفاده از do_shortcode در قالب | اعمال صریح do_shortcode روی فیلد |
| شورت‌کد بعد از تغییر قالب غیب شد | وابستگی به تابع قالب قدیمی | انتقال تابع به افزونه یا چایلد |
| شورت‌کد بعد از کش، قدیمی نمایش داده می‌شود | کش صفحه یا کش شورت‌کد | پاک‌سازی کش افزونه |
| شورت‌کد فقط برای کاربران مهمان کار نمی‌کند | کش یا محدودیت شورت‌کد | بررسی استثنای کش برای مهمان |
| شورت‌کد در بلوک گوتنبرگ نمی‌رندر می‌شود | استفاده از بلوک اشتباه یا صفحه‌ساز | استفاده از بلوک Shortcode |
| شورت‌کد در فید RSS یا ایمیل نمایش داده می‌شود | عدم اعمال do_shortcode در فید | افزودن فیلتر به فید |
در تجربه‌ی چندساله‌ام، چهار نشانه‌ی اول شایع‌تر هستند و در ۷۰ درصد موارد، با بررسی ثبت تابع یا اصلاح اولویت هوک حل می‌شوند. بقیه‌ی موارد، نیازمند عیب‌یابی دقیق‌تر در لایه‌های کش یا صفحه‌ساز است.
ده ریشه‌ی اصلی کار نکردن شورت‌کد
در عیب‌یابی این خطا روی سایت‌های وردپرسی، این ده ریشه بیش از بقیه تکرار می‌شوند:
ریشه‌ی اول: ثبت شورت‌کد در اولویت اشتباه
شایع‌ترین دلیل. اگر تابع ثبت شورت‌کد با اولویت پایین (بعد از init) ثبت شود ولی محتوا قبل از آن رندر شود، شورت‌کد به‌صورت متن خام نمایش داده می‌شود. راه‌حل: استفاده از اولویت پیش‌فرض init برای ثبت شورت‌کدها. مباحث مرتبط در نحوه استفاده از هوک‌های وردپرس باز شده است.
ریشه‌ی دوم: غیرفعال شدن افزونه‌ی ثبت‌کننده
اگر افزونه‌ای که شورت‌کد را ثبت کرده بود غیرفعال یا حذف شده باشد، شورت‌کد به‌صورت متن خام روی صفحه باقی می‌ماند. این سناریو در سایت‌هایی که افزونه‌ها بازبینی می‌شوند شایع‌تر است. راه‌حل: بررسی لاگ افزونه‌های حذف‌شده و بازنصب یا جایگزینی آن‌ها.
ریشه‌ی سوم: عدم اعمال do_shortcode در قالب
اگر در قالب سفارشی خود از the_field یا توابع مشابه برای نمایش فیلد استفاده می‌کنید، شورت‌کد به‌طور خودکار پردازش نمی‌شود. باید صریحاً do_shortcode روی خروجی اعمال کنید. مباحث مرتبط در ساخت فیلد سفارشی در وردپرس باز شده است.
ریشه‌ی چهارم: تداخل صفحه‌سازها
صفحه‌سازهایی مثل Elementor یا WPBakery، کد خود را در جدول‌های جداگانه ذخیره می‌کنند و ممکن است شورت‌کدها را در پردازش اولیه نادیده بگیرند. راه‌حل: استفاده از ویجت مخصوص شورت‌کد در همان صفحه‌ساز. مباحث مرتبط در بررسی افزونه المنتور باز شده است.
ریشه‌ی پنجم: عدم پردازش شورت‌کد در بلوک گوتنبرگ
در گوتنبرگ، اگر شورت‌کد را داخل بلوک Paragraph وارد کنید، به‌صورت متن خام نمایش داده می‌شود. باید از بلوک Shortcode استفاده کنید. مباحث مرتبط در گوتنبرگ و آینده‌ی ویرایش محتوا باز شده است.
ریشه‌ی ششم: عدم پردازش در ویجت‌ها
به‌طور پیش‌فرض، ویجت‌های وردپرس شورت‌کد را پردازش نمی‌کنند. باید با فیلتر widget_text این قابلیت را فعال کنید. راه‌حل: افزودن فیلتر do_shortcode به محتوای ویجت.
ریشه‌ی هفتم: تداخل کش صفحه
اگر افزونه‌ی کش، صفحه را قبل از پردازش شورت‌کد ذخیره کرده باشد، ممکن است کاربران نسخه‌ی قبلی را ببینند. راه‌حل: پاک‌سازی کش و بررسی تنظیمات استثنای کش. مباحث مرتبط در بهترین افزونه‌های کش وردپرس باز شده است.
ریشه‌ی هشتم: مشکل در فایل‌های فید و ایمیل
در فید RSS و ایمیل‌های وردپرس، شورت‌کدها به‌طور پیش‌فرض پردازش نمی‌شوند. اگر شورت‌کدی در محتوا استفاده می‌کنید که باید در فید یا ایمیل نمایش داده شود، باید فیلترهای مناسب را اضافه کنید. راه‌حل: استفاده از فیلتر the_content_feed و هوک‌های مشابه.
ریشه‌ی نهم: مشکل در ترتیب اجرای هوک‌ها
اگر شورت‌کد شما وابسته به افزونه‌ی دیگری باشد و ترتیب اجرای هوک‌ها نادرست باشد، ممکن است شورت‌کد قبل از آماده شدن وابستگی‌اش رندر شود. راه‌حل: بررسی وابستگی‌ها و تنظیم دقیق اولویت هوک. مباحث مرتبط در اولویت هوک در وردپرس باز شده است.
ریشه‌ی دهم: تغییر در API افزونه
گاهی افزونه‌ای که شورت‌کد را ثبت کرده، ساختار API خود را تغییر می‌دهد ولی نام شورت‌کد را تغییر نمی‌دهد. نتیجه این است که شورت‌کد قدیمی به‌صورت متن خام نمایش داده می‌شود. راه‌حل: بررسی changelog افزونه و به‌روزرسانی محتوا. مباحث مرتبط در بررسی سازگاری افزونه‌ها باز شده است.
پروتکل واکنش سریع در بحران
اگر سایت شما همین حالا شورت‌کد را به‌صورت متن خام نمایش می‌دهد و کاربران شکایت دارند، این پنج حرکت را به همین ترتیب اجرا کنید:
- تشخیص نوع شورت‌کد: نام شورت‌کد را یادداشت کنید. با جستجوی آن در فهرست افزونه‌ها یا سایت رسمی، افزونه‌ی ثبت‌کننده را پیدا کنید.
- بررسی فعال بودن افزونه: اگر افزونه‌ی ثبت‌کننده غیرفعال است، آن را فعال کنید و صفحه را دوباره بارگذاری کنید.
- پاک‌سازی کش: کش مرورگر، کش افزونه و کش سرور را پاک کنید.
- بررسی اولویت اجرای هوک: اگر شورت‌کد سفارشی است، تابع ثبت آن را با اولویت پیش‌فرض
initثبت کنید. - تست در حالت متفاوت: شورت‌کد را در یک برگه‌ی جدید با ویرایشگر کلاسیک تست کنید تا اگر ریشه در گوتنبرگ است، شناسایی شود.
نکته‌ی میدانی: در بحران، اول نام شورت‌کد را دقیقاً یادداشت کنید. تجربه‌ی من نشان داده که در نیمی از موارد، کاربر متن را با حرف بزرگ یا کوچک اشتباه تایپ کرده یا فاصله‌ای اضافه گذاشته است. یک اشتباه کوچک در نوشتن شورت‌کد، آن را کاملاً از کار می‌اندازد.
تشخیص دقیق با DevTools و لاگ‌ها
ابزارهای تشخیصی، دقیق‌ترین راه پیدا کردن ریشه‌ی کار نکردن شورت‌کد هستند. سه ابزار کلیدی:
DevTools مرورگر
در مرورگر، ابزار DevTools را باز کنید (کلید F12) و به تب Console بروید. اگر خطای JavaScript مربوط به شورت‌کد باشد، در این تب دیده می‌شود. همچنین در تب Elements، می‌توانید ساختار HTML خروجی را بررسی کنید. اگر شورت‌کد به‌صورت متن خام در تگ <p> یا مشابه دیده می‌شود، ریشه در پردازش سمت سرور است. مباحث مرتبط در پیدا کردن خطاهای جاوااسکریپت در کنسول باز شده است.
لاگ PHP
اگر خطای PHP در پردازش شورت‌کد رخ دهد، در لاگ PHP ثبت می‌شود. برای فعال‌سازی، در wp-config.php مقادیر WP_DEBUG و WP_DEBUG_LOG را تنظیم کنید. لاگ در wp-content/debug.log ذخیره می‌شود. روش دقیق خواندن لاگ در بررسی خطاهای سرور در لاگ‌ها باز شده است.
تست شورت‌کد در محیط استیجینگ
یک محیط استیجینگ بسازید و شورت‌کد را در آنجا تست کنید. اگر در استیجینگ کار می‌کند ولی روی سایت زنده نه، ریشه در کش، افزونه‌ی امنیتی یا تنظیمات سرور است.
بررسی خروجی head با یک شورت‌کد ساده
یک شورت‌کد ساده مثل [gallery] را در یک برگه‌ی تستی قرار دهید. اگر این شورت‌کد هم به‌صورت متن خام نمایش داده شد، احتمالاً مشکل در سراسر سایت است و ریشه در کش یا افزونه‌ی اصلی است.
ترتیب اجرای هوک‌ها و اولویت ثبت شورت‌کد
ترتیب اجرای هوک‌ها، یکی از شایع‌ترین و کم‌شناخته‌شده‌ترین ریشه‌های کار نکردن شورت‌کد است. برای درک این مفهوم، باید بدانید که در وردپرس، هوک‌ها با ترتیب مشخص و اولویت مشخص اجرا می‌شوند. توضیح دقیق اولویت هوک در اولویت هوک وردپرس باز شده است.
الگوی صحیح ثبت شورت‌کد
شورت‌کدها باید در هوک init و با اولویت پیش‌فرض ۱۰ ثبت شوند:
function my_custom_shortcode() {
return 'محتوای شورت‌کد';
}
add_action('init', function() {
add_shortcode('myshortcode', 'my_custom_shortcode');
});الگوی اشتباه رایج
اگر شورت‌کد را با اولویت بالاتر یا در هوک اشتباه ثبت کنید، ممکن است قبل از رندر محتوا فرصت ثبت پیدا نکند:
// اشتباه: ثبت در اولویت بالا
add_action('init', function() {
add_shortcode('myshortcode', 'my_custom_shortcode');
}, 999);
// اشتباه: ثبت در هوک نامناسب
add_action('wp_loaded', function() {
add_shortcode('myshortcode', 'my_custom_shortcode');
});مشکل خاص: شورت‌کدهایی که به افزونه‌ی دیگری وابسته‌اند
اگر شورت‌کد شما به توابع افزونه‌ی دیگری نیاز دارد، باید مطمئن شوید که آن افزونه قبل از ثبت شورت‌کد، لود شده است. راه‌حل: استفاده از اولویت پایین‌تر روی init یا بررسی صریح وجود تابع قبل از استفاده:
add_action('init', function() {
if (function_exists('other_plugin_function')) {
add_shortcode('myshortcode', 'my_custom_shortcode');
}
}, 20);مباحث مرتبط با ساختار شورت‌کد در ساخت شورت‌کد با کدنویسی وردپرس باز شده است.
do_shortcode، apply_filters و فیلدهای سفارشی
یکی از ریشه‌های شایع خطای شورت‌کد، عدم اعمال صریح do_shortcode روی خروجی است. توضیح دقیق این تابع در توابع وردپرس برای دریافت اطلاعات نوشته باز شده است.
کاربرد do_shortcode
تابع do_shortcode وظیفه‌ی پردازش شورت‌کدها را برعهده دارد. اگر شما با یک فیلد سفارشی یا کوئری سفارشی داده استخراج می‌کنید، وردپرس به‌طور خودکار do_shortcode روی آن اعمال نمی‌کند:
// اشتباه: شورت‌کد پردازش نمی‌شود
echo $custom_field_value;
// درست: اعمال صریح do_shortcode
echo do_shortcode($custom_field_value);کاربرد فیلدهای ACF
اگر از افزونه‌ی Advanced Custom Fields استفاده می‌کنید، باید به‌طور صریح do_shortcode روی خروجی اعمال کنید:
$field_value = get_field('my_field');
echo do_shortcode($field_value);پردازش شورت‌کد در ویجت‌ها
ویجت‌ها به‌طور پیش‌فرض شورت‌کد را پردازش نمی‌کنند. برای فعال‌سازی این قابلیت، باید به فایل functions.php قالب یا چایلد‌تم اضافه کنید:
add_filter('widget_text', 'do_shortcode');
add_filter('widget_text_content', 'do_shortcode');
add_filter('widget_custom_html_content', 'do_shortcode');مباحث مرتبط در قالب چایلد وردپرس باز شده است.
پردازش شورت‌کد در فید و ایمیل
در فید RSS و ایمیل‌های وردپرس، شورت‌کدها به‌طور پیش‌فرض پردازش نمی‌شوند. برای فعال‌سازی:
add_filter('the_content_feed', 'do_shortcode');شورت‌کد در بلوک‌های گوتنبرگ و صفحه‌سازها
ویرایشگر گوتنبرگ و صفحه‌سازهای وردپرسی، رفتار متفاوتی با شورت‌کد دارند:
شورت‌کد در بلوک Paragraph گوتنبرگ
اگر شورت‌کد را در بلوک Paragraph وارد کنید، به‌صورت متن خام نمایش داده می‌شود. علت این است که گوتنبرگ بلوک Paragraph را به‌عنوان متن خام ذخیره می‌کند و do_shortcode روی آن اعمال نمی‌شود. راه‌حل: استفاده از بلوک Shortcode مخصوص:
- در ویرایشگر گوتنبرگ، روی دکمه‌ی + کلیک کنید.
- در جستجو، عبارت Shortcode را وارد کنید.
- بلوک Shortcode را انتخاب و شورت‌کد را در آن وارد کنید.
شورت‌کد در بلوک HTML سفارشی
اگر از بلوک Custom HTML استفاده می‌کنید، باید شورت‌کد را در متن خام قرار دهید و مطمئن شوید که بلوک HTML، محتوای شما را به‌درستی ذخیره می‌کند:
// درست: بلوک HTML سفارشی با شورت‌کد
[myshortcode]شورت‌کد در صفحه‌سازها
صفحه‌سازهایی مثل Elementor، WPBakery و Divi، شورت‌کدها را فقط در ویجت مخصوص شورت‌کد پردازش می‌کنند. اگر از متن ساده استفاده کنید، شورت‌کد به‌صورت متن خام نمایش داده می‌شود. مباحث مرتبط در بررسی افزونه المنتور باز شده است.
مشکل خاص: کدهای کوتاه در بلوک‌های پویا
بعضی بلوک‌های پویا در گوتنبرگ (مثل بلوک Query Loop) ممکن است شورت‌کدها را در خروجی نهایی پردازش نکنند. راه‌حل: استفاده از فیلتر render_block:
add_filter('render_block', function($block_content) {
return do_shortcode($block_content);
}, 10);کش، افزونه‌ی بهینه‌سازی و ناسازگاری
افزونه‌های کش و بهینه‌سازی، می‌توانند با پردازش شورت‌کد تضاد داشته باشند:
کش و شورت‌کدهای پویا
اگر شورت‌کد شما خروجی پویا (مثل فرم تماس یا جدول قیمت) دارد، کش صفحه می‌تواند آن را ثابت کند و کاربران نسخه‌ی اولیه را ببینند. راه‌حل: شورت‌کدهای پویا را از کش مستثنی کنید. مباحث مرتبط در بهترین افزونه‌های کش وردپرس باز شده است.
کش مرورگر و شورت‌کدهای پویا
اگر شورت‌کد شما با تاریخ یا زمان کار می‌کند، کش مرورگر می‌تواند مقدار قدیمی را نمایش دهد. راه‌حل: تنظیم سربرگ Cache-Control برای صفخات پویا یا افزودن timestamp به خروجی شورت‌کد.
بهینه‌سازی CSS و JS و شورت‌کدها
افزونه‌های بهینه‌سازی که CSS و JS را ترکیب می‌کنند، ممکن است با شورت‌کدهایی که فایل‌های خود را بارگذاری می‌کنند تضاد داشته باشند. راه‌حل: بررسی تنظیمات بهینه‌سازی و مستثنی کردن فایل‌های شورت‌کد خاص. مباحث مرتبط در تأثیر افزونه‌ها بر سرعت سایت باز شده است.
روش تشخیص کش به‌عنوان ریشه
سایت را در حالت Incognito باز کنید و شورت‌کد را تست کنید. اگر در حالت ناشناس کار کرد ولی در حالت معمولی نه، ریشه در کش مرورگر است. اگر در حالت ناشناس هم کار نکرد، کش افزونه را غیرفعال و مجدداً تست کنید.
شورت‌کد در ویجت‌ها و سایدبار
شورت‌کد در ویجت‌ها به‌طور پیش‌فرض پردازش نمی‌شود و این یکی از ریشه‌های شایع کار نکردن شورت‌کد است:
فعال‌سازی پردازش شورت‌کد در ویجت متن
برای فعال‌سازی پردازش شورت‌کد در ویجت متن، این فیلتر را به فایل functions.php چایلد‌تم اضافه کنید:
add_filter('widget_text', 'do_shortcode');
add_filter('widget_text_content', 'do_shortcode');فعال‌سازی در ویجت HTML سفارشی
برای ویجت HTML سفارشی، از فیلتر زیر استفاده کنید:
add_filter('widget_custom_html_content', 'do_shortcode');مشکل خاص: ویجت‌های بلوکی گوتنبرگ
در ویجت‌های بلوکی گوتنبرگ، باید از بلوک Shortcode استفاده کنید، نه بلوک Paragraph. اگر از بلوک Paragraph استفاده کنید، شورت‌کد به‌صورت متن خام نمایش داده می‌شود.
تداخل افزونه‌ها و قالب
افزونه‌ها و قالب، لایه‌ی بعدی ریشه‌های خطای شورت‌کد هستند. سه دسته افزونه بیشتر از بقیه مشکوک هستند:
افزونه‌های امنیتی
افزونه‌های امنیتی مثل Wordfence ممکن است شورت‌کدهای خاصی را به‌عنوان مخرب شناسایی و مسدود کنند. این سناریو در سایت‌هایی که شورت‌کدهای کد PHP را اجرا می‌کنند (مثل Insert PHP Code Snippet) شایع‌تر است. راه‌حل: بررسی لاگ افزونه‌ی امنیتی.
افزونه‌های بهینه‌سازی
افزونه‌های بهینه‌سازی که محتوا را بازنویسی می‌کنند، ممکن است شورت‌کدها را هم تغییر دهند. راه‌حل: غیرفعال‌سازی موقت افزونه‌های بهینه‌سازی و تست مجدد.
قالب و کد سفارشی
اگر در functions.php قالب، تابعی تعریف شده باشد که شورت‌کد خاصی را بازنویسی کند، ممکن است با شورت‌کد اصلی تضاد داشته باشد. راه‌حل: بررسی دقیق کد قالب و حذف تعریف‌های تکراری. مباحث مرتبط در کدنویسی اختصاصی برای قالب باز شده است.
روش تشخیص افزونه‌ی مقصر
روش حذف تدریجی، دقیق‌ترین راه است. در محیط استیجینگ، ابتدا تمام افزونه‌ها را غیرفعال کنید و سپس یکی‌یکی فعال کنید تا مقصر پیدا شود. روش دقیق این کار در پیدا کردن افزونه‌ی مشکل‌ساز وردپرس باز شده است.
بازگردانی شورت‌کدها و اولویت‌بندی
بعد از پیدا کردن ریشه، نوبت به بازگردانی شورت‌کدها می‌رسد. ترتیب اولویت‌بندی من در پروژه‌های واقعی:
- بازگردانی سریع شورت‌کدهای پرترافیک: ابتدا شورت‌کدهایی که در صفحات پربازدید یا محصولات اصلی سایت هستند را بررسی و اصلاح کنید.
- فعال‌سازی افزونه‌ی ثبت‌کننده: اگر افزونه غیرفعال است، آن را فعال کنید.
- اصلاح اولویت هوک: اگر شورت‌کد سفارشی است، اولویت هوک را به مقدار پیش‌فرض تغییر دهید.
- افزودن do_shortcode: اگر در فیلد سفارشی یا قالب استفاده می‌شود،
do_shortcodeرا به‌طور صریح اعمال کنید. - پاک‌سازی کش: کش مرورگر، کش افزونه و کش سرور را پاک کنید.
- مستندسازی: ریشه، روش تشخیص و راه‌حل را ثبت کنید.
پایش مستمر و پیشگیری
بعد از رفع، مهم‌تر از رفع، پیشگیری است. پنج سطح پایش توصیه می‌کنم:
سطح اول: پایش دوره‌ای شورت‌کدهای سایت
هفته‌ای یک‌بار، صفحاتی که شورت‌کد دارند را با مرورگر باز کنید و نمایش آن‌ها را بررسی کنید. اگر شورت‌کدی به‌صورت متن خام نمایش داده شد، بلافاصله بررسی کنید.
سطح دوم: پایش سازگاری بعد از آپدیت
بعد از هر آپدیت افزونه یا قالب، سریع تست کنید که شورت‌کدها سالم هستند یا نه. اگر مشکل ظاهر شد، قبل از بحران، ریشه را پیدا کنید. مباحث مرتبط در بررسی سازگاری افزونه‌ها باز شده است.
سطح سوم: مستندسازی شورت‌کدهای سفارشی
برای شورت‌کدهای سفارشی، مستندات دقیق بنویسید که شامل نام، پارامترها و افزونه‌ی ثبت‌کننده باشد. این مستندات در عیب‌یابی سریع‌تر کمک می‌کند.
سطح چهارم: تست بعد از تغییر قالب
اگر قالب سایت را عوض می‌کنید، قبل از انتشار نهایی، تمام شورت‌کدهای سفارشی را تست کنید. بعضی شورت‌کدها ممکن است به تابع قالب قدیمی وابسته باشند و در قالب جدید از کار بیفتند. مباحث مرتبط در تغییر قالب بدون آسیب باز شده است.
سطح پنجم: بکاپ منظم قبل از تغییرات
قبل از هر تغییر در افزونه‌ها، قالب یا کد سفارشی، بکاپ کامل بگیرید. مباحث مرتبط در بهترین افزونه‌های بکاپ وردپرس باز شده است.
پرسش‌های پرتکرار درباره کار نکردن شورت‌کد وردپرس
چرا شورت‌کد به‌صورت متن خام نمایش داده می‌شود؟
این الگو معمولاً به یکی از سه دلیل برمی‌گردد: افزونه‌ی ثبت‌کننده شورت‌کد غیرفعال یا حذف شده، تابع ثبت شورت‌کد در اولویت اشتباه ثبت شده، یا محتوا در فیلد سفارشی است و do_shortcode روی آن اعمال نشده. بررسی DevTools و لاگ PHP، سریع‌ترین راه تشخیص است.
آیا شورت‌کد در گوتنبرگ کار می‌کند؟
بله، ولی به شرط استفاده از بلوک Shortcode. اگر شورت‌کد را در بلوک Paragraph وارد کنید، به‌صورت متن خام نمایش داده می‌شود. مباحث مرتبط در گوتنبرگ و آینده‌ی ویرایش محتوا باز شده است.
چرا شورت‌کد در ویجت سایدبار کار نمی‌کند؟
به‌طور پیش‌فرض، ویجت‌های وردپرس شورت‌کد را پردازش نمی‌کنند. باید فیلتر widget_text را به do_shortcode متصل کنید. راه‌حل در بخش «شورت‌کد در ویجت‌ها» همین مقاله آمده است.
آیا افزونه‌های کش می‌توانند باعث کار نکردن شورت‌کد شوند؟
بله، به‌خصوص برای شورت‌کدهای پویا که محتوایشان با هر بار بارگذاری تغییر می‌کند. راه‌حل: شورت‌کدهای پویا را از کش مستثنی کنید یا از کش متغیر-محور استفاده کنید. مباحث مرتبط در افزونه‌های کش وردپرس باز شده است.
چرا شورت‌کد بعد از تغییر قالب غیب شد؟
اگر شورت‌کد در فایل functions.php قالب قدیمی ثبت شده بود، بعد از تغییر قالب، تابع ثبت‌کننده از دسترس خارج می‌شود. راه‌حل: انتقال تابع ثبت شورت‌کد به یک افزونه‌ی سفارشی یا به چایلد‌تم جدید. مباحث مرتبط در قالب چایلد وردپرس باز شده است.
آیا do_shortcode روی همه‌ی محتوا اعمال می‌شود؟
به‌طور پیش‌فرض، do_shortcode فقط روی محتوای اصلی نوشته و برگه اعمال می‌شود. برای ویجت‌ها، فیلدهای سفارشی، فید و ایمیل، باید به‌طور صریح این تابع را فراخوانی کنید یا فیلتر مناسب اضافه کنید.
چطور بفهمم مشکل از کدام افزونه است؟
روش حذف تدریجی دقیق‌ترین راه است: ابتدا تمام افزونه‌ها را غیرفعال کنید و شورت‌کد را تست کنید. سپس افزونه‌ها را یکی‌یکی فعال کنید تا مقصر پیدا شود. مباحث مرتبط در پیدا کردن افزونه‌ی مشکل‌ساز باز شده است.
آیا شورت‌کد می‌تواند کد PHP اجرا کند؟
به‌طور پیش‌فرض، شورت‌کدها فقط توابع PHP را ثبت‌شده فراخوانی می‌کنند، نه اینکه کد PHP خام را اجرا کنند. اگر می‌خواهید کد PHP خام در محتوا اجرا شود، باید از افزونه‌های مخصوص مثل Insert PHP Code Snippet استفاده کنید که خودشان ریسک امنیتی دارند و باید با احتیاط استفاده شوند.
چرا شورت‌کد در فید RSS نمایش داده می‌شود؟
در فید RSS، وردپرس به‌طور پیش‌فرض do_shortcode را اعمال نمی‌کند تا از اجرای ناخواسته‌ی کد جلوگیری شود. اگر می‌خواهید شورت‌کد در فید نمایش داده شود، فیلتر the_content_feed را اضافه کنید.
آیا شورت‌کد می‌تواند در ایمیل‌های ووکامرس نمایش داده شود؟
در ایمیل‌های ووکامرس، شورت‌کدها به‌طور پیش‌فرض پردازش نمی‌شوند. برای فعال‌سازی، باید فیلتر woocommerce_email_order_meta یا فیلترهای مشابه را بررسی کنید. مباحث مرتبط در رفع خطای ارسال ایمیل سفارش در ووکامرس باز شده است.
نکته‌های میدانی از رفع خطای شورت‌کد
در پایان این مقاله، چند نکته‌ای را می‌گویم که در مستندات رسمی کم‌تر به آن‌ها اشاره می‌شود ولی در پروژه‌های واقعی بارها به کارم آمده:
نخست: قبل از هر چیز، نام شورت‌کد را دقیقاً بررسی کنید. تجربه‌ی من نشان داده که در نیمی از موارد، کاربر متن را با حرف بزرگ یا کوچک اشتباه تایپ کرده یا فاصله‌ای اضافه در آن گذاشته است. یک اشتباه کوچک در نوشتن شورت‌کد، آن را کاملاً از کار می‌اندازد. اگر شورت‌کد به‌درستی تایپ شده و باز هم کار نمی‌کند، به سراغ بخش‌های دیگر این مقاله بروید.
دوم: هیچ‌گاه تابع ثبت شورت‌کد را در فایل functions.php قالب والد ننویسید. اگر قالب را عوض کنید یا آپدیت کنید، شورت‌کد از کار می‌افتد. همیشه تابع ثبت شورت‌کد را در یک افزونه‌ی سفارشی یا در چایلد‌تم قرار دهید. این عادت ساده، در پروژه‌های من از فاجعه‌های بزرگ جلوگیری کرده است. مباحث مرتبط در کدنویسی اختصاصی برای افزونه وردپرس باز شده است.
سوم: همیشه شورت‌کدهای سفارشی خود را با یک تابع ساده شروع کنید و بعد پیچیدگی را اضافه کنید. این رویکرد تدریجی، تشخیص مشکل را در مراحل ابتدایی ساده‌تر می‌کند. تجربه‌ی من نشان داده که شورت‌کدهای پیچیده‌ای که یک‌باره نوشته می‌شوند، در اولین اجرا با مشکل مواجه می‌شوند و عیب‌یابی آن‌ها ساعت‌ها وقت می‌گیرد.
در تجربه‌ی چندساله‌ام روی سایت‌های وردپرسی، الگویی که بارها تکرار شده این است که خطای کار نکردن شورت‌کد تقریباً همیشه در یکی از پنج لایه ریشه دارد: اولویت ثبت، فعال بودن افزونه، do_shortcode در فیلد سفارشی، بلوک گوتنبرگ، و کش. تشخیص سریع این لایه، از هر راه‌حل آماده مؤثرتر است. اگر ابزارهای تشخیصی را در اختیار داشته باشید و لایه‌ها را به ترتیب بررسی کنید، این خطا از یک بحران ترسناک به یک تمرین روتین تبدیل می‌شود.
اگر روی سایت خود با نوعی از مشکل کار نکردن شورت‌کد مواجه شده‌اید که در این مقاله پوشش داده نشده، یا اگر راه‌حل متفاوتی پیدا کرده‌اید که به کارتان آمده، برای من جالب است آن را بشنوم. مشخصاً اگر خروجی DevTools یا تکه‌کدی که ریشه‌ی واقعی را نشان داد، با خوانندگان دیگر به اشتراک بگذارید؛ این یادداشت‌های دقیق، برای صاحب سایت بعدی ساعت‌ها زمان صرفه‌جویی می‌کنند. 🧩
نویسنده در وردپرس کار.