چرا جاوااسکریپت قالب وردپرس بارگذاری نمی‌شود و چگونه آن را اصولی برطرف کنیم؟

عدم بارگذاری JavaScript قالب دقیقاً چیست؟

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

از منظر معماری وردپرس، اسکریپت‌های قالب باید از طریق سیستم enqueue بارگذاری شوند، نه با تگ مستقیم <script> در فایل header.php یا footer.php. دلیل این است که وردپرس یک چرخه دقیق برای مدیریت وابستگی‌ها دارد: اگر اسکریپت شما به jQuery (کتابخانه معروف جاوااسکریپت) وابسته است، می‌توانید این وابستگی را در همان wp_enqueue_script اعلام کنید و وردپرس به‌طور خودکار ترتیب را رعایت می‌کند. اما اگر تگ دستی بگذارید، ترتیب دستی و شکننده می‌شود. برای درک جایگاه این مکانیزم در کلیت قالب، مقاله قالب وردپرس چیست و چگونه انتخاب کنیم نقطه شروع خوبی است.

یک سوءبرداشت رایج: بسیاری از توسعه‌دهندگان تازه‌کار تصور می‌کنند که «قرار دادن فایل در پوشه js قالب» به‌معنی بارگذاری خودکار آن است. این‌طور نیست. وردپرس هیچ فایل جاوااسکریپتی را به‌طور خودکار بارگذاری نمی‌کند — مگر اسکریپت‌های هسته. هر اسکریپت قالب، از جمله اسکریپت‌های افزونه، باید صریحاً enqueue شود. برای مطالعه بیشتر درباره مفهوم JavaScript در وب، ویکی‌پدیا مرجع خوبی است.

جاوااسکریپت قالب اگر enqueue نشود، وجودش مثل کتابی است که در قفسه نشسته و هیچ‌کس نمی‌داند آنجاست.

هفت ریشه اصلی این خطا

در تجربه‌ام، این مشکل تقریباً همیشه یکی از هفت ریشه زیر را دارد. هر کدام امضای مشخص خودش را در کنسول یا Network دارد:

۱. فراموشی enqueue در functions.php

شایع‌ترین علت. فایل جاوااسکریپت در پوشه قالب موجود است، اما هیچ‌جا wp_enqueue_script فراخوانی نشده. به همین دلیل مرورگر هیچ درخواستی برای فایل ارسال نمی‌کند و در تب Network اثری از آن نیست.

۲. آدرس نادرست در wp_enqueue_script

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

۳. اجرای نادرست هوک

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

۴. تعارض با افزونه بهینه‌سازی یا کش

افزونه‌های بهینه‌ساز مثل Autoptimize، WP Rocket، و LiteSpeed Cache، با ترکیب و ادغام فایل‌های JS باعث می‌شوند که بعضی از فایل‌ها در مسیر جدید بارگذاری نشوند. این حالت معمولاً بعد از نصب یا تنظیم این افزونه‌ها ظاهر می‌شود و به‌سادگی نادیده گرفته می‌شود.

۵. خطای سینتکسی در فایل JavaScript

اگر فایل .js خطای سینتکسی داشته باشد، مرورگر آن را دریافت می‌کند اما در اجرا با خطا مواجه می‌شود. تب Console مرورگر در این حالت یک پیام صریح مثل Uncaught SyntaxError نشان می‌دهد. برای مطالعه دقیق‌تر درباره این خطاها، مقاله خطای SyntaxError در جاوااسکریپت را توصیه می‌کنم.

۶. خطای CORS (Cross-Origin Resource Sharing) در فایل‌های خارجی

اگر فایل JS از یک CDN خارجی بارگذاری می‌شود و هدرهای CORS به‌درستی تنظیم نشده باشند، مرورگر اجرای اسکریپت را رد می‌کند. این حالت در قالب‌هایی که از کتابخانه‌های CDN محبوب مثل Google Fonts یا jsDelivr استفاده می‌کنند، شایع است.

