خطای کار نکردن شورت‌کد در وردپرس
شورت‌کد وردپرس چرا کار نمی‌کند، چرا خطا ساکت است و چطور با روش لایه‌ای، ریشه را در محتوا، افزونه یا قالب پیدا و بدون آسیب به سایت حل کنیم.
در وردپرس، کمتر ابزاری به اندازهی شورت‌کد، این‌قدر ساده به‌نظر می‌رسد و در عمل این‌قدر می‌تواند دردسرساز شود. یک براکت باز، یک نام، یک براکت بسته — و انتظار دارید داخل نوشته‌تان، یک گالری، یک دکمه، یا یک جدول ظاهر شود. اما وقتی این اتفاق نمی‌افتد، صحنه آشنایی رخ می‌دهد: به‌جای ظاهر شدن محتوا، همان متن خام [gallery] یا [contact-form-7] روی صفحه دیده می‌شود. هیچ خطایی نیست، هیچ پیام قرمزی نیست، فقط یک براکت که بی‌اعتنا به تمام تلاش شما، به‌عنوان متن ساده روی صفحه می‌نشیند.
در سال‌ها کار با سایت‌های وردپرسی، خطای کار نکردن شورت‌کد را در ده‌ها پرونده دیده‌ام. یک بار به‌خاطر تغییر قالب، یک بار بعد از به‌روزرسانی افزونه، یک بار به‌خاطر یک پیکربندی اشتباه در ویرایشگر بلوکی، و بارها به‌خاطر یک اشتباه ساده در نوشتن خود شورت‌کد. آنچه همه این موارد را به هم وصل می‌کند یک نکتهی مهم است: شورت‌کد در وردپرس ذاتاً ساکت است. اگر مرجع ثبت‌کننده‌اش نباشد، اگر در جای درست نباشد، یا اگر قالب خروجی را به‌درستی پردازش نکند، شورت‌کد بی‌صدا نادیده گرفته می‌شود. همین سکوت، تشخیص را برای کاربر عادی دشوار می‌کند.
در این مقاله، همان مسیری را باز می‌کنم که در پروژه‌های واقعی برای تشخیص و رفع این خطا طی می‌کنم. اگر با ساختار پایه‌ای وردپرس آشنایی ندارید، پیشنهاد می‌کنم ابتدا وردپرس چیست و چگونه شروع کنیم را بخوانید؛ چون فهم مکانیزم شورت‌کد بدون درک لایه‌بندی وردپرس، شبیه دیدن یک قطعه بدون تصویر کامل است.
شورت‌کد وردپرس دقیقاً چیست؟
شورت‌کد، یک قطعه‌ی متنی ساده در داخل پرانتز براکت است که وردپرس آن را با یک خروجی پویا جایگزین می‌کند. مثلاً [gallery] را وردپرس به یک گالری تصاویر تبدیل می‌کند، یا [contact-form-7 id="123"] را به فرم تماس مربوطه. مکانیزم آن ساده است: هر افزونه یا قالب، با استفاده از تابع add_shortcode() یک نام را ثبت می‌کند و یک تابع پردازش به آن نسبت می‌دهد. وقتی وردپرس به محتوای یک نوشته می‌رسد، بخش پردازش محتوا این براکت‌ها را شناسایی می‌کند و خروجی مربوطه را جایگزینشان می‌کند.
نکتهی کلیدی اینجاست: شورت‌کد ذاتاً یک قرارداد نرم است. یعنی اگر مرجع ثبت‌کننده‌اش نباشد یا رفتار درستی نداشته باشد، وردپرس هیچ خطایی نمی‌دهد؛ فقط براکت را به‌عنوان متن ساده روی صفحه نمایش می‌دهد. این رفتار، برخلاف خطاهای معمول وردپرس است که حداقل یک پیام مبهم نشان می‌دهند. همین سکوت، منبع اصلی سردرگمی در این نوع خطا است.
شورتکدها در اکوسیستم وردپرس، جایگاه ویژه‌ای دارند.
تقریباً هر افزونه‌ی مهمی از فرم‌سازها تا گالری‌ها، از فروشگاه‌سازها تا صفحه‌سازها یک یا چند شورت‌کد برای جای‌گذاری محتوای خود در نوشته‌ها و برگه‌ها ثبت می‌کند. توضیح کامل این که چه چیزی شورت‌کد را معتبر می‌کند، در افزونه وردپرس چیست و همچنین در راهنمای ساخت شورت‌کد با کدنویسی وردپرس آمده است.
شورت‌کد، در واقع یک پنجره‌ی پویا در دل متن است. اگر آن پنجره باز نشود، به‌جای منظره، فقط قاب را می‌بینید.
چرا خطای شورت‌کد ساکت است؟
برای اینکه بتوانید این خطا را در ریشه تشخیص دهید، اول باید بفهمید چرا اصلاً ساکت است. سه دلیل پشت این سکوت وجود دارد که در تجربه‌ام بارها به آن‌ها برخورده‌ام:
- معماری تحمل‌پذیر: وردپرس عمداً شورت‌کدهای ناشناخته را نادیده می‌گیرد. یعنی اگر شما
[unknown_shortcode]بنویسید، وردپرس همان متن را چاپ می‌کند، نه یک خطا. این تصمیم طراحی، برای جلوگیری از شکستن سایت در صورت نبود یک افزونه گرفته شده. - نبود تعامل مستقیم با کاربر: شورت‌کد در بستر محتوا اجرا می‌شود، نه در رابط کاربری. یعنی پیام موفقیت یا خطا نمایش داده نمی‌شود؛ فقط خروجی نهایی مهم است.
- اجرای شرطی: بسیاری از افزونه‌ها شورت‌کدشان را فقط در شرایط مشخص (مثلاً در صفحه‌ی خاص، برای کاربر مشخص، یا در حالت خاص) فعال می‌کنند. اگر آن شرط برقرار نباشد، شورت‌کد بدون هیچ پیامی نادیده گرفته می‌شود.
این سه دلیل، در کنار هم، خطای شورت‌کد را به یکی از مبهم‌ترین خطاهای وردپرس تبدیل می‌کند. تجربه‌ام می‌گوید در بیشتر پرونده‌ها، کاربر ساعت‌ها وقت صرف می‌کند تا بفهمد چرا یک شورت‌کد کار نمی‌کند؛ درحالی‌که با یک رویکرد لایه‌ای، در چند دقیقه می‌تواند ریشه را پیدا کند.
آناتومی فرآیند پردازش شورت‌کد
در تجربه‌ی خودم، ترسیم فرآیند پردازش شورت‌کد در پنج گره همیشه کمک کرده که تشخیص را ساختاری کنم:
- گره‌ی اول — ثبت شورت‌کد: افزونه یا قالب، با تابع
add_shortcode()یک نام را ثبت می‌کند و تابع پردازشش را تعیین می‌کند. - گره‌ی دوم — بارگذاری افزونه: در هر ریکوئست، وردپرس افزونه‌های فعال را بارگذاری می‌کند. اگر افزونه‌ای غیرفعال باشد، شورت‌کدش هم ثبت نمی‌شود.
- گره‌ی سوم — شناسایی در محتوا: وردپرس محتوای نوشته را اسکن می‌کند و براکت‌ها را شناسایی می‌کند.
- گره‌ی چهارم — اجرای تابع پردازش: تابع پردازش، داده‌ها را می‌گیرد و خروجی HTML را می‌سازد.
- گره‌ی پنجم — جایگزینی در خروجی: خروجی تابع، جایگزین متن شورت‌کد در صفحه‌ی نهایی می‌شود.
هر خطای شورت‌کد، در یکی از این پنج گره رخ می‌دهد. اگر شورت‌کد به‌عنوان متن خام نمایش داده می‌شود، گره‌ی اول یا دوم مسئله دارد. اگر خروجی اشتباه است، گره‌ی چهارم. اگر شورت‌کد در ویرایشگر کار می‌کند اما در فرانت‌اند نه، گره‌ی پنجم. تشخیص دقیق گره، اولین کار شماست.
سناریوی اول: شورت‌کد به‌صورت متن خام نمایش داده می‌شود
شایع‌ترین حالت خطای شورت‌کد، نمایش متن خام آن روی صفحه است. یعنی به‌جای اینکه خروجی شورت‌کد دیده شود، خودِ [gallery] به‌عنوان متن روی صفحه می‌نشیند. این وضعیت، همیشه به یکی از دو دلیل رخ می‌دهد:
- افزونه‌ی ثبت‌کننده غیرفعال است: اگر افزونه‌ای که شورت‌کد را ثبت می‌کند، غیرفعال شده باشد، شورت‌کد شما هم ناشناس می‌شود. این اتفاق، بیشتر بعد از به‌روزرسانی سایت یا انتقال آن رخ می‌دهد.
- شورت‌کد در جای اشتباه قرار گرفته: بعضی شورتکدها فقط در محتوای نوشته کار می‌کنند، نه در ابزارک‌ها یا فایل‌های قالب. اگر جای اشتباه باشند، به‌عنوان متن خام نمایش داده می‌شوند.
تشخیص: اول، فهرست افزونه‌های فعال را ببینید و مطمئن شوید که افزونه‌ی ثبت‌کننده‌ی آن شورت‌کد فعال است. سپس در یک نوشته‌ی تازه، شورت‌کد را امتحان کنید تا مطمئن شوید مشکل از متن قدیمی نیست. اگر شورت‌کد در نوشته‌ی تازه هم کار نمی‌کند، مقصر افزونه است یا نام شورت‌کد اشتباه نوشته شده.
رفع: اگر افزونه غیرفعال شده، آن را فعال کنید. اگر نام شورت‌کد اشتباه است، به مستندات افزونه مراجعه کنید. یک نکتهی ظریف: بعضی افزونه‌ها، شورت‌کدشان را در به‌روزرسانی‌ها تغییر می‌دهند. اگر بعد از یک به‌روزرسانی، شورتکدها به‌صورت متن خام ظاهر شدند، این احتمال را جدی بگیرید.
سناریوی دوم: شورت‌کد کاملاً ناپدید می‌شود
در بعضی موارد، شورت‌کد نه به‌عنوان متن خام نمایش داده می‌شود و نه به‌عنوان خروجی صحیح. فقط ناپدید می‌شود. یعنی در محتوای اصلی هست، اما در خروجی نهایی هیچ اثری از آن نیست. این وضعیت، معمولاً به یکی از سه دلیل رخ می‌دهد:
- تابع پردازش خروجی خالی برمی‌گرداند: بعضی افزونه‌ها، وقتی شرط‌های داخلی‌شان برقرار نیست، خروجی خالی برمی‌گردانند. نتیجه، ناپدید شدن بی‌صدا است.
- شورت‌کد توسط یک فیلتر حذف می‌شود: بعضی افزونه‌ها یا قالب‌ها، فیلتری روی
the_contentنصب می‌کنند که شورتکدها را حذف می‌کند. این اتفاق، بیشتر در قالب‌های تخصصی دیده می‌شود. - شورت‌کد در یک زمینه‌ی اشتباه قرار گرفته: مثلاً در قسمت خلاصه‌ی نوشته، که معمولاً پردازش نمی‌شود.
تشخیص: در DevTools مرورگر، بخش Inspector را باز کنید و ساختار HTML قسمت مربوطه را ببینید. اگر هیچ اثری از خروجی شورت‌کد نیست، احتمال اول یا دوم قوی‌تر است. اگر شورت‌کد در پیشخوان هست اما در فرانت‌اند نه، احتمال سوم را بررسی کنید.
رفع: برای سناریوی اول، به تنظیمات افزونه مراجعه کنید و شرط‌ها را بررسی کنید. برای سناریوی دوم، کد فیلتر قالب را ببینید و آن را حذف یا اصلاح کنید. اگر با قالب سفارشی کار می‌کنید، این موضوع را در قالب چایلد وردپرس چیست به‌عنوان یکی از موارد رایج سفارشی‌سازی مطرح کرده‌ام.
سناریوی سوم: شورت‌کد نتیجه‌ی اشتباهی می‌دهد
در این حالت، شورت‌کد پردازش می‌شود اما خروجی اشتباهی می‌دهد: نه آنچه انتظار داشتید، بلکه چیزی متفاوت. مثلاً یک گالری، با تصاویری اشتباه نمایش داده می‌شود، یا یک فرم، با فیلدهای نامناسب. این وضعیت، معمولاً به یکی از سه دلیل رخ می‌دهد:
- پارامترهای اشتباه در شورت‌کد: شورتکدها معمولاً پارامتر می‌پذیرند. اگر پارامتر اشتباه نوشته شود، خروجی هم اشتباه خواهد بود.
- تنظیمات نادرست در افزونه: بعضی افزونه‌ها، به‌جای پارامترهای شورت‌کد، از تنظیمات درون افزونه استفاده می‌کنند. اگر آن تنظیمات درست نباشند، خروجی هم اشتباه می‌شود.
- تعارض با افزونه‌ی دیگر: گاهی دو افزونه، یک پارامتر مشترک را با مقادیر متفاوت تنظیم می‌کنند و خروجی نهایی ترکیبی نامناسب می‌شود.
تشخیص: ابتدا شورت‌کد را در یک نوشته‌ی تازه و بدون پارامتر اضافه امتحان کنید. اگر خروجی درست شد، پارامترها مقصر بوده‌اند. اگر نه، به تنظیمات افزونه مراجعه کنید. اگر همچنان مسئله باقی است، تعارض افزونه‌ها را با روش غیرفعال‌سازی نیمه‌ای بررسی کنید. مسیر دقیق تشخیص تعارض، در چگونه افزونه مشکل‌ساز وردپرس را پیدا کنیم به تفصیل آمده است.
سناریوی چهارم: در ویرایشگر کار می‌کند، در فرانت‌اند نه
یکی از وضعیت‌های عجیب، زمانی است که شورت‌کد در ویرایشگر به‌درستی نمایش داده می‌شود اما در سایت نهایی، متن خام است. این اتفاق، معمولاً به یکی از دو دلیل رخ می‌دهد:
- کش: مرورگر یا افزونه‌ی کش، نسخه‌ی قدیمی را نشان می‌دهد. راه‌حل: پاک‌سازی کش در همه‌ی لایه‌ها.
- پردازش محتوا در فرانت‌اند: بعضی قالب‌ها، تابع
the_content()را برای پردازش شورتکدها صدا نمی‌زنند و به‌جای آن، محتوای خام را چاپ می‌کنند. این اتفاق، در قالب‌های غیراستاندارد بیشتر دیده می‌شود.
موضوع تشخیص قالب استاندارد، به‌ویژه در این سناریو، اهمیت جدی دارد. راهنمای تشخیص قالب استاندارد وردپرس معیارهای دقیقی برای این کار دارد؛ اگر قالبتان یکی از نشانه‌های قالب غیراستاندارد را داشته باشد، این احتمال جدی می‌شود.
سناریوی پنجم: شورت‌کد بعد از تغییر قالب از کار افتاده
یکی از رایج‌ترین زمان‌هایی که خطای شورت‌کد ظاهر می‌شود، بعد از تغییر قالب است. این اتفاق، دو ریشه‌ی متفاوت دارد:
- قالب قبلی، یک شورت‌کد اختصاصی ثبت می‌کرد: بعضی قالب‌ها، شورت‌کدهای اختصاصی خودشان را ثبت می‌کنند (مثلاً برای دکمه، جدول، یا بخش‌بندی). وقتی قالب را عوض می‌کنید، آن شورتکدها ناشناس می‌شوند و به‌عنوان متن خام نمایش داده می‌شوند.
- قالب جدید، فیلتری روی محتوا نصب می‌کند: بعضی قالب‌های تخصصی، فیلتری روی
the_contentنصب می‌کنند که پردازش شورتکدها را تحت تأثیر قرار می‌دهد.
این وضعیت، نمونه‌ی کلاسیکی از هزینه‌ی پنهان قالب‌های پُرامکانات است. قالب‌های چندمنظوره که برای هر بخش، یک شورت‌کد اختصاصی ثبت می‌کنند، روز تغییر قالب، کاربر را با ده‌ها براکت خام روی صفحه رها می‌کنند. همین موضوع را در تغییر امن قالب وردپرس به‌عنوان یکی از سه دام اصلی تغییر قالب مطرح کرده‌ام.
رفع: اگر بعد از تغییر قالب، شورت‌کدهای اختصاصی قالب قبلی از کار افتادند، دو مسیر دارید. اول، شورت‌کدهای معادل در قالب جدید را پیدا کنید و جایگزین کنید — که در سایت‌های بزرگ، کار دشواری است. دوم، شورت‌کدهای قدیمی را در یک افزونه‌ی کوچک یا چایلد‌تم بازسازی کنید تا همچنان کار کنند. تجربه‌ام این است که روش دوم، اگرچه کدنویسی می‌خواهد، در بلندمدت پایدارتر است. اصول کد سفارشی را در توسعه وردپرس چیست و از کجا شروع کنیم به تفصیل باز کرده‌ام.
سناریوی ششم: شورت‌کد بعد از به‌روزرسانی افزونه خراب شده
دومین زمان رایج ظهور این خطا، بعد از به‌روزرسانی افزونه‌ی ثبت‌کننده است. سه سناریوی متفاوت در این دسته وجود دارد:
- تغییر نام شورت‌کد: سازنده، به‌دلایلی، نام شورت‌کد را تغییر می‌دهد. نسخه‌ی جدید نام جدید را می‌شناسد، اما نام قدیمی را ناشناس می‌بیند.
- تغییر ساختار پارامترها: بعضی به‌روزرسانی‌ها، ساختار پارامترها را تغییر می‌دهند. شورت‌کد قدیمی ممکن است کار کند اما خروجی اشتباه بدهد.
- باگ در نسخه‌ی جدید: گاهی خود به‌روزرسانی، یک باگ در پردازش شورت‌کد ایجاد می‌کند. این اتفاق، در افزونه‌های کم‌کیفیت بیشتر دیده می‌شود.
رفع: ابتدا چنج‌لاگ (changelog) افزونه را بخوانید تا تغییرات را ببینید. اگر تغییر نام یا ساختار پارامتر بوده، شورتکدها را به‌روزرسانی کنید. اگر باگ است، به نسخه‌ی قبلی برگردید — با بکاپ گرفتن از فایل‌ها و دیتابیس. پیش از هر بازگشتی، مطمئن شوید که بکاپی تست‌شده دارید؛ راهنمای اصولی در چگونه از سایت وردپرسی بکاپ بگیریم.
سناریوی هفتم: شورت‌کد تو‌در‌تو کار نمی‌کند
در وردپرس، بعضی شورتکدها می‌توانند درون شورت‌کدهای دیگر قرار بگیرند. مثلاً یک شورت‌کد ستون که درونش یک شورت‌کد فرم قرار دارد. این قابلیت، به‌طور پیش‌فرض فعال نیست و باید توسط تابع پردازش پشتیبانی شود. اگر نه، شورت‌کد درونی به‌عنوان متن خام نمایش داده می‌شود.
این وضعیت، به‌ویژه در سایت‌های آموزشی و فروشگاهی که از شورت‌کدهای چیدمانی زیاد استفاده می‌کنند، رایج است. تشخیص: شورت‌کد بیرونی را حذف کنید و شورت‌کد درونی را به‌تنهایی امتحان کنید. اگر درونی به‌تنهایی کار کرد اما در ترکیب نه، مسئله در پشتیبانی از تو‌در‌تو است.
رفع: اگر خودتان شورت‌کد را ساخته‌اید، از تابع do_shortcode() در تابع پردازش استفاده کنید. اگر از افزونه‌ی شخص‌ثالث می‌آید، به مستندات آن مراجعه کنید یا با توسعه‌دهنده تماس بگیرید. جزئیات فنی این موضوع را در ساخت شورت‌کد با کدنویسی وردپرس باز کرده‌ام.
سناریوی هشتم: شورت‌کد در صفحه‌ساز کار نمی‌کند
اگر از یک صفحه‌ساز مثل Elementor، Divi یا WPBakery استفاده می‌کنید، شورتکدها در محیط صفحه‌ساز رفتار متفاوتی دارند. سه سناریوی رایج:
- شورت‌کد به‌عنوان متن خام در ویجت متنی: بعضی صفحه‌سازها، ویجت متنی را به‌شکل متفاوتی پردازش می‌کنند. راه‌حل: از ویجت مخصوص شورت‌کد استفاده کنید.
- شورت‌کد درون یک ویجت صفحه‌ساز، نیاز به تابع پردازش جداگانه دارد: بعضی صفحه‌سازها، برای پردازش شورتکدها، به تنظیمات خاصی نیاز دارند.
- شورت‌کد در پیش‌نمایش کار می‌کند اما در خروجی نهایی نه: این حالت، معمولاً به‌خاطر تفاوت پردازش محتوا در محیط ویرایش و فرانت‌اند است.
در تجربه‌ی خودم، صفحه‌سازها بیشترین دردسر را در این حوزه ایجاد می‌کنند؛ چون بین محتوای خام و خروجی نهایی، یک لایه‌ی اضافه‌ی رندر وجود دارد که خودش ممکن است شورت‌کد را پردازش کند یا نکند. برای اینکه انتخاب آگاهانه‌ای در این زمینه داشته باشید، مقایسه‌ی دقیق در Hello Elementor در برابر Neve و تحلیل کامل قالب‌های صفحه‌سازمحور در قالب چندمنظوره وردپرس چیست آمده است.
سناریوی نهم: شورت‌کد در ابزارک یا منو
به‌طور پیش‌فرض، وردپرس شورتکدها را فقط در محتوای نوشته‌ها و برگه‌ها پردازش می‌کند. اگر شورت‌کدی را در ابزارک یا منو بگذارید، ممکن است به‌عنوان متن خام نمایش داده شود. سه راه برای رفع این محدودیت وجود دارد:
- استفاده از ابزارک متنی که شورت‌کد را پردازش می‌کند: بعضی قالب‌ها، ابزارک متنی مخصوصی دارند که شورت‌کد را پردازش می‌کند.
- افزودن یک اسنیپت به
functions.phpچایلد‌تم: با فیلترwidget_text، می‌توان پردازش شورت‌کد را در ابزارک‌ها فعال کرد. - استفاده از یک افزونه‌ی سبک: افزونه‌هایی هستند که این قابلیت را اضافه می‌کنند.
موضوع مشابهی برای منوها هم وجود دارد. اگر شورت‌کد در منو قرار می‌دهید، احتمالاً به یک افزونه‌ی واسط نیاز دارید یا باید از یک روش جایگزین استفاده کنید. راهنمای کلی افزودن کد سفارشی به وردپرس، در چگونه کد سفارشی به وردپرس اضافه کنیم به تفصیل آمده است.
سناریوی دهم: شورت‌کد در ویرایشگر بلوکی
با ظهور ویرایشگر بلوکی (گوتنبرگ)، شورتکدها همچنان کار می‌کنند اما با محدودیت‌های جدید. سه سناریوی رایج در این حوزه:
- بلوک شورت‌کد مخصوص: گوتنبرگ یک بلوک به نام «شورت‌کد» دارد که برای این کار طراحی شده. اگر شورت‌کد را در بلوک «متن» بگذارید، ممکن است پردازش نشود.
- بلوک‌های داینامیک: بعضی افزونه‌ها، بلوک اختصاصی خودشان را ارائه می‌دهند که جایگزین شورت‌کد است. در این حالت، بهتر است از بلوک استفاده کنید نه شورت‌کد.
- تنظیمات سئو: بعضی افزونه‌های سئو، شورتکدها را در خروجی متا تگ حذف می‌کنند. اگر شورت‌کد شما متن مهمی تولید می‌کند، این موضوع را جدی بگیرید — چرا که توضیحات متا با متن خام شورت‌کد، کیفیت پایین‌تری برای سئو خواهد داشت. موضوع مشابه در سئو داخلی چیست و چه تاثیری دارد مطرح شده است.
روش گام‌به‌گام تشخیص
ترتیبی که در پروژه‌های خودم طی می‌کنم، از سریع‌ترین به دقیق‌ترین است:
- شورت‌کد را در یک نوشته‌ی تازه امتحان کنید. اگر در نوشته‌ی تازه کار می‌کند، مسئله در محتوای قدیمی است، نه در افزونه.
- کش را پاک کنید. مرورگر، افزونه‌ی کش، و CDN — هر سه را. راهنمای دقیق در بهترین افزونه‌های کش وردپرس.
- افزونه‌های فعال را بررسی کنید. مطمئن شوید افزونه‌ی ثبت‌کننده‌ی شورت‌کد فعال است.
- نام شورت‌کد را در مستندات بررسی کنید. شاید نام تغییر کرده یا پارامتری اشتباه نوشته شده.
- قالب را به پیش‌فرض تغییر دهید. اگر با تغییر قالب، شورت‌کد کار کرد، مسئله در قالب است.
- افزونه‌ها را به روش نیمه‌ای غیرفعال کنید. اگر مشکل حل شد، مقصر پیدا می‌شود.
- لاگ خطا را فعال کنید. با WP_DEBUG، خطاهای پنهان آشکار می‌شوند.
برای فعال‌سازی لاگ، پیش از خط /* That's all, stop editing! */ در wp-config.php اضافه کنید:
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );بعد از عیب‌یابی، WP_DEBUG را خاموش کنید. اگر با خطاهای دیگری هم روبه‌رو هستید، دو مقاله‌ی خطای ۵۰۰ وردپرس چیست و چگونه رفع می‌شود و رفع خطای سفید شدن صفحه وردپرس می‌توانند در همین مسیر کمک کنند.
رفع امن و راستی‌آزمایی
بعد از رفع، سه لایه راستی‌آزمایی انجام دهید تا مطمئن شوید مسئله در ریشه حل شده و برنمی‌گردد:
- تست در یک نوشته‌ی تازه: شورت‌کد را در یک نوشته‌ی جدید امتحان کنید و مطمئن شوید خروجی درست دارد.
- تست در نوشته‌ی اصلی: به همان نوشته‌ای که مشکل داشت برگردید و بازبینی کنید.
- تست در دو مرورگر: از یک مرورگر دیگر هم بررسی کنید تا مطمئن شوید مسئله مختص مرورگر خاصی نیست.
یک نکتهی ظریف: اگر شورت‌کد شما محتوای مهمی تولید می‌کند (مثلاً یک فرم تماس یا یک جدول قیمت)، بعد از رفع، چند روز پایش کنید تا مطمئن شوید که همچنان کار می‌کند. بعضی از مشکلات این حوزه، فقط در شرایط خاص (مثلاً با نقش کاربری متفاوت) ظاهر می‌شوند.
اشتباهات رایج در مواجهه با این خطا
| اشتباه | پیامد | روش درست |
|---|---|---|
| حذف و نصب مجدد افزونه بدون بررسی | از دست دادن تنظیمات و داده‌ها | بررسی لایه‌ای، سپس اقدام هدفمند |
| تغییر نام شورت‌کد بدون بررسی مستندات | خرابی بیشتر و سردرگمی | مطالعه‌ی چنج‌لاگ و مستندات افزونه |
| ویرایش قالب والد به‌جای چایلد‌تم | از دست رفتن تغییرات پس از آپدیت | استفاده از چایلد‌تم |
| نادیده گرفتن کش | تصور غلط از باقی‌بودن خطا | پاک‌سازی کش قبل از تست |
| نصب چند افزونه‌ی شورت‌کد هم‌زمان | تعارض و رفتار غیرقابل پیش‌بینی | یک افزونه‌ی ثبت‌کننده در هر زمان |
یک اشتباه ظریف که در دیدگاه‌ها زیاد می‌بینم: کاربران با دیدن شورت‌کد به‌صورت متن خام، فوراً فرض می‌کنند که افزونه خراب شده و آن را حذف می‌کنند. اما در بیش از نیمی از موارد، افزونه سالم است و مسئله در جای اشتباه شورت‌کد یا تنظیمات نادرست آن است. پیش از حذف، اول تشخیص دهید که مسئله واقعاً کجاست.
پیشگیری بلندمدت
پنج عادتی که در پروژه‌های خودم، نرخ این خطا را به کمترین حد رسانده است:
- مستندسازی شورتکدها: یک فایل کوچک داشته باشید که در آن، هر شورت‌کد و افزونه‌ی ثبت‌کننده‌اش ثبت شده باشد. اگر روزی افزونه‌ای حذف شد، بدانید کدام شورتکدها تحت تأثیر قرار می‌گیرند.
- پیش از تغییر قالب، شورت‌کدهای اختصاصی قالب قبلی را بررسی کنید: این یک گام کوچک است که در روز تغییر قالب، از ساعت‌ها سردرگمی جلوگیری می‌کند.
- پیش از به‌روزرسانی افزونه‌ها، بکاپ بگیرید: اگر به‌روزرسانی مشکل ایجاد کرد، بازگشت سریع ممکن است. راهنمای بکاپ در چگونه از سایت وردپرسی بکاپ بگیریم.
- افزونه‌های کم‌کیفیت را حذف کنید: افزونه‌هایی که شورت‌کدهای متعدد ثبت می‌کنند و رفتارشان شفاف نیست، معمولاً منبع دردسر هستند. فهرست افزونه‌های ضروری وردپرس نقطه‌ی شروع آگاهانه است.
- از صفحه‌سازها در سطح کنترل‌شده استفاده کنید: صفحه‌سازها ابزار قدرتمندی هستند، اما هر کدام یک لایه‌ی اضافه برای پردازش شورت‌کد اضافه می‌کنند. اگر از صفحه‌ساز استفاده می‌کنید، از ابتدا رفتار شورتکدها را تست کنید.
و یک عادت عملی که در پروژه‌های خودم پیاده کرده‌ام: هر ماه، یک نوشته‌ی تستی بسازید که در آن، همه‌ی شورت‌کدهای مهم سایت را در کنار هم قرار دهید. اگر یکی از آن‌ها کار نمی‌کند، همان لحظه متوجه می‌شوید، نه وقتی که مشتری از طریق تماس تلفنی خبر دهد. این رویکرد ساده، بارها از فاجعه‌های آینده جلوگیری کرده است. برای پایش کلی سلامت سایت، راهنمای راهنمای جامع رفع خطاهای رایج وردپرس دید جامع‌تری به شما می‌دهد.
نگاه مهندسی به شورت‌کد به‌عنوان یک قرارداد نرم
از منظر کسی که وردپرس را به‌عنوان یک پلتفرم تولیدی می‌بیند، شورت‌کد نمونه‌ای از یک قرارداد نرم است — یعنی توافقی بین دو بخش سیستم که هیچ‌کدام اجبار قانونی برای اجرای آن ندارد. سه تفکیک در این نگاه، به تشخیص و پیشگیری کمک می‌کند:
یک — شورت‌کد، محتوا را به کد گره می‌زند. در معماری بالغ، محتوا باید مستقل از هر لایه‌ی فنی باشد. اما شورت‌کد، محتوا را به یک افزونه یا قالب خاص گره می‌زند. یعنی روزی که آن افزونه حذف شود، محتوای شما پر از براکت‌های ناشناس می‌شود. در پروژه‌های خودم، هرگاه مجبورم به شورت‌کد وابسته باشم، از همان روز اول یک برنامه‌ی خروج دارم: یعنی می‌دانم اگر فردا آن افزونه را حذف کردم، چطور می‌توانم شورتکدها را با یک راه‌حل جایگزین بازسازی کنم. این نوع تفکر، در معماری سیستم‌های بلندمدت ضروری است. برای درک نقش قالب‌ها در این نوع وابستگی، مقاله‌ی قالب وردپرس چیست و چگونه انتخاب کنیم نقطه‌ی شروع مناسبی است.
دو — شورت‌کد، سطح حمله را افزایش می‌دهد. هر شورت‌کد یک نقطه‌ی پردازش ورودی است. اگر افزونه‌ای شورت‌کدش را بدون اعتبارسنجی پارامترها پردازش کند، می‌تواند یک نقطه‌ی آسیب‌پذیری باشد. در سایت‌های حساس، من همیشه تعداد شورت‌کدهای فعال را محدود نگه می‌دارم و هر شورت‌کد را از نظر امنیتی بررسی می‌کنم. این رویکرد، در بلندمدت، سطح حمله‌ی سایت را به‌شکل محسوسی کاهش می‌دهد. راهنمای امنیت مرتبط با این حوزه در بهترین افزونه‌های امنیتی وردپرس آمده است.
سه — شورت‌کد، از نظر عملکردی هزینه دارد. هر شورت‌کد، در هر نمایش صفحه، اجرا می‌شود. اگر یک نوشته، ده شورت‌کد داشته باشد، وردپرس ده بار تابع پردازش را اجرا می‌کند. اگر آن شورتکدها کوئری دیتابیس بزنند یا محاسبات سنگین انجام دهند، هزینه‌ی عملکردی به‌شکل نمایی رشد می‌کند. در پروژه‌های پُرترافیک، این نوع وابستگی می‌تواند به‌سرعت به یک مسئله‌ی جدی تبدیل شود. راه‌حل معماری، جداسازی محتوای پویا از محتوای استاتیک است: جاهایی که شورت‌کد لازم نیست، از آن استفاده نکنیم. اثر این نوع تصمیم‌ها را در افزایش سرعت وردپرس به تفصیل سنجیده‌ام.
از منظر انتزاعی‌تر، مسئله‌ی شورت‌کد یک نمونه‌ی کلاسیک از وابستگی نرم در سیستم‌هاست. برخلاف وابستگی سخت (که اگر نباشد، سیستم کاملاً از کار می‌افتد)، وابستگی نرم باعث می‌شود سیستم در ظاهر کار کند اما با کیفیت پایین‌تر. شورت‌کدی که از کار افتاده، در ظاهر یک براکت ساده روی صفحه است؛ اما در واقع، نشانه‌ی یک گره‌ی شکسته در زنجیره‌ی معماری محتواست. سایت‌هایی که در بلندمدت پایداری محتوایی دارند، معمولاً از یک الگوی مشخص پیروی می‌کنند: شورت‌کد فقط برای محتوای پویا، و محتوای ثابت بدون هیچ وابستگی به افزونه. اگر می‌خواهید از خطاهای آینده پیشگیری کنید، اولین قدم ساده‌ای که توصیه می‌کنم: یک فهرست از شورت‌کدهای فعال سایت‌تان بسازید و کنار هرکدام بنویسید که چه افزونه‌ای آن را ثبت می‌کند و اگر آن افزونه حذف شود، چه چیزی از دست می‌رود. همین یک فهرست کوچک، در تصمیم‌های بلندمدت، تفاوت بین معماری پایدار و معماری شکننده را می‌سازد.
شورت‌کدی که کار نمی‌کند، فقط یک براکت روی صفحه نیست؛ یک گره‌ی پنهان در معماری محتوای سایت است. برای حل، باید همان گره را در نقشه‌ی کلی ببینید.
سخن پایانی
خطای کار نکردن شورت‌کد در وردپرس، از آن دسته خطاهایی است که در ظاهر هیچ خطایی نشان نمی‌دهد اما می‌تواند بخشی از محتوای سایت شما را از کار بیندازد. تفاوت بین یک عیب‌یابی سریع و یک سردرگمی طولانی، نه در دانش فنی، که در داشتن یک نقشه‌ی لایه‌ای است. ده سناریویی که در این مقاله باز کردم — از نمایش متن خام تا ناپدید شدن، از تغییر قالب تا تعارض افزونه‌ها — می‌توانند بیش از نود درصد پرونده‌ها را تا گام سوم حل کنند.
تجربه‌ام این است که در این خطا، «سادگی» فریبنده است. کاربران معمولاً به‌دنبال راه‌حل‌های پیچیده می‌روند، درحالی‌که مسئله در بیشتر مواقع، به یک تنظیم ساده یا یک جای اشتباه در محتوا برمی‌گردد. آرام باشید، لایه به لایه بررسی کنید، و در صورت لزوم از بکاپ استفاده کنید.
اگر این خطا را روی سایت خودتان دیده‌اید و یکی از سناریوهای این مقاله مقصر بوده، خوشحال می‌شوم در دیدگاه‌ها بخوانم. به‌ویژه اگر سناریوی نادری کشف کرده‌اید — مثلاً یک شورت‌کد خاص با یک رفتار غیرمعمول، یا یک تنظیم قالب که کمتر دیده می‌شود — همان جزئیات برای خواننده‌ی بعدی که در همان موقعیت گرفتار است، از هر راهنمای عمومی ارزشمندتر است. اگر هم پس از خواندن این مقاله به این نتیجه رسیدید که زیرساخت فعلی سایت شما سقف این نوع مسائل است، دو مقاله‌ی راهنمای انتخاب هاست و تأثیر هاست بر سرعت سایت مسیر بعدی شما هستند. 🧩
نویسنده در وردپرس کار.