Manifest V3 изменил архитектуру расширений Chrome: background page заменяется service worker, меняются правила permissions, host_permissions, сетевых запросов и жизненного цикла. Поэтому старый код часто перестает работать после формального обновления manifest.

Сначала нужно открыть страницу расширений, посмотреть ошибки service worker, проверить permissions и убедиться, что content scripts реально подключаются к нужным страницам.

Коротко: что делать

  • Открыть chrome://extensions и включить Developer mode
  • Посмотреть ошибки service worker и content scripts
  • Проверить manifest.json на permissions и host_permissions
  • Проверить, не используется ли устаревший background page
  • Проверить messaging между content script, popup и service worker

Основные причины

Чаще всего ломается не одна строка, а модель работы расширения: фоновый код больше не живет постоянно.

  • Код ожидает постоянный background page
  • Не указаны host_permissions для нужных сайтов
  • Content script не подключается из-за matches
  • Сетевые запросы блокируются CSP или permissions
  • События теряются из-за завершения service worker

Пошаговая диагностика

Диагностика начинается с ошибок в браузере: Chrome обычно явно пишет, что не так с manifest или service worker.

  • Проверить manifest на warning и errors
  • Открыть Inspect views для service worker
  • Проверить вкладку Console на целевой странице
  • Проверить chrome.runtime.lastError в callbacks
  • Проверить, какие события реально приходят в service worker

Как исправить проблему

Исправление обычно сводится к переносу фоновой логики на событийную модель и явному описанию разрешений.

  • Переписать background logic под service worker
  • Добавить нужные permissions и host_permissions
  • Исправить content_scripts matches и run_at
  • Переделать хранение состояния через chrome.storage
  • Настроить messaging и обработку ошибок

Безопасный план решения

Сначала добейтесь загрузки расширения без ошибок manifest, затем восстановите content script, затем messaging и только потом сетевые запросы и сложную логику.

Чего не стоит делать

  • Не переносить manifest на V3 механически без проверки архитектуры
  • Не хранить важное состояние только в памяти service worker
  • Не запрашивать лишние permissions без причины
  • Не тестировать только popup, забывая content script

Что подготовить перед исправлением

  • Файл manifest.json
  • Ошибки из chrome://extensions
  • Код background/service worker и content scripts
  • Описание сценария, который перестал работать

FAQ

Почему код работает только иногда?

Service worker может завершаться и запускаться заново. Код должен быть событийным и восстанавливать состояние.

Куда делся background page?

В Manifest V3 используется service worker вместо постоянной фоновой страницы.

Нужно ли переписывать расширение полностью?

Не всегда. Но фоновые части, permissions и messaging часто требуют правки.

Когда стоит обратиться за помощью

Помощь нужна, если расширение связано с рабочими процессами, парсингом страниц, API или публикацией в Chrome Web Store.

Итог

Начните с ошибок service worker и permissions. Если нужно перевести расширение на Manifest V3 без потери функций, можно написать в Telegram @rabotator_support.