Пользователь устанавливает расширение, возвращается в уже открытую вкладку — и ничего не происходит. После F5 всё оживает. Это ожидаемый разрыв жизненного цикла: декларативный content script из manifest применяется при подходящей навигации, а старый документ был создан до установки.

Есть два честных решения. Простое — показать просьбу обновить страницу. Более плавное — после `runtime.onInstalled` найти подходящие вкладки и внедрить скрипт через `chrome.scripting.executeScript`. Второй вариант требует аккуратно работать с разрешениями и повторной инъекцией.

Сначала исключите другую причину

  • URL вкладки действительно совпадает с `matches` и не является внутренней страницей браузера.
  • У расширения есть `scripting` и необходимые host permissions либо временный `activeTab` для действия пользователя.
  • Скрипт не падает до установки визуального признака; ошибка видна в контексте вкладки, а не только service worker.
  • Страница не открыта в другом профиле или режиме, где расширение выключено.

Если content script появляется после обычной перезагрузки, manifest и основной код, скорее всего, исправны. Тогда можно заниматься именно сценарием уже открытых документов.

Явная инъекция после установки

chrome.runtime.onInstalled.addListener(async ({ reason }) => {
  if (reason !== 'install') return;
  const tabs = await chrome.tabs.query({ url: ['https://example.com/*'] });
  for (const tab of tabs) {
    if (!tab.id) continue;
    await chrome.scripting.executeScript({ target: { tabId: tab.id }, files: ['content.js'] });
  }
});

Это условный пример, а не готовый универсальный код. Реальный список URL должен совпадать с функцией расширения. Нельзя запрашивать доступ ко всем сайтам только ради удобства установки.

Сделайте content script повторяемым

Один документ может получить скрипт декларативно после навигации, программно после установки или повторно во время разработки. Поэтому инициализация должна проверять собственный маркер и не создавать второй observer, панель или обработчик сообщений.

if (!globalThis.__myExtensionInitialized) {
  globalThis.__myExtensionInitialized = true;
  startExtensionForThisDocument();
}

Для сложного расширения удобнее возвращать из проверочной функции версию уже установленного content script и решать, нужна ли миграция. Маркер DOM менее надёжен: его может удалить сама страница.

Что делать с запрещёнными страницами

СтраницаПоведение
Разрешённый HTTPS-сайтИнъекция при наличии host permission
chrome://, магазин расширений, системная страницаНе пытаться внедрять код
Файл или incognitoТолько если пользователь отдельно разрешил соответствующий доступ
Страница без выданного host permissionОбъяснить и запросить доступ из понятного действия

Проверка установки глазами пользователя

  1. Откройте целевую страницу до установки расширения.
  2. Установите production-подобную сборку и вернитесь во вкладку без F5.
  3. Убедитесь, что функция появилась один раз и не затронула запрещённые URL.
  4. Обновите страницу и проверьте, что повторная инициализация не создаёт дубли.
  5. Удалите расширение: внедрённый код не должен продолжать опасные действия без своего runtime.

Если автоматическая инъекция не оправдана правами, сообщение «обновите уже открытые вкладки» лучше скрытой поломки. Для технического разбора нужны manifest, target URL без приватных параметров и ошибки из service worker и content script.

Проверенные источники