Converter XPI para CRX

Um add-on do Firefox ou Thunderbird fornecido como um XPI não pode ser instalado diretamente no Chrome, Edge, Brave ou outros navegadores baseados em Chromium. Um pacote CRX é útil apenas depois que a fonte da extensão tiver sido tornada compatível com a plataforma de extensões do navegador de destino.

O que os arquivos XPI contêm

XPI é o formato de pacote de add-ons da Mozilla, usado principalmente pelo Firefox e Thunderbird. A maioria dos XPIs atuais são arquivos baseados em ZIP que contêm manifest.json, JavaScript, HTML, ícones, arquivos de localização e outros recursos da extensão.

Add-ons do Firefox distribui XPIs assinados. Add-ons mais antigos podem, em vez disso, usar install.rdf, chrome.manifest, overlays XUL ou código bootstrap legado; essas tecnologias não são compatíveis com Chromium e exigem nova implementação, em vez de reempacotamento.

O que os arquivos CRX fornecem

CRX é o formato de pacote de extensão assinado do Chromium. Navegadores Chromium atuais criam pacotes CRX3, cuja chave de assinatura determina o ID da extensão; manter essa chave é necessário para publicar atualizações com o mesmo ID.

O CRX é principalmente útil para implantação em navegadores gerenciados e serviços privados de atualização. A Chrome Web Store aceita um ZIP da fonte de extensão compatível para publicação, não um CRX pré-compilado, e instalações normais do Chrome geralmente bloqueiam a instalação direta de arquivos CRX baixados.

Prepare a fonte da extensão

1. Copie e extraia o XPI para uma pasta de trabalho. Use 7-Zip no Windows, ou execute unzip addon.xpi -d addon-src no macOS ou Linux. Renomear uma cópia de addon.xpi para addon.zip também permite a extração por ferramentas padrão de arquivo.
2. Verifique manifest.json. Um add-on que contém apenas arquivos legados da Mozilla não pode se tornar uma extensão funcional do Chromium sem uma migração do código-fonte.
3. Adapte o manifest e o código para o navegador de destino. Remova ou isole configurações do manifest apenas do Firefox como browser_specific_settings, substitua permissões e APIs não suportadas e use Manifest V3 quando necessário. As submissões atuais na Chrome Web Store exigem Manifest V3; a disponibilidade do Manifest V2 em navegadores Chromium depende da versão do navegador e da política corporativa.
4. Revise as diferenças de API. Código do Firefox que usa browser.* pode precisar de alterações direcionadas ou de webextension-polyfill para compatibilidade com Chromium. APIs apenas do Firefox, páginas privilegiadas, comportamento de proxy, recursos de tema e nomes de permissões podem não ter equivalente no Chromium.
5. Teste a pasta não empacotada antes de empacotar. Abra chrome://extensions, edge://extensions ou a página equivalente do navegador; habilite Developer mode; escolha Load unpacked; e selecione addon-src. Resolva primeiro erros do manifest, do service-worker, de permissões e de runtime.

Crie o pacote CRX

Use o navegador Chromium de destino ou o próprio Chromium para empacotar a pasta testada. Na página de extensões, habilite Developer mode, selecione Pack extension, escolha a pasta raiz da extensão e crie uma nova chave ou selecione a chave .pem existente.

Uma alternativa via linha de comando é chromium --pack-extension=/full/path/addon-src. No Windows, use o executável do navegador instalado, por exemplo chrome.exe --pack-extension="C:\work\addon-src". O empacotamento cria um arquivo .crx e, para um novo pacote, uma .pem (chave privada).

Mantenha o arquivo PEM em sigilo e faça backup. Recompile com a mesma chave, por exemplo chromium --pack-extension=/full/path/addon-src --pack-extension-key=/full/path/addon-src.pem. Uma nova chave cria um novo ID de extensão e quebra a continuidade das atualizações.

Limites de implantação e conversão

A assinatura de um XPI não pode ser reutilizada para a assinatura de CRX. Extrair um XPI fornece arquivos de origem, não uma assinatura Chromium transferível ou identidade de extensão.

Para distribuição pública no Chrome, envie o ZIP da fonte compatível para a Chrome Web Store. Para dispositivos gerenciados pela organização, implemente o CRX por meio da política corporativa de instalação de extensões do navegador e, quando necessário, uma URL de atualização aprovada.

Conversores de arquivo online não conseguem portar APIs do navegador, validar o comportamento da extensão ou gerar uma identidade de assinatura de longo prazo utilizável. Não envie a fonte da extensão nem chaves privadas .pem para um site de conversão; use ferramentas locais como 7-Zip e Chrome, Edge ou o empacotador de extensões do Chromium.