۷. اجرای زودهنگام قبل از آماده شدن DOM

اگر کد JS شما به عناصر DOM وابسته است اما قبل از آن‌ها اجرا می‌شود، هیچ خطایی در کنسول نمی‌بینید، اما رفتار مورد نظر رخ نمی‌دهد. این حالت در قالب‌های قدیمی که اسکریپت را در <head> با تگ مستقیم بارگذاری می‌کنند، شایع است.

نشانه‌ها و علائم تشخیص در کنسول و Network

قبل از اینکه به سراغ کد بروید، باید بدانید از کدام زاویه به مشکل نگاه کنید. علائم این خطا در سه لایه ظاهر می‌شوند:

• در لایه بصری: اسلایدر کار نمی‌کند، منوی موبایل باز نمی‌شود، تب‌ها عوض نمی‌شوند، و انیمیشن‌های اسکرول به‌اجرا در نمی‌آیند.
• در تب Network مرورگر: فایل JS با خطای ۴۰۴ یا ۵۰۰ نشان داده می‌شود، یا اصلاً در فهرست درخواست‌ها نیست.
• در تب Console مرورگر: پیام‌هایی مثل Uncaught SyntaxError، Uncaught ReferenceError: $ is not defined، یا Uncaught TypeError: Cannot read property of null.

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

تشخیص دقیق: پروتکل گام‌به‌گام

برای رسیدن به ریشه مشکل، این پروتکل را در تجربه‌ام مفید یافته‌ام:

گام اول: بررسی تب Network مرورگر

مرورگر را باز کنید، F12 بزنید، و به تب Network بروید. سپس صفحه را رفرش کنید و در فیلتر، گزینه JS را انتخاب کنید. اگر فایل مورد نظر شما در این فهرست نیست، یعنی اصلاً enqueue نشده — یعنی مرورگر حتی درخواستی ارسال نکرده. این شایع‌ترین حالت است و ریشه در عدم فراخوانی wp_enqueue_script دارد.

اگر فایل در فهرست هست اما با کد وضعیت قرمز (۴۰۴ یا ۵۰۰)، یعنی مسیر نادرست است یا سرور نمی‌تواند فایل را سرو کند. اگر کد ۲۰۰ سبز دارد اما باز هم اسلایدر کار نمی‌کند، یعنی فایل رسیده اما اجرا نشده — اینجا باید به سراغ تب Console بروید.

گام دوم: بررسی تب Console

به تب Console بروید. اگر خطای Uncaught ReferenceError: $ is not defined دیدید، یعنی اسکریپت شما به jQuery وابسته است اما jQuery بارگذاری نشده. این حالت در قالب‌هایی که jquery را در وابستگی‌های wp_enqueue_script اعلام نکرده‌اند، شایع است. راه‌حل در بخش الگوهای enqueue می‌آید.

اگر خطای Uncaught SyntaxError دیدید، یک خطای نوشتاری در فایل JS وجود دارد. اگر خطای Cannot read property of null دیدید، یعنی کد JS تلاش کرده به یک عنصر DOM دسترسی پیدا کند که وجود ندارد یا هنوز ایجاد نشده. راهنمای کامل این خطاها را در خطای Cannot read property of undefined آورده‌ام.

گام سوم: بررسی View Source صفحه

روی صفحه راست‌کلیک کنید و View Page Source را بزنید. در HTML منبع، به دنبال تگ <script بگردید. اگر فایل JS شما در این فهرست نیست، یعنی enqueue نشده. اگر هست اما با پارامترهای عجیب (مثلاً ?ver=1.0.0&defer)، یعنی یک افزونه بهینه‌سازی آن را تغییر داده است. اگر مسیر به‌شکل عجیب و با آدرس CDN ترکیب شده، یعنی یک افزونه کش آن را بازنویسی کرده است.

گام چهارم: بررسی functions.php

