Як налагоджувати сервісний воркер Manifest V3

Коротка відповідь

Спершу визначте: воркер не зареєструвався, пропустив подію, кинув помилку в обробнику чи втратив пам’ять після завершення. Це різні виправлення. Відкрийте chrome://extensions, перегляньте помилки й посилання налагодження сервісного воркера.

Неактивний воркер — нормальний стан. Chrome пробуджує його подіями. Якщо функція працює лише з DevTools, підозрюйте залежність від життєвого циклу: налагодження утримує воркер і приховує холодний запуск.

Практичні кроки реалізації

1. Для відмови реєстрації перевірте шлях, синтаксис зібраного JavaScript, імпорти й випадковий DOM-доступ при ініціалізації. Один зламаний імпорт може заблокувати всіх слухачів.
2. Для пропущених подій журналюйте запуск модуля окремо від входу обробника. Реєструйте синхронно до очікування параметрів. Перевірте, чи налаштоване вікно не замінило очікуваний action.onClicked.
3. Для відмови обробника записуйте ID запиту, етап і очищену помилку. Обробляйте кожен відхилений проміс; не журналюйте весь текст сторінки, секрети чи звіти лише заради доказу запуску.
4. Для втрати стану запустіть із порожнім кешем і перевірте записи. Звіт на зразок LocaleStress не має зникати через завершення воркера. Розрізняйте тимчасовий прогрес і підтверджені записи.
5. Закрийте DevTools і відтворіть взаємодію після простою чи перезапуску. Запишіть версію й точні кроки. Потім знову перегляньте журнали без постійного налагодження протягом перевірки.

Перезавантаження розпакованого розширення також викликає оновлення. Якщо onInstalled перезаписує параметри, це може виглядати як помилка сховища. Перевірте причину події й мігруйте відсутні поля замість постійного скидання.

Приклад реалізації

Ідентифікатор запуску відрізняє час життя воркера без даних сторінки. Це тимчасове журналювання відомої події за дозволу storage.

const bootId = crypto.randomUUID();
console.info("worker-start", { bootId });

chrome.runtime.onInstalled.addListener((details) => {
  console.info("installed-event", { bootId, reason: details.reason });
  chrome.storage.local.get("schemaVersion").then(
    ({ schemaVersion }) => console.info("schema-read", { bootId, schemaVersion }),
    (error) => console.error("schema-read-failed", { bootId, message: String(error) }),
  );
});

Нові ID очікувані при холодних запусках. Якщо запуск є, а входу обробника немає, досліджуйте доставку події; якщо вхід є, а читання відмовляє — сховище чи дозволи. Приберіть тимчасові деталі перед випуском або залиште свідомо обмежену діагностику.

Компроміси та альтернативи

Використовуйте breakpoints для локальної логіки, а відтворення без debugger — для завершення. Імітація перевіряє перетворення помилки, справжній пакет — реєстрацію й події.

Поширені помилки

• Називати простій відмовою реєстрації.
• Перевіряти завершення з DevTools.
• Додавати keepalive-таймери до визначення втраченого стану.
• Шукати помилку імпорту воркера в консолі вікна.

Контрольний список випуску

• ☐ Відмови реєстрації та обробника розрізняються.
• ☐ Реєстрація передує асинхронній роботі.
• ☐ Відхилені проміси мають діагностику.
• ☐ Холодний шлях перевірено без налагодження.
• ☐ Збережені дані переживають перезапуск воркера.

Поширені запитання

Чому перезавантаження допомагає?

Воно очищає пам’ять, повторює запуск або викликає update-обробники. Це звужує пошук, але не визначає причину.

Що включити у звіт про помилку?

Версії, точний виклик, очищену помилку й наявність відкритого налагодження.

Яка наступна дія?

Відтворіть одну відмову з холодного запуску й виправте перший відсутній етап замість одночасної зміни кількох механізмів.

Первинні джерела

• Налагодження розширень
• Життєвий цикл воркера
• Події воркера

Пов’язані посібники та приклади

• Тематичний розділ
• Модульне тестування логіки розширень Chrome
• Наскрізне тестування розширень Chrome з Playwright
• Як створити розширення Chrome з Manifest V3
• Процес збережених звітів LocaleStress