Перехват и модификация HTTP-запросов в расширениях MV3

Техническая реализация перехвата HTTP-запросов в браузерном расширении

Клиент ставит задачу: блокировать скрипты телеметрии, добавлять авторизационные заголовки к внутренним API и перенаправлять все медиа-запросы на быстрый CDN. Без перехвата HTTP-запросов не обойтись. Мы реализовали десятки таких расширений и знаем все подводные камни — от ограничений Manifest V3 до нюансов кросс-браузерной совместимости.

Раньше разработчики активно использовали chrome.webRequest с флагом blocking, но с переходом на Manifest V3 этот метод потерял гибкость. Современный стандарт — declarativeNetRequest, декларативный API, который переносит обработку правил на уровень браузера. Он быстрее, безопаснее и не нагружает основной поток, но накладывает строгие лимиты: одновременно можно активировать не более 5 000 правил. Разберём, как проектировать систему правил, чтобы обойти ограничения и сохранить полный контроль над трафиком.

Как перехватить запросы в MV3?

В основу положен декларативный подход: вы описываете правила в JSON, а браузер сам их применяет. Расширение не тратит CPU на анализ каждого запроса, а значит, Core Web Vitals не страдают.

Статические правила

Правила, определённые в файле rules/static.json, действуют постоянно. Пример настройки блока аналитики, модификации заголовков и редиректа:

[
  {
    "id": 1,
    "priority": 1,
    "action": {
      "type": "block"
    },
    "condition": {
      "urlFilter": "||analytics.example.com^",
      "resourceTypes": ["script", "xmlhttprequest", "image"]
    }
  },
  {
    "id": 2,
    "priority": 2,
    "action": {
      "type": "modifyHeaders",
      "requestHeaders": [
        {
          "header": "X-Custom-Token",
          "operation": "set",
          "value": "my-token"
        },
        {
          "header": "Referer",
          "operation": "remove"
        }
      ]
    },
    "condition": {
      "urlFilter": "https://api.internal.corp/*",
      "resourceTypes": ["xmlhttprequest"]
    }
  },
  {
    "id": 3,
    "priority": 1,
    "action": {
      "type": "redirect",
      "redirect": {
        "regexSubstitution": "https://cdn.example.com\\1"
      }
    },
    "condition": {
      "regexFilter": "^https://slow-cdn\\.com(.*)",
      "resourceTypes": ["image", "media", "font"]
    }
  }
]

Лимиты: до 30 000 статических правил суммарно, одновременно включено не более 5 000. Остальные можно активировать динамически через service worker.

Динамические правила

Если нужно добавлять правила на лету — используйте service worker. Например, блокировка/разблокировка домена или подстановка токена авторизации:

// background/sw.js
async function blockDomain(domain) {
  const existingRules = await chrome.declarativeNetRequest.getDynamicRules();
  const maxId = existingRules.reduce((max, r) => Math.max(max, r.id), 0);
  await chrome.declarativeNetRequest.updateDynamicRules({
    addRules: [{
      id: maxId + 1,
      priority: 10,
      action: { type: 'block' },
      condition: {
        urlFilter: `||${domain}^`,
        resourceTypes: [
          'main_frame',
          'sub_frame',
          'script',
          'stylesheet',
          'image',
          'xmlhttprequest',
          'other'
        ]
      }
    }],
    removeRuleIds: []
  });
}

Как модифицировать тело запроса через content script?

declarativeNetRequest не позволяет менять тело. Для этого используйте content script с world 'MAIN', перехватив fetch и XMLHttpRequest. Пример инъекции поля в тело POST-запроса:

const originalFetch = window.fetch;
window.fetch = async function(input, init = {}) {
  const url = typeof input === 'string' ? input : input.url;
  if (url.includes('api.target.com')) {
    init.headers = {
      ...init.headers,
      'X-Injected-Header': 'value',
    };
    if (init.body) {
      const body = JSON.parse(init.body);
      body.extraField = 'injected';
      init.body = JSON.stringify(body);
    }
  }
  return originalFetch.call(this, input, init);
};

Учтите: monkey-patching не работает для запросов из веб-воркеров и WebSocket. Для полного контроля над трафиком (корпоративные прокси) корпоративная политика Chrome до сих пор разрешает MV2, но публичный Chrome Web Store его не принимает.

Почему declarativeNetRequest быстрее webRequest?

Основное отличие — нативная обработка правил браузером без участия JavaScript. WebRequest требует синхронной обработки каждого запроса в расширении, что задерживает ответ и ухудшает TTFB. declarativeNetRequest обрабатывает правила на уровне сетевого стека, что снижает LCP на 10–20% в типовых кейсах.

Дополнительная таблица: когда применять статические и динамические правила

Какие ограничения у declarativeNetRequest?

Кроме лимита на количество правил (5 000 включённых), важно помнить: динамические правила можно добавлять только из service worker, а не из popup или content script. Также все правила должны быть объявлены заранее — нельзя сгенерировать правило на основе произвольного JS-вычисления. Для отладки используйте chrome.declarativeNetRequest.getMatchedRules() и testMatchOutcome(). Эти методы помогут проверить, какое правило сработает для конкретного URL, и выявить конфликты.

Что входит в нашу реализацию

• Архитектура: проектирование системы правил (статические + динамические) с учётом лимитов MV3.
• Content scripts: monkey-patching для модификации тела запросов, если необходимо.
• Отладка: тестирование правил через testMatchOutcome, логирование срабатываний.
• Документация: описание всех правил, схемы перенаправлений.
• Поддержка: сопровождение после запуска, обновление при изменении API.

Процесс работы

1. Аналитика — изучаем структуру запросов вашего приложения, выявляем цели перехвата.
2. Проектирование — создаём спецификацию правил, согласовываем с вами.
3. Реализация — пишем код расширения, включая service worker и content scripts.
4. Тест — проверяем на реальных сценариях, отлавливаем edge cases.
5. Деплой — публикуем в Chrome Web Store (или корпоративный реестр).

Сроки и гарантии

Срок разработки — от 5 до 15 рабочих дней в зависимости от сложности. Мы гарантируем стабильную работу и соответствие политикам Chrome Web Store. Опыт — более 50 проектов по браузерным расширениям.

За подробной информацией обращайтесь к официальной документации declarativeNetRequest. Получите консультацию по вашему проекту — свяжитесь с нами для обсуждения.