فایل functions.php قالب را باز کنید و بررسی کنید که آیا wp_enqueue_script وجود دارد یا نه. برای قالب‌های حرفه‌ای، این تابع معمولاً در یک تابع به نام theme_scripts یا my_theme_enqueue_scripts فراخوانی می‌شود و به هوک wp_enqueue_scripts وصل می‌گردد. برای مطالعه بیشتر درباره روش صحیح، مقاله افزودن کد سفارشی به وردپرس را ببینید.

گام پنجم: تست با افزونه بهینه‌سازی غیرفعال

اگر از افزونه‌های بهینه‌سازی مثل Autoptimize یا WP Rocket استفاده می‌کنید، همه آن‌ها را یک به یک غیرفعال کنید و صفحه را رفرش کنید. اگر مشکل حل شد، مقصر همان افزونه است و باید تنظیماتش را بازبینی کنید. برای مطالعه بیشتر درباره تنظیم اصولی این افزونه‌ها، مقاله بهترین افزونه‌های کش وردپرس را توصیه می‌کنم.

گام ششم: بررسی از منظر سمت سرور

اگر با SSH کار می‌کنید، می‌توانید مستقیماً بررسی کنید که سرور فایل را برمی‌گرداند یا نه:

curl -I https://yourdomain.com/wp-content/themes/your-theme/js/theme.js

اگر پاسخ با کد 200 OK بود، فایل روی سرور موجود و قابل دسترسی است. اگر 404 Not Found بود، مسیر غلط است. اگر 403 Forbidden بود، مجوزهای فایل مشکل دارند.

تفاوت با خطاهای مشابه

این جدول به شما کمک می‌کند سریع تشخیص دهید کدام خطا را در دست دارید:

نکته ظریف: خطای عدم بارگذاری استایل‌شیت (CSS) و خطای عدم بارگذاری اسکریپت (JS) اغلب با هم رخ می‌دهند، چون هر دو از یک مکانیزم مشترک در functions.php استفاده می‌کنند. اگر یکی از آن‌ها کار نمی‌کند، احتمالاً ساختار کلی functions.php مشکل دارد. برای مطالعه موردی مشابه، مقاله چگونه خطای قالب وردپرس را عیب‌یابی کنیم را ببینید.

راه‌حل‌های عملی برای هر ریشه

حالا که تشخیص دادید، وقت درمان است. راه‌حل‌ها را بر اساس ریشه مشکل دسته‌بندی کرده‌ام:

راه‌حل ریشه اول: نوشتن enqueue صحیح

function my_theme_enqueue_scripts() {
    wp_enqueue_script(
        'my-theme-main',
        get_template_directory_uri() . '/js/theme.js',
        array( 'jquery' ),
        '1.0.0',
        true
    );
}
add_action( 'wp_enqueue_scripts', 'my_theme_enqueue_scripts' );

سه نکته کلیدی در این کد:

1. پارامتر array( 'jquery' ) اعلام می‌کند که اسکریپت به jQuery وابسته است — وردپرس به‌طور خودکار jQuery را قبل از آن بارگذاری می‌کند.
2. پارامتر true در انتها یعنی اسکریپت در فوتر بارگذاری شود، بعد از بسته شدن </body>. این کار زمان رندر اولیه را بهبود می‌دهد.
3. استفاده از get_template_directory_uri() به‌جای آدرس دستی، مسیر را همیشه نسبت به ریشه قالب محاسبه می‌کند.

راه‌حل ریشه دوم: اصلاح آدرس در چایلد تم

در قالب چایلد، باید تصمیم بگیرید که فایل JS از کدام پوشه بارگذاری شود. اگر فایل شما در چایلد است، از get_stylesheet_directory_uri() استفاده کنید؛ اگر در والد است، از get_template_directory_uri(). اشتباه رایج در اینجا، استفاده از تابع اشتباه است که منجر به خطای ۴۰۴ می‌شود.

wp_enqueue_script(
    'child-theme-script',
    get_stylesheet_directory_uri() . '/js/child.js',
    array( 'jquery' ),
    '1.0.0',
    true
);

