Content Script для модификации страниц в браузерном расширении

Как правильно внедрить content script в браузерное расширение?

Представьте: вы разработали расширение для Chrome, которое подсвечивает цены на странице интернет-магазина. Content script работает на первой загрузке, но когда пользователь переходит в корзину через pushState, скрипт перестаёт реагировать — MutationObserver не срабатывает. Такая ситуация — классика SPA-ловушек. Мы сталкиваемся с подобными кейсами на каждом втором проекте. В этой статье разберём, как корректно внедрить content script, обработать SPA-навигацию, организовать обмен данными с background и избежать типичных ошибок.

Content script — это механизм инъекции кода в страницу. Мы интегрируем content script — JavaScript-файл, который браузер внедряет в контекст целевой страницы в изолированном окружении, как указано в документации Chrome Extensions. Это даёт доступ к DOM, но не к переменным страницы, что является и защитой, и ограничением. Наш опыт — 5+ лет и 30+ успешных проектов в области браузерных расширений. Content script предназначен для модификации DOM целевой страницы.

Как браузер загружает content script

В manifest.json (MV3) объявляете список скриптов и условия их запуска. Параметр run_at определяет момент внедрения. Ниже — сравнение значений:

{ "manifest_version": 3, "content_scripts": [ { "matches": ["https://*.example.com/*"], "js": ["content/injected.js"], "css": ["content/injected.css"], "run_at": "document_idle", "world": "ISOLATED" } ] } 

Если нужно внедрить скрипт динамически — из service worker или по требованию — используйте chrome.scripting.executeScript:

// background/service-worker.js chrome.action.onClicked.addListener(async (tab) => { await chrome.scripting.executeScript({ target: { tabId: tab.id, allFrames: false }, files: ['content/injected.js'], world: 'ISOLATED' }); }); 

Сравнение ISOLATED и MAIN world

world: 'MAIN' даёт доступ к переменным страницы, но теряет изоляцию — используйте только когда это реально нужно (перехват вызовов нативных API).

Почему content script не срабатывает на SPA-страницах?

При клиентской навигации браузер не перезагружает content script. MutationObserver на