الإضافة لا تظهر: أين تجد السجلات وكيف تقرأ الأخطاء
صنعتها باتباع أول إضافة Chrome: Hello World في 15 دقيقة، وهذه المرة أضفت ميزات جديدة، فكانت النتيجة: النقر على الأيقونة لا يفتح popup أو يظهر فارغًا، وكتبت console.log ولا تراه في أي مكان، والميزة تعمل أحيانًا ولا تعمل أحيانًا، وfetch للواجهة الخارجية يفشل دائمًا. لا تتعجل بتعديل الكود — الدرس الأول في تصحيح أخطاء إضافات chrome: اعثر على السجلات في الموضع الصحيح، واقرأ من الأخطاء معلومات مفيدة.
ماذا ستستطيع أن تفعل بعد التعلم
- في 60 ثانية تميّز بين نوعين من المشكلات: «فشل التحميل» (يظهر مربع حوار خطأ عند التحميل) و«نجح التحميل لكن هناك خطأ» (يصبح زر Errors أحمر)
- تعثر دفعة واحدة على مواضع سجلات أجزاء الكود الثلاثة: Service Worker وpopup وcontent script، دون البحث في الواجهة كلها عن
console.log - تتعرف على نصوص 6 أخطاء عالية التكرار في إضافات Chrome، ولكل خطأ تعرف السبب وطريقة الإصلاح
- تُطعم نص الخطأ للذكاء الاصطناعي كما هو؛ وعندما لا يُجدي الفحص الذاتي في جولتين، ترفع مستوى طلب المساعدة مع ثلاثة عناصر من المواد
⏳ الفحص الأول: فحص سريع في 60 ثانية
افتح صفحة إدارة الامتدادات، وحدد أولًا إلى أي فئة تنتمي المشكلة:
# 1. أدخل في شريط العناوين لفتح صفحة إدارة الامتدادات، واعثر على بطاقة إضافتك
chrome://extensions
# 2. ظهور مربع حوار خطأ عند التحميل ← manifest معطوب، فشل تحميل الإضافة ← انظر «مشكلات manifest والأذونات»
# 3. زر Errors أصبح أحمر ← نجح التحميل لكن هناك خطأ، افتحه وانسخ النص ← طابق نص الخطأ مع القسم المناسب
# 4. كلا الموضعين نظيف ← تأكد من أن الإضافة مفعّلة، وانقر «إعادة التحميل»، ثم أعد إظهار الأعراض مرة أخرى
# 5. ما زلت بلا أدلة ← غالبًا تشاهد السجلات في المكان الخطأ ← انظر «أين تجد السجلات» وبدّل إلى وحدة التحكم الصحيحة وأعد المحاولة🔧 استكشاف المشكلات الشائعة وإصلاحها
نصوص الأخطاء أدناه مأخوذة حرفيًا من مثال Broken Color في درس Chrome الرسمي لتصحيح أخطاء الامتدادات، مجمّعة حسب مكونات الإضافة، ولكل خطأ السبب وطريقة الإصلاح.
أين تجد السجلات: في تصحيح أخطاء إضافات chrome انظر أولًا إلى المكان الصحيح
«كتبت console.log ولا ترى المخرجات في أي مكان»
السبب: سجلات أجزاء الكود الثلاثة للإضافة تُطبع في ثلاثة أماكن مختلفة تمامًا، وإذا نظرت في المكان الخطأ لن ترى أيًّا منها.
الحل: طابق كل حالة مع موضعها —
| أين يوجد الكود | أين توجد السجلات | كيف تفتحها |
|---|---|---|
| Service Worker | صفحة الامتدادات Inspect views DevTools المُفتوح عبر الرابط المجاور لها | chrome://extensions ← انقر على رابط service worker على بطاقة الإضافة |
| popup | DevTools الخاص بالـ popup | انقر بزر الماوس الأيمن على popup الظاهر ← «فحص» |
| content script | وحدة تحكم الصفحة المضيفة | على الصفحة الهدف اضغط F12، واختر إضافتك من القائمة المنسدلة بجانب top |
ينبغي أن ترى: console.log لكل جزء من الكود يظهر في الموضع المقابل. لمعرفة ما يديره كل جزء من الأجزاء الثلاثة، انظر Content Script وService Worker: عقل الإضافة وأطرافها.
💡 الصفحات الكاملة الأخرى للإضافة
صفحات الإضافة المعروضة كعلامات تبويب (مثل صفحة الخيارات الكاملة)، انقر عليها بزر الماوس الأيمن واختر «فحص» مباشرة على الصفحة لرؤية السجلات، أو عد إلى صفحة إدارة الامتدادات لرؤية Errors.
«الميزة تعمل أحيانًا ولا تعمل أحيانًا، وكأن service worker نائم»
السبب: ليس بالضرورة وهمًا. أثناء Inspect (فتح DevTools) يبقى service worker نشطًا طوال الوقت، وكثير من المشكلات «التي تنكشف بعد السكون فقط» لا يمكن إعادة إظهارها حينها؛ وبمجرد إغلاق DevTools يُنهى وفق دورة حياته الطبيعية.
الحل:
- عند إعادة إظهار المشكلة أبقِ DevTools مفتوحًا (ادخل من رابط Inspect views)، لضمان ألا ينام worker في المنتصف.
- عند التحقق من السلوك الحقيقي أغلق DevTools، ليُنهى worker وفق دورة حياته الطبيعية.
- للتشغيل والإيقاف يدويًا: انسخ معرّف الامتداد الموجود أعلى Inspect views في صفحة الامتدادات، ثم افتح
chrome-extension://<你的扩展ID>/manifest.jsonفي المتصفح، وبعد فحص تلك الصفحة انتقل إلى لوحة Application ثم إلى الجزء Service Workers، واستخدم الرابط بجانب status للتشغيل أو الإيقاف.
مشكلات manifest والصلاحيات
«Failed to load extension / Required value version is missing or invalid. It must be between 1-4 dot-separated integers each between 0 and 65536. / Could not load manifest.»
السبب: خطأ في اسم حقل أو تنسيق ملف manifest.json — مثلًا كتابة "versions" بدلًا من "version"، فالإضافة لم تُحمَّل أصلًا. يظهر مربع حوار الخطأ هذا عند التحميل، وسيشير Chrome إلى موضع المشكلة.
الحل:
- راجع الحقل المذكور في مربع الحوار داخل manifest.json، وأعده إلى الصياغة الصحيحة (
versions→version). - بعد الحفظ ارجع إلى
chrome://extensionsواضغط «إعادة التحميل». - المفترض أن ترى: مربع الحوار لا يظهر مجددًا، وبطاقة الإضافة تُعرض بشكل طبيعي.
- إذا لم تنجح التعديلات بعد محاولات متكررة، انسخ رسالة الخطأ كاملة كما هي إلى الذكاء الاصطناعي وأرفق النص الكامل لملف manifest.json.
💡 امنع هذا النوع من الأخطاء مسبقًا
في محرر الأكواد، اربط ملف manifest.json بمخطط JSON الخاص بـ Chrome manifest (json.schemastore.org/chrome-manifest)، وسيظهر باللون الأحمر مباشرة أي خطأ إملائي في أسماء الحقول أو نقص في الحقول المطلوبة.
«Permission 'activetab' is unknown or URL pattern is malformed.»
السبب: خطأ إملائي في اسم الصلاحية، مثل كتابة activetab بحروف صغيرة بالكامل بدلًا من activeTab. ملاحظة: مع هذا النوع من الأخطاء تظل الإضافة قادرة على التحميل بنجاح، لكن يتحول زر Errors في صفحة الامتدادات إلى اللون الأحمر، وهو الأسهل إغفالًا.
الحل:
- افتح
chrome://extensions، واضغط زر Errors الأحمر على بطاقة الإضافة. - صحّح كتابة الصلاحية المذكورة في الخطأ:
activetab→activeTab. - اضغط Clear all في الزاوية العلوية اليمنى لمسح السجلات القديمة، ثم أعد تحميل الإضافة.
- المفترض أن ترى: زر Errors لا يتحول إلى الأحمر بعد الآن.
«طلب fetch() إلى واجهة خارجية يفشل دائمًا»
السبب: لم يُعلن ملف manifest عنوان URL الهدف كـ host permission. لاستخدام fetch() مع خادم خارجي، يجب أولًا الإعلان عن هذا العنوان في manifest، وإلا فلن يُرسَل الطلب أصلًا — نفس الكود يعمل عند وضعه في صفحة ويب عادية، وهذا هو الفرق.
الحل:
- أعلن عن الموقع الهدف كـ host permission في ملف manifest.
- بعد الحفظ أعد تحميل الإضافة، ثم أرسل الطلب مرة أخرى.
- المفترض أن ترى: الطلب يظهر في لوحة Network الخاصة بالـ popup (طريقة الالتقاط موضحة في «مشكلات popup»).
مشكلات Service Worker
«Service worker registration failed. Status code: 15.»
السبب: ألقى service worker خطأً في مرحلة بدء التشغيل (التسجيل)، مثل كتابة oninstalled بحروف صغيرة بدلًا من onInstalled. أثناء فشل التسجيل، لا يمكن فتح DevTools الخاص بالـ worker إطلاقًا، لذا يجب إصلاح هذا الخطأ أولًا.
الحل:
- ارجع إلى
chrome://extensionsواضغط Errors، وأول ما يظهر هو فشل التسجيل هذا. - السبب الحقيقي عادةً ما يكون في رسالة الخطأ الثانية التي تليه مباشرةً (انظر القسم التالي)، فعدّل الكود بناءً عليها.
- بعد التعديل اضغط Clear all وأعد التحميل. المفترض أن ترى: هذا الخطأ لا يظهر في Errors بعد الآن.
«Uncaught TypeError: Cannot read properties of undefined (reading 'addListener')»
السبب: استدعاء addListener على كائن undefined — وفي الغالبية الساحقة يكون السبب خطأً إملائيًا في اسم API (مثل كتابة oninstalled بدلًا من onInstalled)، فيتعذر الحصول على الكائن، وينفجر الاستدعاء التالي.
الحل:
- حسب رقم السطر في رسالة الخطأ، راجع كتابة اسم API وحالة الأحرف، وأعده إلى الاسم الصحيح.
- أعد تحميل الإضافة، وافتح DevTools من Inspect views للتأكد من تسجيل الـ worker بشكل طبيعي.
- المفترض أن ترى: السجلات التي كتبتها تُطبع في Console الخاص بالـ worker، ولا تظهر أخطاء بعد الآن.
مشكلات popup
«Uncaught ReferenceError: tabs is not defined»
السبب: استُخدم في كود popup متغير tabs غير معرّف (مثلًا تم التعليق على مقطع tabs.query)، فلا تعرف الإضافة في أي تبويب تحقن السكربت.
الحل:
- انقر بزر الفأرة الأيمن على الـ popup الظاهر → «فحص»، ليُفتح DevTools الخاص بالـ popup نفسه، وستجد الخطأ في Console.
- أضف
tabs.queryللحصول على التبويب الحالي، ثم استخدمtabs[0].idلتحديد هدف الحقن. - اضغط Clear all وأعد التحميل، ثم افتح الـ popup مجددًا للتحقق. المفترض أن ترى: بعد الضغط على الزر يظهر التأثير المتوقع في التبويب الهدف.
«لا يمكن التقاط أي من طلبات الشبكة الخاصة بالـ popup»
السبب: يرسل الـ popup الطلبات بسرعة كبيرة، وغالبًا ما تكتمل جميعها قبل أن تفتح DevTools، لذلك تظهر لوحة Network فارغة تمامًا.
الحل: في DevTools الخاص بالـ popup انتقل إلى لوحة Network، ثم اضغط زر التحديث داخل اللوحة — بهذه الطريقة يُعاد تحميل الـ popup دون إغلاق DevTools، فتُسجَّل الطلبات.
مشكلات content script
«Uncaught ReferenceError: colors is not defined»
السبب: خطأ إملائي في اسم المتغير داخل content script (مثل كتابة colors بدلًا من color)، فلم ينقل السكربت المحقون المتغير بشكل صحيح.
الحل:
- اذهب إلى صفحة الويب المضيفة واضغط F12 لفتح وحدة التحكم — أخطاء content script تُطبع هنا، لا في صفحة الامتدادات.
- في وحدة التحكم، اضغط السهم المنسدل بجانب top واختر إضافتك لعرض سجلاتها فقط.
- حسب رسالة الخطأ، أعِد اسم المتغير إلى الصياغة الصحيحة، ثم حدّث صفحة الويب وأعد المحاولة. المفترض أن ترى: اختفاء الخطأ من وحدة تحكم صفحة الويب وظهور التأثير في الصفحة.
«صفحة الامتدادات نظيفة تمامًا في Errors، لكن الإضافة لا تعمل»
السبب: زر Errors في صفحة الامتدادات يسجّل أخطاء وقت التشغيل وconsole.warning وconsole.error فقط. كثير من مشكلات content script لا تظهر هناك — فإذا نظرت إلى مكان السجلات الخاطئ، فمهما بحثت طويلًا فلن تجد شيئًا.
الحل:
- انتقل إلى وحدة تحكم صفحة الويب المضيفة وابحث هناك مرة أخرى (الطريقة موضحة في البند السابق).
- إذا كانت السجلات نظيفة فعلًا وتم التحقق من manifest بالمخطط، لكن الميزة ما زالت لا تعمل — توقف عن المحاولة العشوائية، واطلب مساعدة أرقى مصحوبًا بثلاثة عناصر (انظر أدناه).
💡 لا يزال لا يعمل؟
إذا أجريت جولتين من الفحص الذاتي دون أي فكرة، توقف عن التجربة العشوائية. عند حدوث أي من الحالات التالية، قم بالتصعيد مباشرة:
- الخطأ يتعلق بسلوك Chrome API، والتعديلات التي قدمها الذكاء الاصطناعي في جولتين متتاليتين لم تكن فعالة
- السجلات نظيفة، واجتاز التحقق من schema في manifest، لكن الميزة لا تزال لا تعمل، وقد تأكدت أنك لم تنظر إلى موقع السجلات بشكل خاطئ
عند طلب المساعدة، أحضر معك ثلاثة عناصر:
- النص الكامل لملف manifest.json
- النص الكامل للخطأ بما في ذلك تتبع المكدس (stack trace)
- خطوات إعادة الإنتاج المصغرة
بعد اكتمال هذه المواد، سواء أرسلتها إلى الذكاء الاصطناعي أو ذهبت لطرح سؤال، ستحصل على إجابة فعالة من الجولة الأولى. أما الطريقة المحددة لإعادة تغذية نص الخطأ كما هو إلى الذكاء الاصطناعي، فراجع حلقة الأخطاء: أعد تغذية رسالة الخطأ كما هي.
للتلخيص، مسار تصحيح أخطاء إضافة chrome يتكون من ثلاث خطوات: أولاً التصنيف، ثم العثور على موقع السجلات الصحيح، وأخيراً إعادة تغذية نص الخطأ كما هو.
استعراض الدرس التالي
بعد أن تعمل الإضافة بشكل مستقر، شاركها مع المزيد من الأشخاص: في الصفحة التالية نشر الإضافة على متجر تطبيقات Chrome: التسجيل والحزم وتقديم المراجعة بالكامل، سنأخذك عبر العملية الكاملة للتسجيل كحساب مطور والحزم وتقديم المراجعة.