راه‌حل ریشه سوم: اتصال به هوک صحیح

همیشه از wp_enqueue_scripts استفاده کنید، نه init یا wp_head. اگر با هوک‌ها آشنایی ندارید، مقاله هوک‌های وردپرس چیستند و چگونه کار می‌کنند را ببینید.

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

هر افزونه بهینه‌سازی، یک بخش «Exclude» یا «Exception» دارد که می‌توانید فایل‌های JS قالب خود را در آن اضافه کنید. این کار از ترکیب آن‌ها با فایل‌های دیگر و به‌هم‌ریختگی ترتیب جلوگیری می‌کند. برای مطالعه دقیق‌تر درباره این تنظیمات، مقاله افزونه‌های وردپرس چگونه روی سرعت سایت اثر می‌گذارند را توصیه می‌کنم.

راه‌حل ریشه پنجم: رفع خطای سینتکسی

خطای سینتکسی در JS معمولاً از یک کاما اضافی، یک پرانتز بسته‌نشده، یا یک نقل‌قول نادرست می‌آید. ابزارهای lint مثل ESLint در VS Code یا ابزار آنلاین jshint.com این خطاها را سریع پیدا می‌کنند. برای مطالعه درباره محیط توسعه، مقاله نقد نرم‌افزار Visual Studio Code را ببینید.

راه‌حل ریشه ششم: تنظیم CORS

اگر فایل JS از یک CDN خارجی بارگذاری می‌شود، سرور CDN باید هدر Access-Control-Allow-Origin را ارسال کند. اگر سرور شما از PHP استفاده می‌کند، می‌توانید این هدر را در فایل functions.php اضافه کنید — هرچند راه‌حل اصلی، استفاده از CDNهایی است که این هدر را به‌طور پیش‌فرض ارسال می‌کنند.

راه‌حل ریشه هفتم: استفاده از jQuery ready

اگر اسکریپت شما به DOM وابسته است، کد را درون یک بلاک jQuery(document).ready() یا DOMContentLoaded قرار دهید:

jQuery(function($) {
    // کد شما اینجا اجرا می‌شود، بعد از آماده شدن DOM
    $('.slider').slick();
});

این الگو در ۹۰٪ موارد مشکل «کد اجرا می‌شود اما بی‌اثر است» را حل می‌کند.

الگوی صحیح enqueue اسکریپت در قالب

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

function my_theme_assets() {
    $version = wp_get_theme()->get( 'Version' );

    // استایل اصلی
    wp_enqueue_style(
        'my-theme-style',
        get_template_directory_uri() . '/style.css',
        array(),
        $version
    );

    // اسکریپت اصلی (در فوتر)
    wp_enqueue_script(
        'my-theme-main',
        get_template_directory_uri() . '/js/main.js',
        array( 'jquery' ),
        $version,
        true
    );

    // پاس دادن داده‌های PHP به JS (اختیاری)
    wp_localize_script( 'my-theme-main', 'myThemeData', array(
        'ajaxUrl' => admin_url( 'admin-ajax.php' ),
        'homeUrl' => home_url( '/' ),
        'nonce'   => wp_create_nonce( 'my_theme_nonce' ),
    ) );
}
add_action( 'wp_enqueue_scripts', 'my_theme_assets' );

سه نکته مهم در این الگو:

اول: استفاده از wp_get_theme()->get('Version') برای نسخه‌بندی خودکار. این کار باعث می‌شود که با هر آپدیت قالب، نسخه فایل JS در URL تغییر کند و کش مرورگر خودکار تازه شود. اگر این کار را نکنید، کاربران قدیمی با نسخه قدیمی اسکریپت گیر می‌کنند.

دوم: استفاده از wp_localize_script برای پاس دادن داده‌های PHP به JS. این تابع، یک آبجکت جاوااسکریپت ایجاد می‌کند که شامل URL آژاکس، nonce امنیتی و سایر داده‌های لازم است. برای مطالعه بیشتر درباره پیاده‌سازی امن AJAX، مقاله نوشتن کد PHP امن برای وردپرس را توصیه می‌کنم.

