چگونه خطای undefined در جاوااسکریپت را برطرف کنیم؟

در یک پروژهٔ فروشگاهی، تیمی داشتم که هر بار روی دکمهٔ «افزودن به سبد» می‌زد، Console مرورگر یک خطای قرمز می‌داد: Cannot read properties of undefined. محصول با موفقیت اضافه می‌شد، ولی هر کاربری که کنسول را باز می‌کرد فکر می‌کرد سایت خراب است. ریشه، ساده بود: پاسخ API در بعضی موارد فیلد cart را برنمی‌گرداند و کد فرض می‌کرد همیشه هست. آن پروژه برایم درس شد که خطای undefined در جاوااسکریپت کم‌تر دربارهٔ نحو است و بیش‌تر دربارهٔ فرض‌های ما از دنیای واقعی.

undefined در جاوااسکریپت یعنی چه؟

در جاوااسکریپت، undefined یکی از هفت مقدار اولیه است و معنایش این است: «این متغیر یا خصوصیت، تعریف شده ولی مقدار نگرفته» یا «این خصوصیت اصلاً وجود ندارد». تفاوت این تعریف با null دقیقاً همان جایی است که خیلی‌ها اشتباه می‌کنند. undefined معمولاً از سمت موتور جاوااسکریپت می‌آید (مقدار پیش‌فرض)، ولی null مقداری است که برنامه‌نویس خودش قرار می‌دهد تا بگوید «عمداً خالی است».

let x;
console.log(x); // undefined
console.log(x === null); // false
console.log(typeof x); // "undefined"

تفاوت undefined و null

درک این تفاوت، نصف راه تشخیص خطاست:

نکتهٔ ظریف: typeof null در جاوااسکریپت "object" است، نه "null". این یک باگ قدیمی در زبان است که تا امروز حفظ شده؛ برای تشخیص دقیق، از === null استفاده کنید نه از typeof.

خطای undefined در چه شکل‌هایی ظاهر می‌شود؟

در کنسول مرورگر، این خطا در چند پیام متفاوت دیده می‌شود؛ همه‌شان یک ریشه دارند ولی پیام متفاوت است:

• Uncaught TypeError: Cannot read properties of undefined (reading 'x')
• Uncaught TypeError: Cannot read property 'x' of undefined (نسخهٔ قدیمی)
• Uncaught ReferenceError: foo is not defined (متغیر اصلاً تعریف نشده)
• undefined is not a function

در پست جداگانه‌ای، تفاوت دقیق این خطاها را در خطای TypeError در جاوااسکریپت و خطای ReferenceError باز کرده‌ام. یک جمله‌ای بگویم: ReferenceError یعنی متغیر هرگز تعریف نشده؛ TypeError ... undefined یعنی تعریف شده ولی مقدارش undefined است.

ریشه‌های اصلی این خطا

در تجربهٔ خودم، این خطا در پنج سناریو رخ می‌دهد:

1. ترتیب اجرا: کدی که قبل از بارگذاری DOM اجرا می‌شود، عنصر document.getElementById("btn") را null یا undefined می‌بیند. راه‌حل: defer یا DOMContentLoaded.
2. پاسخ نامعتبر از API: فیلدی که انتظار دارید همیشه در پاسخ باشد، در بعضی شرایط نیست. راه‌حل: بررسی ساختار پاسخ قبل از دسترسی.
3. مقدار پیش‌فرض نداشتن متغیر: متغیری که در بعضی مسیرهای کد مقدار نمی‌گیرد. راه‌حل: مقدار پیش‌فرض.
4. خطا در حلقه‌ها: for یا forEach روی آرایه‌ای که هنوز خالی است.
5. اشتباه در this: در توابع callback، this دیگر به شیء والد اشاره نمی‌کند و خصوصیت‌هایش undefined می‌شوند.

۹۰٪ خطاهای undefined در جاوااسکریپت، در واقع خطای «فرض غلط دربارهٔ ترتیب یا وجود داده» هستند، نه خطای نگارشی.

تشخیص در Console و Debugger

روش من برای یافتن این خطا در پروژه‌های واقعی:

1. Console: پیام خطا دقیقاً می‌گوید کدام خط از کدام فایل، و چه خصوصیتی از undefined خوانده شده.
2. Sources / Debugger: روی شمارهٔ خط کلیک کنید تا فایل باز شود. یک breakpoint روی همان خط بگذارید و متغیرهای لحظهٔ اجرا را ببینید.
3. Watch expressions: متغیر مشکوک را به Watch اضافه کنید و مقدارش را در هر بار اجرا تماشا کنید.
4. Network tab: اگر ریشه از پاسخ API است، ساختار JSON را در تب Network ببینید.

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

الگوهای امن برای پیشگیری

جاوااسکریپت مدرن چند ابزار عالی برای مقابله با این خطا دارد:

1. Optional Chaining: user?.address?.city اگر user یا address undefined باشد، به‌جای خطا، undefined برمی‌گرداند.
2. Nullish Coalescing: const count = data.count ?? 0; اگر مقدار null یا undefined باشد، صفر می‌گذارد. تفاوتش با || این است که مقادیر 0 یا "" را هم جایگزین نمی‌کند.
3. مقدار پیش‌فرض در پارامترها: function greet(name = "کاربر") { ... }
4. بررسی نوع قبل از دسترسی: if (Array.isArray(data.items)) { ... }

// قبل
const city = user.address.city;

// بعد
const city = user?.address?.city ?? "نامشخص";

در پروژه‌هایی که با React کار می‌کنم، ترکیب optional chaining و state اولیهٔ درست، تقریباً همهٔ خطاهای undefined را قبل از انتشار می‌گیرد.

در وردپرس و پروژه‌های فرانت

در وردپرس، این خطا معمولاً از دو جا می‌آید:

• افزونه‌ها و قالب‌های jQuery-محور قدیمی: کدی که فرض می‌کند عنصر همیشه در صفحه است. اگر یک ویجت در صفحه نباشد، اسکریپت روی undefined می‌افتد.
• جاوااسکریپت قالب که قبل از jQuery بارگذاری می‌شود: ترتیب enqueue در وردپرس، اهمیت زیادی دارد.

در پروژه‌های ووکامرسی، این خطا در صفحهٔ سبد خرید بیشتر دیده می‌شود؛ چون DOM صفحه با AJAX تغییر می‌کند. نکته: این خطا گاهی فقط در ظاهر بی‌خطر است ولی می‌تواند روی نرخ تبدیل اثر بگذارد. در پست CRO برای فروشگاه‌های ووکامرس به تأثیر خطاهای فرانت روی فروش اشاره کرده‌ام.

نگاه آخر

خطای undefined در جاوااسکریپت را می‌توان با یک optional chaining در همان خط رفع کرد؛ ولی این کار همیشه کافی نیست. اگر پیام را با دقت بخوانید و پنج ریشهٔ گفته‌شده در این مقاله را در ذهن داشته باشید، در چند دقیقه تشخیص می‌دهید مشکل از ترتیب اجرا است، از پاسخ API، یا از فرض نادرست شما دربارهٔ داده‌ها. تجربه‌ام این است: سایت‌هایی که Consoleشان تمیز است، هم سریع‌تر توسعه داده می‌شوند هم نرخ تبدیل بالاتری دارند — چون خطاهای نامرئی، همیشه روی تجربهٔ کاربر اثر می‌گذارند. اگر این خطا در پروژهٔ خودتان به شکل جالبی ظاهر شد، در دیدگاه‌ها بنویسید. 🌐