Chrome Extension Manifest V3: подробный разбор

Если вы недавно искали руководства по разработке расширений Chrome, то наверняка столкнулись с неприятным фактом: половина найденных материалов опирается на архитектуру background page, которая уже не работает. Manifest V2 объявлен устаревшим и отключён по умолчанию в Chrome. Manifest V3 — это текущая платформа, и понимание её архитектуры — единственная практичная отправная точка для разработки расширений в 2026 году.

В этой статье объясняется, что изменилось, почему и как ключевые API соотносятся между собой.

Почему Chrome отказался от Manifest V2

Расширения Manifest V2 могли запускать постоянную background page — полноценный HTML-документ, который оставался загруженным в памяти бесконечно, даже когда расширение ничего не делало. Это было удобно для разработчиков, но дорого для пользователей. Каждое установленное расширение с background page непрерывно потребляло память и процессорное время.

Помимо производительности, MV2 позволял расширениям загружать и исполнять JavaScript с удалённых URL. Это означало, что расширение могло пройти проверку Chrome Web Store с безобидным кодом, а затем незаметно подменить логику вредоносной с внешнего сервера. Не было практического способа проверить, что расширение реально выполняет.

Эти две проблемы — расход ресурсов и неаудируемый удалённый код — и есть настоящие движущие силы перехода к Manifest V3.

Основные архитектурные изменения в Chrome Extension Manifest V3

Extension Service Workers заменяют background pages

В MV3 постоянная background page исчезла. Её замена — extension service worker, событийно-управляемый скрипт, который Chrome запускает по необходимости и завершает при простое.

Именно это изменение сбивает с толку большинство разработчиков, переходящих с MV2. У service worker нет доступа к DOM, и он не остаётся активным между событиями. Нельзя сохранить состояние в глобальной переменной и рассчитывать, что оно сохранится. Вместо этого используйте chrome.storage для всего, что должно пережить события, и API chrome.alarms для планирования периодических задач, которые раньше выполнялись через setInterval внутри background page.

{
  "background": {
    "service_worker": "background.js",
    "type": "module"
  }
}

declarativeNetRequest заменяет блокирующий webRequest

API webRequest из MV2 позволял расширениям перехватывать каждый сетевой запрос и синхронно решать, блокировать ли его или модифицировать. Это давало расширениям широкий обзор всего трафика браузера — значительный риск для приватности — и приводило к задержкам, поскольку каждый запрос должен был ждать ответа расширения.

API declarativeNetRequest (DNR) работает иначе. Вы определяете набор правил в JSON, Chrome обрабатывает их нативно, и расширениям больше не нужно синхронно перехватывать запросы на JavaScript для их блокировки или модификации. Это быстрее и приватнее по самой архитектуре.

Начиная с Chrome 120, лимиты на правила значительно выросли по сравнению с ранними днями MV3. Блокировщики контента, такие как uBlock Origin Lite, выпустили версии, совместимые с MV3, так что утверждение, будто MV3 «убил блокировщики рекламы», не совсем верно — хотя модель фильтрации действительно более ограничительная, чем подходы эпохи MV2, и оригинальный uBlock Origin по решению автора остаётся только под MV2.

Никакого удалённо размещённого кода

Весь JavaScript, исполняемый расширением MV3, должен быть включён в сам пакет расширения. Загрузка исполняемого кода из внешнего CDN или API запрещена. Это делает каждое расширение полностью аудируемым на момент проверки.

API chrome.action и Offscreen API

API browserAction и pageAction из MV2 объединены в единый chrome.action API в MV3. Он отвечает за иконку на панели инструментов, текст значка и всплывающее окно через один согласованный интерфейс.

Для случаев, когда нужен доступ к DOM или воспроизведение аудио из фонового контекста — то, чего service worker делать не может, — MV3 предоставляет Offscreen API. Он позволяет создать минимальный скрытый документ специально для таких задач, без накладных расходов на полноценную постоянную background page. По данным Can I Use, связанные offscreen API теперь широко поддерживаются в современных браузерах на основе Chromium.

Как выглядит минимальный манифест MV3

{
  "manifest_version": 3,
  "name": "My Extension",
  "version": "1.0",
  "background": { "service_worker": "background.js" },
  "action": { "default_popup": "popup.html" },
  "permissions": ["storage", "activeTab"],
  "host_permissions": ["https://example.com/*"]
}

Обратите внимание, что host permissions теперь объявляются отдельно от API permissions — намеренное изменение, дающее пользователям более чёткое понимание того, к каким сайтам имеет доступ расширение.

Заключение

Manifest V3 — более ограниченная платформа, чем MV2, и часть этих ограничений требует реальных архитектурных изменений. Но эти ограничения существуют по конкретным причинам: меньшее потребление памяти, отсутствие неаудируемого удалённого кода и меньшее воздействие сырого сетевого трафика на процессы расширений. Если вы начинаете новое расширение сегодня, MV3 — единственный практичный поддерживаемый путь. Понимание жизненного цикла service worker и модели declarativeNetRequest — это то, с чего начинается работа.

FAQ

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers. Check our GitHub repo and join the thousands of developers in our community.