سوم: استفاده از wp_enqueue_scripts به‌عنوان هوک. این هوک در نسخه ۲.۸ وردپرس معرفی شد و از آن زمان استاندارد است. اگر از هوک‌های قدیمی مثل init یا template_redirect استفاده می‌کنید، احتمالاً در آینده با deprecation مواجه می‌شوید.

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

if ( is_page( 'contact' ) ) {
    wp_enqueue_script(
        'my-theme-contact',
        get_template_directory_uri() . '/js/contact.js',
        array(),
        $version,
        true
    );
}

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

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

استراتژی‌های پیشگیری

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

۱. همیشه در استجینگ تست کنید

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

۲. از یک الگوی ثابت برای enqueue استفاده کنید

یک فایل inc/enqueue.php در قالب خود بسازید و همه فراخوانی‌های wp_enqueue_script و wp_enqueue_style را در آن متمرکز کنید. این کار نگهداری و عیب‌یابی را ساده می‌کند.

۳. کش مرورگر را با نسخه‌بندی مدیریت کنید

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

۴. فایل JS را با ابزارهای lint بررسی کنید

قبل از هر انتشار، فایل JS خود را با ESLint یا ابزار آنلاین بسنجید. یک کاما اضافی، می‌تواند ساعت‌ها وقت عیب‌یابی بگیرد.

۵. مانیتورینگ خطاهای سمت کلاینت

اگر سایت شما ترافیک بالایی دارد، از ابزارهایی مثل Sentry یا LogRocket برای دریافت خودکار خطاهای JS استفاده کنید. این ابزارها خطاها را از مرورگر کاربران واقعی جمع‌آوری می‌کنند و به شما گزارش می‌دهند — همان اصلی که در رفع مشکلات سرعت سایت هم توضیح داده‌ام.

۶. سازگاری با قالب چایلد

اگر از قالب چایلد استفاده می‌کنید، همیشه بررسی کنید که functions.php چایلد، فایل‌های JS والد را بازنویسی نمی‌کند. برای مطالعه بیشتر، مقاله توسعه وردپرس با Child Theme را توصیه می‌کنم.

پرسش‌های پرتکرار درباره بارگذاری JavaScript قالب

چرا فایل JS قالب من در Network اصلاً نمایش داده نمی‌شود؟

این نشانه کلاسیک عدم enqueue است. یعنی مرورگر اصلاً درخواستی برای آن ارسال نکرده، چون در HTML صفحه هیچ تگی برای آن وجود ندارد. راه‌حل: بررسی کنید که wp_enqueue_script در functions.php فراخوانی شده و به هوک wp_enqueue_scripts وصل است.

چرا خطای ۴۰۴ برای فایل JS می‌گیرم؟

مشکل در آدرس است. اگر از get_template_directory_uri() استفاده می‌کنید، مطمئن شوید که فایل در پوشه قالب والد قرار دارد. اگر فایل در قالب چایلد است، از get_stylesheet_directory_uri() استفاده کنید. برای مطالعه دقیق‌تر، مقاله رفع خطای عدم بارگذاری استایل قالب را ببینید.

چرا خطای $ is not defined می‌گیرم؟

این خطا یعنی اسکریپت شما از jQuery استفاده می‌کند، اما jQuery قبل از آن بارگذاری نشده. راه‌حل: در wp_enqueue_script، پارامتر وابستگی را روی array( 'jquery' ) تنظیم کنید. وردپرس به‌طور خودکار jQuery را قبل از اسکریپت شما بارگذاری می‌کند.

آیا افزونه کش می‌تواند باعث عدم بارگذاری JS شود؟

