پسوندهای اشکال زدایی

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

قبل از شروع

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

پسوند را بشکنید

این آموزش هر بار یک جزء افزونه را خراب می کند و سپس نحوه تعمیر آن را نشان می دهد. به یاد داشته باشید که قبل از ادامه دادن به بخش بعدی، اشکالات معرفی شده در یک بخش را لغو کنید. با دانلود نمونه Broken Color در GitHub شروع کنید.

مانیفست را اشکال زدایی کنید

ابتدا، اجازه دهید فایل مانیفست را با تغییر کلید "version" به "versions" بشکنیم:

manifest.json:

{
  "name": "Broken Background Color",
  "version": "1.0",
  "versions": "1.0",
  "description": "Fix an Extension!",
  ...
}

اکنون بیایید برنامه افزودنی را به صورت محلی بارگیری کنیم . یک کادر محاوره ای خطا را مشاهده خواهید کرد که به مشکل اشاره می کند:

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.

گفتگوی خطای کلید مانیفست نامعتبر.

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

آن تغییر را لغو کنید و یک مجوز نامعتبر وارد کنید تا ببینید چه اتفاقی می‌افتد. مجوز "activeTab" را به "activetab" کوچک تغییر دهید:

manifest.json:

{
  ...
  "permissions": ["activeTab", "scripting", "storage"],
  "permissions": ["activetab", "scripting", "storage"],
  ...
}

برنامه افزودنی را ذخیره کنید و دوباره آن را بارگیری کنید. این بار باید با موفقیت بارگیری شود. در صفحه مدیریت برنامه افزودنی، سه دکمه را مشاهده خواهید کرد: جزئیات ، حذف و خطاها . برچسب دکمه Errors هنگامی که خطایی وجود دارد قرمز می شود. برای مشاهده خطای زیر روی دکمه Errors کلیک کنید:

Permission 'activetab' is unknown or URL pattern is malformed.

با کلیک روی دکمه Errors پیغام خطا را پیدا کنید.

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

نحوه پاک کردن خطاهای برنامه افزودنی

توجه: استفاده از طرح مانیفست در ویرایشگر کد راهی است برای اطمینان از اینکه مانیفست دارای قالب بندی مناسب و فیلدهای مورد نیاز است.

سرویس کارگر را اشکال زدایی کنید

مکان یابی سیاهههای مربوط

سرویس‌کار رنگ پیش‌فرض را برای ذخیره‌سازی تنظیم می‌کند و آن را در کنسول ثبت می‌کند. برای مشاهده این گزارش، پانل Chrome DevTools را با انتخاب پیوند آبی رنگ کنار Inspect views باز کنید.

کارمند سرویس در پانل Chrome DevTools گزارش می‌شود.

نکته کلیدی: بازرسی کارگر سرویس آن را فعال نگه می دارد. برای اطمینان از اینکه برنامه افزودنی در هنگام پایان کار سرویس دهنده شما به درستی رفتار می کند، به یاد داشته باشید که DevTools را ببندید.

مکان یابی خطاها

بیایید سرویس worker را با تغییر onInstalled به حروف کوچک oninstalled بشکنیم:

service-worker.js:

