قطعه کد افزودن کد سفارشی به هدر وردپرس
قطعه کد افزودن کد سفارشی به هدر وردپرس چطور کار میکند؟ راهنمای عملی استفاده از هوک wp_head برای افزودن اسکریپت تحلیلی، متاتگ تأیید، کد رهگیری و استای
اولین باری که در یک پروژهٔ مشتری با نیاز «افزودن کد Google Analytics» روبهرو شدم، کار را ساده دیدم: فایل header.php قالب را باز کردم، کد را پیش از </head> گذاشتم و تمام. سه ماه بعد، قالب آپدیت امنیتی منتشر کرد و مشتری بدون اطلاع من آن را نصب کرد. سه روز بعد، گزارش تحلیلی صفر بود و معلوم شد کد رهگیری بهخاطر نبود در نسخهٔ جدید، ناپدید شده است. آن لحظه، به یک قاعدهٔ ساده در کارم رسیدم: هر کدی که با هدف «افزودن به هدر» نوشته میشود، باید در لایهای باشد که آپدیت قالب آن را پاک نکند. این مقاله، مسیر عملی همین موضوع را با هم مرور میکند: قطعه کد افزودن کد سفارشی به هدر وردپرس چیست، چطور با هوک رسمی wp_head انجام میشود، چه تفاوتی با ویرایش مستقیم فایل قالب دارد، و چه ملاحظات امنیتی و کارایی در این زمینه باید در نظر گرفته شود. اگر با مفهوم پایهٔ اسنیپت آشنا نیستید، پیش از ادامه قطعه کد وردپرس چیست و چگونه از آن استفاده کنیم نقطهٔ شروع مناسبتری است.
افزودن کد به هدر دقیقاً یعنی چه؟
در وردپرس، «هدر» به بخش بالای هر صفحهٔ HTML گفته میشود؛ همان بخشی که با تگ <head> شروع میشود و پیش از تگ <body> قرار میگیرد. محتوای این بخش، مستقیماً به کاربر نمایش داده نمیشود؛ ولی نقش تعیینکنندهای در رفتار مرورگر، موتورهای جستجو و ابزارهای رهگیری دارد. کدی که در هدر قرار میگیرد، معمولاً به یکی از این چهار دسته تعلق دارد:
- اسکریپتهای تحلیلی و رهگیری: Google Analytics، Google Tag Manager، Meta Pixel، Yandex Metrica.
- متاتگهای تأیید مالکیت: کدهای تأیید Google Search Console، Bing Webmaster، Pinterest.
- استایلها و فونتهای وب: لینک به فونتهای گوگل، استایلهای اختصاصی، قواعد اولیهٔ CSS.
- متاتگهای سئو و اشتراکگذاری: Open Graph، Twitter Card، canonical، و مشابهها.
این چهار دسته، در عمل، بیشترین کاربردهای افزودن کد به هدر را میسازند. سؤال اصلی این است که این کد را کجا قرار دهیم که هم کار کند، هم پاک نشود، و هم سایت را کند نکند. پاسخ این سؤال، در تفاوت بین دو مسیر اصلی خلاصه میشود: ویرایش مستقیم فایل header.php قالب، یا استفاده از هوک رسمی wp_head. در تجربهٔ من، تقریباً همیشه مسیر دوم انتخاب درستتری است. توضیح مبنای این انتخاب در تفاوت Action و Filter در وردپرس چیست با مثالهای ساده آمده است.
هدر سایت، عرشهٔ اطلاعات پنهان است. کاربر آن را نمیبیند، ولی موتور جستجو، مرورگر و ابزارهای رهگیری همه از آن میخوانند. هر خطی که در آن میگذارید، تا سالها بر رفتار سایت شما اثر میگذارد.
دو مسیر: ویرایش مستقیم قالب یا استفاده از هوک
برای افزودن کد به هدر، دو مسیر اصلی پیش روی شماست. مسیر اول، ویرایش مستقیم فایل header.php قالب است که در آن کد را مستقیماً پیش از </head> میگذارید. مسیر دوم، استفاده از هوک رسمی wp_head است که در فایل functions.php چایلد تم یا در یک افزونهٔ اختصاصی استفاده میشود. تفاوت این دو، در نگاه اول نامحسوس بهنظر میرسد؛ ولی در عمل، سه تفاوت اساسی دارند:
| معیار | ویرایش header.php | استفاده از wp_head |
|---|---|---|
| مقاومت در برابر آپدیت قالب | خیر؛ کد در آپدیت ناپدید میشود | بله؛ کد مستقل از قالب باقی میماند |
| مدیریت از پیشخوان | نیاز به FTP یا ویرایشگر پیشخوان | قابل مدیریت از چایلد تم یا افزونه |
| قابلیت اعمال شرطی | دشوار و پرخطا | ساده با is_single()، is_home() و… |
در تجربهٔ من، تنها در دو سناریوی بسیار محدود، ویرایش مستقیم header.php منطقی است: اول، وقتی قالب اختصاصی خودتان است و از ابتدا با آپدیت دستی توسعه مییابد؛ دوم، وقتی کد بهقدری به ساختار آن قالب گره خورده که از wp_head نمیشود به درستی اعمال کرد. در همهٔ موارد دیگر — و بهویژه در قالبهای آماده و تجاری — انتخاب درست، استفاده از هوک wp_head است. اگر با تفاوت قالب و چایلد تم آشنایی ندارید، قالب وردپرس چایلد چیست و چه زمانی به آن نیاز داریم و قالب وردپرس چیست و چگونه قالب مناسب انتخاب کنیم مراجع خوبی هستند.
هوک wp_head: تنها مسیر امن و پایدار
هوک wp_head همان نقطهٔ رسمی وردپرس است که درون <head> هر صفحه اجرا میشود. مهمترین نکتهای که باید بدانید این است: قالبهای استاندارد، همه در ابتدای فایل header.php تابع wp_head() را صدا میزنند؛ همین یک خط، تمام اکوسیستم وردپرس را به هدر متصل میکند. از طریق این هوک، هم هستهٔ وردپرس و هم افزونهها و هم قالبها میتوانند کد خودشان را به هدر تزریق کنند.
الگوی پایه استفاده از این هوک، ساده است:
add_action( 'wp_head', 'wphk_add_custom_header_code' );
function wphk_add_custom_header_code() {
// کدی که به هدر اضافه میشود
}
سه نکتهٔ کلیدی در همین چهار خط: اول، هوک wp_head یک Action است نه Filter؛ بنابراین تابع بازگشت مقدار ندارد و فقط کد تولید میکند. تفاوت دقیق این دو در تفاوت Action و Filter در وردپرس چیست آمده است. دوم، اولویت این هوک بهطور پیشفرض ۱۰ است؛ اگر میخواهید کد شما پیش یا پس از کدهای دیگر بیاید، اولویت را تغییر دهید. توضیح کامل این مفهوم در Priority در هوکهای وردپرس چیست آمده است. سوم، نام تابع با پیشوند یکتا (wphk_) انتخاب شده تا تعارض با افزونههای دیگر پیش نیاید. نحوۀ دقیق اتصال به این هوک در نحوه استفاده از add_action در وردپرس توضیح داده شده است.
سادهترین اسنیپت: افزودن یک کد ثابت به هدر
سادهترین شکل استفاده از این هوک، تزریق یک کد ثابت به هدر است. مثال واقعی: افزودن یک کد رهگیری که در همهٔ صفحات اعمال میشود:
/**
* Snippet: Add tracking script to site header.
*
* @since 2026-09-16
* @author WordPressKar
*
* Purpose: Inject a tracking script in the site head.
* Location: mu-plugins directory or child theme functions.php.
*/
add_action( 'wp_head', 'wphk_add_tracking_script', 5 );
function wphk_add_tracking_script() {
?>
<script async src="https://example.com/tracker.js"></script>
<script>
window.wphkTracker = window.wphkTracker || [];
window.wphkTracker.push({ event: 'pageview' });
</script>
<?php
}
سه نکتهٔ کلیدی در این نمونه: اول، اولویت ۵ انتخاب شده تا کد پیش از کدهای پیشفرض افزونههای دیگر اجرا شود؛ چون کدهای رهگیری معمولاً باید زودتر از بقیه بارگذاری شوند تا همهٔ تعاملات کاربر را بگیرند. دوم، تزریق HTML با ساختار PHP و خروج از حالت PHP برای تولید مستقیم HTML — این رویکرد خوانایی را بالاتر میبرد. سوم، کد رهگیری بهگونهای نوشته شده که حتی اگر فایل بیرونی تأخیر داشته باشد، تعامل کاربر ضبط شود.
یک تصمیم ظریف در این نوع اسنیپتها: تزریق کد پیوسته در برابر بارگذاری فایل خارجی. برخی کدهای رهگیری به فایل خارجی وابستهاند و برخی دیگر را میتوان بهصورت inline نوشت. در پروژههای خودم، کدهای تعامل (event tracking) را بهصورت inline تزریق میکنم تا مستقل از بارگذاری فایل خارجی، ثبت شوند. ولی فایل اصلیِ کتابخانهٔ رهگیری (script tag) باید با async بارگذاری شود تا سرعت صفحه آسیب نبیند. توضیح دقیقتر این تفکیک در چگونه سرعت سایت وردپرسی را افزایش دهیم آمده است.
افزودن شرطی: فقط در صفحات لازم
در پروژههای واقعی، کدهای هدر همیشه در همهٔ صفحات لازم نیستند. مثلاً کد رهگیری Google Tag Manager را معمولاً در همهٔ صفحات لازم داریم، ولی کد تأیید مالکیت Google Search Console فقط در صفحهٔ اصلی لازم است. اعمال شرطی این کدها، سرعت را بالا میبرد و از خروجی اضافه جلوگیری میکند:
add_action( 'wp_head', 'wphk_conditional_header_code' );
function wphk_conditional_header_code() {
if ( is_front_page() ) {
echo '<meta name="google-site-verification" content="YOUR-VERIFICATION-CODE" />';
}
if ( is_singular( 'post' ) ) {
echo '<meta name="twitter:card" content="summary_large_image" />';
}
}
سه نکتهٔ مهم در این الگو: اول، استفاده از شرطهای بومی وردپرس مثل is_front_page و is_singular. این شرطها در لحظهٔ اجرای wp_head بهدرستی مقدار میگیرند و قابل اتکا هستند. دوم، تفکیک کدها در بلوکهای جدا که در آینده بتوان هرکدام را بهسادگی تغییر داد. سوم، خروجی امن؛ اگر کد شما شامل دادهٔ متغیر است، آن را با esc_attr یا esc_html کدگذاری کنید.
نکتهٔ کلیدی که در پروژههای مختلف روی آن تأکید کردهام: این نوع شرطگذاری، هم بار صفحه را کاهش میدهد و هم خروجی HTML را تمیزتر میکند. در سایتهایی که ۳۰ یا ۴۰ کد هدر دارند، اعمال شرطی میتواند تفاوت محسوسی در حجم صفحه و امتیاز Core Web Vitals بسازد. توضیح تفصیلی این اثر در Core Web Vitals چیست و چرا گوگل بر آن تاکید دارد آمده است.
روش حرفهای: بارگذاری اسکریپت با wp_enqueue_script
برای اسکریپتهایی که از یک URL خارجی بارگذاری میشوند، روش حرفهای استفاده از wp_enqueue_script است، نه تزریق مستقیم تگ <script>. تفاوت این دو روش، در سه چیز است: مدیریت بهتر وابستگیها، جلوگیری از تکرار بارگذاری، و امکان مدیریت نسخه.
add_action( 'wp_enqueue_scripts', 'wphk_enqueue_custom_script' );
function wphk_enqueue_custom_script() {
wp_enqueue_script(
'wphk-tracker',
'https://example.com/tracker.js',
array(),
'1.0.0',
false
);
wp_localize_script( 'wphk-tracker', 'wphkData', array(
'userId' => get_current_user_id(),
'pageType' => is_singular() ? 'single' : 'archive',
) );
}
سه نکتهٔ کلیدی در این الگو: اول، استفاده از هوک wp_enqueue_scripts که مخصوص بارگذاری اسکریپت است، نه wp_head. این تفکیک، لایهبندی درست را حفظ میکند. دوم، پارامتر پنجم روی false گذاشته شده تا اسکریپت در <head> بارگذاری شود؛ اگر روی true بگذارید، در <body> بارگذاری میشود که برای اکثر موارد بهتر است. سوم، wp_localize_script برای پاسدادن دادهٔ وردپرس به اسکریپت استفاده شده، الگویی که از تزریق مستقیم متغیرهای PHP در جاوااسکریپت امنتر است. برای مطالعهٔ روشهای معادل در بارگذاری CSS، مهمترین Action Hook های وردپرس مرجع خوبی است.
پنج کاربرد رایج افزودن کد به هدر
در پروژههای خودم، پنج کاربرد رایج افزودن کد به هدر را شناسایی کردهام که هرکدام الگوی خاص خود را دارند. آگاهی از این الگوها، تصمیمگیری را سریعتر میکند:
کاربرد اول: کدهای تحلیلی و رهگیری
پرتکرارترین کاربرد. Google Analytics، Google Tag Manager، Meta Pixel و ابزارهای مشابه، همه با یک کد کوچک در هدر شروع میشوند. الگوی درست: تزریق کد با اولویت پایین (زودتر از بقیه) و بارگذاری فایل خارجی با async. اگر از یک افزونهٔ سئو استفاده میکنید، ممکن است همان افزونه قابلیت افزودن کد تحلیلی داشته باشد؛ در این حالت، افزودن مجدد با اسنیپت باعث دو بار شمارش میشود که باید از آن پرهیز کرد.
کاربرد دوم: متاتگهای تأیید مالکیت
کدهای تأیید Google Search Console، Bing Webmaster و Pinterest، معمولاً یک خط متاتگ ساده هستند. الگوی درست: اعمال شرطی روی صفحهٔ اصلی، برای کاهش حجم صفحههای دیگر. برای مطالعهٔ جامعتر این موضوع، سئو تکنیکال چیست و چرا مهم است را ببینید.
کاربرد سوم: دادهٔ ساختاریافته (Schema)
افزودن JSON-LD برای Article، Product، FAQ یا Breadcrumb. الگوی درست: تزریق کد با ساختار مشخص، استفاده از wp_json_encode برای تولید JSON و اعمال شرطی براساس نوع صفحه. اگر افزونهٔ سئو شما این کار را انجام میدهد، این اسنیپت را اضافه نکنید تا از تکرار schema جلوگیری شود. نقش جامع این داده در نقش Schema در AEO آمده است.
کاربرد چهارم: فونتها و استایلهای بحرانی
افزودن فونتهای وب با preload یا تزریق استایلهای بحرانی برای بهبود LCP. الگوی درست: استفاده از wp_enqueue_style برای فایلهای استایل و preload برای فونتها. یک نکتهٔ ظریف: فونتهای فارسی سنگین، یکی از عوامل اصلی تأخیر در سایتهای ایران هستند؛ اگر با این موضوع آشنایی کمتری دارید، آمادهسازی قالب برای فارسی نکات مفیدی دارد.
کاربرد پنجم: کدهای آزمایشی و A/B تست
افزودن کدهای A/B تست یا کدهای پایش رفتار کاربر. الگوی درست: اعمال شرطی و پرهیز از افزودن کد در همهٔ صفحات، بهویژه در صفحات پرترافیک مانند صفحهٔ محصول یا صفحهٔ تسویهحساب.
ملاحظات سرعت: هر اسکریپت در هدر، چه هزینهای میسازد
افزودن کد به هدر، بهطور مستقیم بر سرعت سایت اثر میگذارد. دلیل این اثر، ساده است: مرورگر پیش از رندر هر چیزی، باید محتوای هدر را پردازش کند. یعنی هر اسکریپت یا استایل جدید در هدر، رندر صفحه را بلوکه میکند. سه قاعدهٔ کارایی که در پروژههای خودم رعایت میکنم:
قاعدهٔ اول: استفاده از async یا defer برای اسکریپتهای غیرحیاتی. اسکریپتهای تحلیلی، تبلیغاتی و رهگیری، معمولاً برای رندر نیازی نیستند. اگر با async بارگذاری شوند، مرورگر بدون انتظار برای اجرای آنها، رندر را ادامه میدهد. تفاوت این دو ویژگی و کاربردشان در چگونه سرعت سایت وردپرسی را افزایش دهیم آمده است.
قاعدهٔ دوم: پرهیز از تزریق کد در همهٔ صفحات. حتی اسکریپتهای سبک، اگر در همهٔ صفحات بارگذاری شوند، مجموعاً بار قابلتوجهی میسازند. اعمال شرطی با is_front_page، is_singular و مشابهها، این بار را بهطور محسوس کاهش میدهد.
قاعدهٔ سوم: پرهیز از تزریق استایل و اسکریپت تکراری. اگر افزونهای قابلیت افزودن کد هدر دارد و شما هم همین کد را با اسنیپت تزریق میکنید، دو بار بارگذاری میشود. بررسی کنید که هر کد فقط در یک جای سایت تزریق شود. برای این بررسی، ابزارهای تست سرعت سایت راهنمای خوبی هستند.
هر خطی که به هدر اضافه میکنید، یک تعهد به کاربر است: او باید صبر کند تا این خط پردازش شود. هر خط اضافه، یک ثانیه از صبر او میگیرد.
امنیت و پایداری در کدهای هدر
کدهایی که به هدر تزریق میشوند، دو ملاحظهٔ امنیتی و پایداری مهم دارند که تجربهام در آنها گران تمام شده:
ملاحظهٔ امنیتی: پاکسازی خروجی
هر دادهٔ متغیری که در کد هدر تزریق میشود، باید با توابع esc_attr، esc_html یا esc_url پاکسازی شود. مثلاً اگر شناسهٔ رهگیری از تنظیمات سایت خوانده میشود و ممکن است توسط کاربر تغییر کند، این پاکسازی ضروری است:
add_action( 'wp_head', 'wphk_safe_tracking_code' );
function wphk_safe_tracking_code() {
$tracking_id = get_option( 'wphk_tracking_id', '' );
if ( empty( $tracking_id ) ) {
return;
}
printf(
'<script>var trackingId = "%s";</script>',
esc_js( $tracking_id )
);
}
سه نکتهٔ کلیدی: اول، بررسی خالیبودن مقدار پیش از تزریق که از تزریق کد بیمعنی جلوگیری میکند. دوم، استفاده از esc_js برای متن داخل جاوااسکریپت که از XSS جلوگیری میکند. سوم، در سایر زمینهها — HTML و ویژگیها — از esc_html و esc_attr استفاده کنید. توضیح جامع این اصول در هوکهای وردپرس و افزایش امنیت کد آمده است.
ملاحظهٔ پایداری: پرهیز از اتکا به ساختار داخلی قالب
کدی که بهطور مستقیم در فایل header.php قرار میگیرد، به ساختار آن قالب گره میخورد. اگر قالب تغییر کند، کد شما از بین میرود. راهحل: استفاده از هوک wp_head که مستقل از قالب کار میکند. اگر مجبور به تغییر مستقیم قالب هستید، کد را در چایلد تم قرار دهید، نه در قالب والد. تفاوت این دو رویکرد در قالب وردپرس چایلد چیست و چه زمانی به آن نیاز داریم آمده است.
محل درست قرارگیری این اسنیپت
مانند همهٔ اسنیپتهای وردپرس، محل قرارگیری این کد هم تصمیم مهمی است. سه گزینه پیش روی شماست:
گزینهٔ اول: چایلد تم. اگر قالب سایت شما از ابتدا چایلد تم دارد، این اسنیپت را در فایل functions.php چایلد تم قرار دهید. در این حالت، کد شما با آپدیت قالب والد پاک نمیشود، ولی اگر روزی قالب را عوض کنید، کد باید منتقل شود. مناسب برای پروژههای کوچک و متوسط.
گزینهٔ دوم: افزونهٔ اختصاصی یا mu-plugins. این گزینه، پایدارترین مسیر برای کدهای مهم است. کد شما در یک افزونهٔ اختصاصی کوچک قرار میگیرد و مستقل از قالب زندگی میکند. اگر با ساختار افزونهٔ اختصاصی آشنا نیستید، کدنویسی اختصاصی برای افزونه وردپرس و ساختار فایلهای یک افزونه استاندارد وردپرس مراجع کاملی هستند.
گزینهٔ سوم: افزونهٔ مدیریت اسنیپت. اگر میخواهید سریع شروع کنید و بعداً تصمیم بگیرید، این گزینه سبکترین راه است. اگر با این رویکرد آشنا نیستید، چگونه قطعه کد وردپرس را ایمن اجرا کنیم نکات ایمنی مهمی دارد.
الگوی عملی من در پروژههای خودم: کدهای تحلیلی و رهگیری که بخشی از استراتژی بلندمدت سایت هستند را در یک افزونهٔ اختصاصی کوچک نگه میدارم. کدهای آزمایشی و موقتی را با افزونهٔ مدیریت اسنیپت اعمال میکنم. و کدهای مرتبط با ظاهر و نمایش (مثل استایلهای کوچک) را در چایلد تم میگذارم. این تفکیک، تجربهٔ من میگوید که نگهداری سادهتر و پایداری بهتری میسازد. برای دیدن فهرست گستردهتری از اسنیپتهای کاربردی، بهترین قطعه کدهای کاربردی وردپرس برای سایتها مرجع خوبی است.
اشتباهات رایج در افزودن کد به هدر
در بازبینی سایتهای مختلف، شش اشتباه تکراری در این حوزه دیدهام که هرکدام درسآموز است:
| اشتباه | پیامد واقعی | اصلاح |
|---|---|---|
ویرایش مستقیم header.php قالب والد | ناپدیدشدن کد با آپدیت قالب | استفاده از هوک wp_head یا چایلد تم |
| تزریق کد در همهٔ صفحات بدون شرط | کندی محسوس و حجم صفحهٔ بالا | شرط با is_front_page، is_singular و… |
| افزودن کد هدر که افزونهٔ سئو هم آن را اضافه میکند | دو بار شمارش یا schema تکراری | بررسی خروجی head پیش از افزودن |
| نبود پاکسازی خروجی برای دادهٔ متغیر | ریسک XSS | esc_attr، esc_html، esc_js |
بارگذاری اسکریپت بدون async یا defer | تأخیر در رندر صفحه، افت LCP | استفاده از این ویژگیها برای اسکریپتهای غیرحیاتی |
| نبود پیشوند اختصاصی در نام تابع | تعارض با افزونههای دیگر | پیشوند یکتا مثل wphk_ |
هرکدام از این اشتباهات را در پروژهای دیدهام و همهشان در چند دقیقه اصلاحشدنی هستند. برای مرور عمومی این نوع خطاها، اشتباهات رایج هنگام استفاده از قطعه کد وردپرس مرجع جامعی است.
مسیر پیشنهادی و نتیجه
افزودن کد سفارشی به هدر وردپرس، یکی از پرتکرارترین نیازهای پروژههای وردپرسی است. مسیر درست این کار، استفاده از هوک wp_head است، نه ویرایش مستقیم فایل header.php قالب. کاربردهای اصلی این اسنیپت — کدهای تحلیلی، متاتگ تأیید، schema، فونت و A/B تست — هرکدام الگوی خود را دارند. سه قاعدهٔ کارایی (استفاده از async، اعمال شرطی، پرهیز از تزریق تکراری) بهتنهایی میتوانند تفاوت محسوسی در سرعت سایت بسازند. دو ملاحظهٔ امنیتی (پاکسازی خروجی، پرهیز از اتکا به ساختار قالب) در همهٔ اسنیپتهای هدر باید رعایت شوند. و محل درست این اسنیپت، افزونهٔ اختصاصی یا چایلد تم است، نه فایل قالب والد.
گام بعدی عملی که پیشنهاد میکنم: در همین امروز، فایل header.php قالب سایت خودتان را باز کنید و ببینید آیا کدی بهطور مستقیم در آن قرار دارد که با آپدیت قالب ممکن است پاک شود. اگر بله، آن کد را به یک اسنیپت با هوک wp_head منتقل کنید و در چایلد تم یا افزونهٔ اختصاصی قرار دهید. این تمرین نیمساعته، در برابر آپدیت بعدی قالب، چند ساعت بازیابی را صرفهجویی میکند. اگر در پروژهای به نکتهٔ جالبی دربارهٔ افزودن کد به هدر برخوردهاید — بهویژه اگر روش تمیزی برای اعمال شرطی این کدها در سایتهای پرترافیک پیدا کردهاید — برای من جالب است بدانید چطور حلش کردید. تجربهٔ خودتان را در دیدگاهها بنویسید؛ بهویژه اگر اسنیپت مکمل دیگری میشناسید که برای خوانندههای بعدی مفید است. 🧩