بله. افزونه‌های بهینه‌سازی مثل Autoptimize، WP Rocket و LiteSpeed Cache، با ترکیب و ادغام فایل‌های JS باعث می‌شوند بعضی از فایل‌ها در مسیر جدید بارگذاری نشوند یا ترتیبشان به‌هم بریزد. راه‌حل: فایل JS قالب خود را در بخش Exclude اضافه کنید.

آیا می‌توانم بدون استفاده از wp_enqueue_script مستقیم تگ بگذارم؟

از نظر فنی بله، اما توصیه نمی‌شود. دلایل: ترتیب بارگذاری قابل‌کنترل نیست، وابستگی‌ها به‌درستی مدیریت نمی‌شوند، و در بازبینی قالب رد می‌شود. همیشه از wp_enqueue_script استفاده کنید.

تفاوت بارگذاری در header و footer چیست؟

اگر پارامتر آخر wp_enqueue_script را true بگذارید، اسکریپت در فوتر بارگذاری می‌شود (بعد از بسته شدن body). این کار زمان رندر اولیه صفحه را بهبود می‌دهد، چون مرورگر تا رسیدن به این اسکریپت منتظر نمی‌ماند. برای اسکریپت‌هایی که به DOM وابسته نیستند (مثل Analytics)، فوتر توصیه می‌شود.

چرا بعد از تغییر functions.php، تغییراتم اعمال نمی‌شود؟

احتمالاً کش. هم کش مرورگر، هم کش افزونه، هم کش سرور می‌توانند تغییرات را پنهان کنند. همیشه بعد از تغییر، یک بار با حالت incognito یا بعد از پاک کردن کش، تست کنید. راه‌حل کامل در تأثیر افزونه‌ها بر سرعت سایت توضیح داده شده است.

آیا استفاده از defer و async در wp_enqueue_script ممکن است؟

خیر، به‌طور مستقیم. وردپرس پارامتر defer/async را در wp_enqueue_script پشتیبانی نمی‌کند. برای افزودن این ویژگی‌ها، باید از هوک script_loader_tag استفاده کنید یا از یک افزونه بهینه‌سازی که این قابلیت را دارد.

کالبدشکافی فنی: چرخه بارگذاری اسکریپت در وردپرس

برای درک عمیق این مکانیزم، باید بدانید وردپرس چطور اسکریپت‌ها را مدیریت می‌کند. هسته وردپرس یک کلاس به نام WP_Scripts دارد که دفتر کل تمام اسکریپت‌هاست. هر wp_enqueue_script فراخوانی، به این کلاس یک رکورد اضافه می‌کند که شامل این اطلاعات است: handle، src، dependencies، version، in_footer.

پس از اینکه همه فراخوانی‌ها در هوک wp_enqueue_scripts انجام شد، هسته در ادامه چرخه رندر، این اسکریپت‌ها را به ترتیب وابستگی مرتب می‌کند. اگر اسکریپت A به B وابسته باشد، B اول بارگذاری می‌شود. اگر وابستگی حلقه‌ای باشد (A به B و B به A)، وردپرس یک هشدار در debug.log می‌دهد و اسکریپت‌ها را به ترتیب ثبت‌شان بارگذاری می‌کند.

در پایان، هسته در دو نقطه مشخص، تگ‌های <script> را رندر می‌کند: در wp_head برای اسکریپت‌هایی که in_footer آن‌ها false است، و در wp_footer برای اسکریپت‌هایی که in_footer آن‌ها true است. اگر هیچ‌کدام از این دو نقطه در قالب شما وجود نداشته باشد — یعنی اگر قالب، wp_head() یا wp_footer() را در فایل‌های خود فراخوانی نکند — اسکریپت‌ها هرگز در HTML ظاهر نمی‌شوند. این مشکل در قالب‌های سفارشی که خیلی مینیمال طراحی شده‌اند، بسیار شایع است.