// There's a typo in the line below;
// ❌ oninstalled should be ✅ onInstalled.
chrome.runtime.onInstalled.addListener(() => { 
chrome.runtime.oninstalled.addListener(() => { 
  chrome.storage.sync.set({ color: '#3aa757' }, () => {
    console.log('The background color is green.');
  });
});

برای مشاهده گزارش خطا، Refresh کرده و روی Errors کلیک کنید. اولین خطا به شما اطلاع می دهد که سرویس دهنده ثبت نام نکرده است. این به این معنی است که در حین شروع مشکلی رخ داده است:

Service worker registration failed. Status code: 15.

پیغام خطای ثبت نام کارگر سرویس.

توجه: اگر سرویس‌کار نتواند ثبت‌نام کند، تا زمانی که اشکال ثبت‌نام را برطرف نکنید، نمی‌توانید به ابزارهای برنامه‌نویس Chrome دسترسی داشته باشید.

خطای واقعی بعد از این اتفاق می افتد:

Uncaught TypeError: Cannot read properties of undefined (reading 'addListener')

پیام TypeError کشف نشده است.

اشکالی را که معرفی کردیم لغو کنید، روی Clear all در گوشه سمت راست بالا کلیک کنید و برنامه افزودنی را دوباره بارگیری کنید.

وضعیت کارگر خدمات را بررسی کنید

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

1. شناسه برنامه افزودنی خود را که در بالای "Inspect views" قرار دارد کپی کنید.

   

   شناسه برنامه افزودنی در صفحه مدیریت برنامه های افزودنی.

2. فایل مانیفست خود را در مرورگر باز کنید. به عنوان مثال: text chrome-extension://YOUR_EXTENSION_ID/manifest.json
3. فایل را بررسی کنید.
4. به پنل Application بروید.
5. به بخش Service Workers بروید.

برای آزمایش کد خود، سرویس کارمند را با استفاده از پیوندهای کنار وضعیت راه‌اندازی یا متوقف کنید.

وضعیت کارمند سرویس در پنل برنامه. (برای بزرگنمایی تصویر کلیک کنید.)

همچنین، اگر تغییراتی در کد سرویس‌کار اعمال کرده‌اید، می‌توانید روی Update یا skipWaiting کلیک کنید تا تغییرات بلافاصله اعمال شوند.

در حال تازه کردن سرویس کار در پانل برنامه. (برای بزرگنمایی تصویر کلیک کنید.)

توجه: توجه داشته باشید که با این کار هیچ مؤلفه افزونه دیگری بارگیری مجدد نمی شود.

پاپ آپ را اشکال زدایی کنید

اکنون که برنامه افزودنی به درستی مقداردهی اولیه می‌شود، بیایید با توضیح خطوط برجسته شده زیر، پنجره بازشو را بشکنیم:

popup.js:

...
changeColorButton.addEventListener('click', (event) => {
  const color = event.target.value;

  // Query the active tab before injecting the content script
  chrome.tabs.query({ active: true, currentWindow: true }, (tabs) => { 
    // Use the Scripting API to execute a script
    chrome.scripting.executeScript({
      target: { tabId: tabs[0].id },
      args: [color],
      func: setColor
    });
  });
});

به صفحه مدیریت افزونه ها برگردید. دکمه Errors دوباره ظاهر می شود. برای مشاهده گزارش جدید روی آن کلیک کنید. پیغام خطای زیر را نشان می دهد:

Uncaught ReferenceError: tabs is not defined

صفحه مدیریت برنامه‌های افزودنی در حال نمایش خطای بازشو.

شما می توانید DevTools پنجره بازشو را با بررسی پنجره بازشو باز کنید.

DevTools در حال نمایش خطای بازشو.

خطا، tabs is undefined ، می گوید که برنامه افزودنی نمی داند کجا اسکریپت محتوا را تزریق کند. این مورد را با فراخوانی tabs.query() و سپس انتخاب تب فعال تصحیح کنید.

برای به روز رسانی کد، روی دکمه پاک کردن همه در گوشه سمت راست بالا کلیک کنید و سپس برنامه افزودنی را دوباره بارگیری کنید.

توجه: برای سایر صفحات افزونه که به صورت یک برگه نمایش داده می‌شوند، مانند صفحات لغو و گزینه‌های تمام صفحه ، می‌توانید گزارش‌ها را با بررسی صفحه یا با بازدید از صفحه مدیریت برنامه‌های افزودنی پیدا کنید.

اشکال زدایی اسکریپت های محتوایی

حالا بیایید اسکریپت محتوا را با تغییر متغیر "color" به "colors" بشکنیم:

content.js:

...
function setColor(color) {
  // There's a typo in the line below;
  // ❌ colors should be ✅ color.
  document.body.style.backgroundColor = color;
  document.body.style.backgroundColor = colors;
}  

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

اگر به صفحه مدیریت برنامه های افزودنی بروید، دکمه Errors ظاهر نمی شود. زیرا فقط خطاهای زمان اجرا، console.warning و console.error در صفحه مدیریت برنامه های افزودنی ثبت می شوند.

اسکریپت های محتوا در داخل یک وب سایت اجرا می شوند. بنابراین برای یافتن این خطاها باید صفحه وب را که برنامه افزودنی سعی در تغییر آن دارد بررسی کنیم:

Uncaught ReferenceError: colors is not defined

خطای برنامه افزودنی در کنسول صفحه وب نمایش داده می شود.

برای استفاده از DevTools از داخل اسکریپت محتوا، روی پیکان کشویی کنار بالا کلیک کنید و پسوند را انتخاب کنید.

خطای مرجع کشف نشده: رنگ ها تعریف نشده است.

خطا می گوید colors تعریف نشده است. پسوند نباید متغیر را به درستی ارسال کند. اسکریپت تزریق شده را تصحیح کنید تا متغیر رنگ به کد منتقل شود.

نظارت بر درخواست های شبکه

پنجره بازشو اغلب تمام درخواست های شبکه مورد نیاز را قبل از اینکه حتی سریع ترین توسعه دهندگان بتوانند DevTools را باز کنند، انجام می دهد. برای مشاهده این درخواست‌ها، از داخل پنل شبکه Refresh کنید. بدون بستن پانل DevTools، پنجره بازشو بارگذاری مجدد می شود.

برای مشاهده درخواست های شبکه بازشو، داخل پانل شبکه را بازخوانی کنید.

مجوزها را اعلام کنید

برخی از APIهای افزونه به مجوز نیاز دارند. برای اطمینان از اینکه یک برنامه افزودنی مجوزهای صحیح را در مانیفست درخواست می کند، به مقاله مجوزها و APIهای Chrome مراجعه کنید.

  {
    "name": "Broken Background Color",
    ...
    "permissions": [
      "activeTab",
      "declarativeContent",
      "storage"
    ],
  ...
  }

نکته کلیدی: برای برقراری تماس fetch() به یک سرور خارجی، باید URL را به عنوان مجوز میزبان اعلام کنید.

در ادامه مطلب

با مطالعه مستندات درباره Chrome Devtools بیشتر بیاموزید.