Manifest V3 do Chrome Extension Explicado

Se você pesquisou tutoriais de extensões do Chrome recentemente, provavelmente notou algo frustrante: metade dos guias que você encontra faz referência a uma arquitetura de background page que não funciona mais. O Manifest V2 está descontinuado e desativado por padrão no Chrome. O Manifest V3 é a plataforma atual, e entender sua arquitetura é o único ponto de partida prático para o desenvolvimento de extensões em 2026.

Este artigo explica o que mudou, por que mudou e como as principais APIs se encaixam.

Por Que o Chrome Abandonou o Manifest V2

As extensões do Manifest V2 podiam executar uma background page persistente — um documento HTML completo que permanecia carregado na memória indefinidamente, mesmo quando a extensão não estava fazendo nada. Isso era conveniente para os desenvolvedores, mas caro para os usuários. Cada extensão instalada com uma background page consumia memória e CPU continuamente.

Além do desempenho, o MV2 permitia que extensões carregassem e executassem JavaScript a partir de URLs remotas. Isso significava que uma extensão poderia passar pela revisão da Chrome Web Store com código inofensivo e, posteriormente, substituí-lo silenciosamente por lógica maliciosa vinda de um servidor externo. Não havia maneira prática de auditar o que uma extensão estava realmente executando.

Esses dois problemas — desperdício de recursos e código remoto não auditável — são os verdadeiros motivadores por trás do Manifest V3.

As Principais Mudanças Arquiteturais no Chrome Extension Manifest V3

Extension Service Workers Substituem as Background Pages

No MV3, a background page persistente acabou. Sua substituta é um extension service worker — um script orientado a eventos que o Chrome inicia quando necessário e encerra quando ocioso.

Essa é a mudança que mais confunde os desenvolvedores vindos do MV2. Um service worker não tem acesso ao DOM e não permanece ativo entre eventos. Você não pode armazenar estado em uma variável global e esperar que ele persista. Em vez disso, use chrome.storage para qualquer coisa que precise sobreviver entre eventos, e use a API chrome.alarms para agendar trabalhos recorrentes que anteriormente viveriam em uma chamada setInterval dentro de uma background page.

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

declarativeNetRequest Substitui o webRequest Bloqueante

A API webRequest do MV2 permitia que as extensões interceptassem cada requisição de rede e decidissem sincronicamente se a bloqueariam ou modificariam. Isso dava às extensões ampla visibilidade sobre todo o tráfego do navegador — uma exposição significativa de privacidade — e introduzia latência, pois cada requisição tinha que aguardar a resposta da extensão.

A API declarativeNetRequest (DNR) funciona de forma diferente. Você define um conjunto de regras em JSON, o Chrome as avalia nativamente, e as extensões não precisam mais interceptar requisições sincronicamente em JavaScript para bloqueá-las ou modificá-las. Isso é mais rápido e mais privado por design.

Desde o Chrome 120, os limites de regras foram consideravelmente expandidos em relação aos primórdios do MV3. Bloqueadores de conteúdo como o uBlock Origin Lite lançaram versões compatíveis com o MV3, então a afirmação de que o MV3 “matou os bloqueadores de anúncios” não é totalmente precisa — embora o modelo de filtragem seja genuinamente mais restritivo do que as abordagens da era MV2, e o uBlock Origin original permaneça exclusivo do MV2 por escolha de seu autor.

Sem Mais Código Hospedado Remotamente

Todo JavaScript executado por uma extensão MV3 deve estar incluído dentro do próprio pacote da extensão. Carregar código executável de um CDN ou API externa não é permitido. Isso torna cada extensão totalmente auditável no momento da revisão.

chrome.action API e a Offscreen API

As APIs browserAction e pageAction do MV2 foram unificadas em uma única API chrome.action no MV3. Ela gerencia o ícone da barra de ferramentas, o texto do badge e o popup em uma interface consistente.

Para casos em que você precisa de acesso ao DOM ou reprodução de áudio a partir de um contexto de background — coisas que um service worker não pode fazer — o MV3 fornece a Offscreen API. Ela permite criar um documento mínimo e oculto especificamente para essas tarefas, sem a sobrecarga de uma background page persistente completa. Segundo o Can I Use, as APIs offscreen relacionadas agora têm amplo suporte em navegadores modernos baseados em Chromium.

Como É um Manifest MV3 Mínimo

{
  "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/*"]
}

Observe que as host permissions agora são declaradas separadamente das permissions de API — uma mudança deliberada que dá aos usuários uma visibilidade mais clara sobre quais sites uma extensão pode acessar.

Conclusão

O Manifest V3 é uma plataforma mais restrita do que o MV2, e algumas dessas restrições exigem mudanças arquiteturais reais. Mas as restrições existem por motivos concretos: menor consumo de memória, ausência de código remoto não auditável e menor exposição do tráfego de rede bruto aos processos da extensão. Se você está começando uma nova extensão hoje, o MV3 é o único caminho prático suportado. Entender o ciclo de vida do service worker e o modelo declarativeNetRequest é onde esse trabalho começa.

FAQs

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.