نکته کمتر شناخته‌شده: اگر قالب شما در فایل header.php به‌جای wp_head() فقط یک تگ <head> خالی دارد، کل سیستم enqueue از کار می‌افتد — نه فقط برای JS، بلکه برای CSS و متادیتا. این موضوع در برخی از قالب‌های اولیه که توسعه‌دهنده از صفر همه‌چیز را نوشته، دیده می‌شود. برای مطالعه بیشتر درباره ساختار استاندارد قالب، مقاله ساختار فایل‌های یک قالب استاندارد وردپرس را توصیه می‌کنم.

یک نکته سوم: در حالت child theme، اگر functions.php فرزند، اسکریپت را با handle مشابه والد enqueue کند، در برخی موارد هسته آن را رد می‌کند چون handle تکراری است. برای جلوگیری از این مشکل، همیشه از handle اختصاصی برای چایلد تم استفاده کنید. این موضوع در پروژه‌های بزرگ، باعث می‌شود که اسکریپت چایلد تم به‌طور شفاف از والد جدا بماند. برای مطالعه بیشتر، مقاله کدنویسی اختصاصی برای قالب وردپرس را ببینید.

مطالعه موردی: احیای اسلایدر یک قالب شرکتی

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

علائم:

• اسلایدر بی‌حرکت باقی می‌ماند
• هیچ خطایی در Console مرورگر نمایش داده نمی‌شد
• در تب Network، فایل slider.js با کد ۲۰۰ بارگذاری می‌شد
• روی لوکال، همه‌چیز عالی بود

تشخیص:

با بررسی دقت، مشخص شد که روی سرور، یک افزونه بهینه‌سازی نصب شده که فایل‌های JS را با هم ترکیب می‌کند. فایل slider.js با فایل‌های دیگر ترکیب شده بود اما به‌خاطر ترتیب، بعد از فایل‌های دیگر قرار گرفته بود — و در همان لحظه، عنصر .slider در DOM وجود نداشت. اسلایدر سعی می‌کرد عنصر را پیدا کند، پیدا نمی‌کرد، و بی‌صدا از کار می‌افتاد.

درمان:

1. ابتدا فایل slider.js را از فهرست ترکیب افزونه بهینه‌سازی حذف کردم.
2. سپس با استفاده از wp_localize_script، وابستگی صریحی از slider.js به jQuery اضافه کردم.
3. در نهایت، کد اسلایدر را درون jQuery(document).ready() قرار دادم تا فقط بعد از آماده شدن DOM اجرا شود.

درس‌آموخته:

عدم بارگذاری JS همیشه به‌معنی «فایل بارگذاری نشده» نیست. گاهی فایل بارگذاری می‌شود اما به‌خاطر ترتیب اشتباه، در لحظه نامناسب اجرا می‌شود. راه‌حل اصولی، استفاده از jQuery(document).ready() در کد JS و اعلام صریح وابستگی‌ها در wp_enqueue_script است. برای مطالعه موردی مشابه، مقاله بهترین روش تست قالب وردپرس را ببینید.

وصیت‌نامه فنی: اسکریپتی که نمی‌رسد

عدم بارگذاری JavaScript قالب وردپرس، در نگاه اول یک خطای مبهم است، اما در واقع یک پیام دقیق است: چرخه enqueue در جایی قطع شده. سؤال درست این نیست «چرا اسلایدر کار نمی‌کند»، بلکه این است «چه چیزی در مسیر بارگذاری اسکریپت ناقص مانده».

از تجربه‌ام، پنج اصل عملی بیشترین بازدهی را داشته‌اند: اول، همیشه از wp_enqueue_script استفاده کنید، حتی برای یک اسکریپت کوچک. دوم، وابستگی‌ها را صریح اعلام کنید — به‌خصوص وابستگی به jQuery. سوم، همیشه پارامتر نسخه را پاس دهید تا کش مرورگر به‌درستی مدیریت شود. چهارم، کد JS را درون jQuery(document).ready() قرار دهید تا از وابستگی به DOM در امان باشد. پنجم، فایل JS قالب خود را در بخش Exclude افزونه‌های بهینه‌سازی اضافه کنید تا ترتیب اسکریپت‌ها به‌هم نریزد.

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

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