Converti XPI in CRX

Un add-on di Firefox o Thunderbird fornito come XPI non può essere installato direttamente in Chrome, Edge, Brave o altri browser basati su Chromium. Un pacchetto CRX è utile solo dopo che la sorgente dell’estensione è stata resa compatibile con la piattaforma di estensioni del browser di destinazione.

Cosa contengono i file XPI

XPI è il formato di pacchetto degli add-on di Mozilla, usato principalmente da Firefox e Thunderbird. La maggior parte delle XPIs attuali sono archivi basati su ZIP che contengono manifest.json, JavaScript, HTML, icone, file di localizzazione e altre risorse dell’estensione.

Gli Add-on di Firefox distribuiscono XPIs firmate. Gli add-on più vecchi possono invece usare install.rdf, chrome.manifest, overlay XUL o codice bootstrap legacy; queste tecnologie non sono supportate da Chromium e richiedono una rivisitazione (redevelopment) invece che un semplice ripacchettamento.

Cosa forniscono i file CRX

CRX è il formato di pacchetto di estensioni firmate di Chromium. I browser Chromium attuali creano pacchetti CRX3, in cui la chiave di firma determina l’ID dell’estensione; conservare quella chiave è necessario per pubblicare aggiornamenti con lo stesso ID.

CRX è principalmente utile per la distribuzione in modalità gestita (managed-browser) e per servizi di aggiornamento privati. Chrome Web Store accetta uno ZIP della sorgente di estensione compatibile per la pubblicazione, non un CRX precompilato, e le installazioni normali di Chrome in genere bloccano l’installazione diretta dei file CRX scaricati.

Preparare la sorgente dell’estensione

1. Copia ed estrai la XPI in una cartella di lavoro. Su Windows usa 7-Zip oppure esegui unzip addon.xpi -d addon-src su macOS o Linux. Rinominare una copia di addon.xpi in addon.zip consente anche l’estrazione con strumenti di archiviazione standard.
2. Verifica la presenza di manifest.json. Un add-on che contiene soltanto file Mozilla legacy non può diventare un’estensione Chromium funzionante senza una conversione della base di codice (porting).
3. Adatta il manifest e il codice per il browser di destinazione. Rimuovi o isola le impostazioni del manifest solo per Firefox come browser_specific_settings, sostituisci permessi e API non supportati e usa Manifest V3 quando richiesto. Le submission attuali di Chrome Web Store richiedono Manifest V3; la disponibilità di Manifest V2 nei browser Chromium dipende dalla versione del browser e dalla policy enterprise.
4. Rivedi le differenze tra API. Il codice Firefox che usa browser.* potrebbe richiedere modifiche mirate o webextension-polyfill per la compatibilità con Chromium. Le API solo Firefox, le pagine privilegiate, il comportamento del proxy, le capacità del tema e i nomi dei permessi potrebbero non avere un equivalente in Chromium.
5. Testa la cartella estratta prima del packaging. Apri chrome://extensions, edge://extensions o la pagina equivalente del browser; abilita Developer mode; scegli Load unpacked; e seleziona addon-src. Risolvi prima gli errori del manifest, del service-worker, dei permessi e in fase di runtime.

Creare il pacchetto CRX

Usa il browser Chromium di destinazione o Chromium stesso per impacchettare la cartella testata. Nella pagina delle estensioni abilita Developer mode, seleziona Pack extension, scegli la cartella root dell’estensione e crea una nuova chiave oppure seleziona l’esistente .pem.

Un’alternativa da riga di comando è chromium --pack-extension=/full/path/addon-src. Su Windows, usa l’eseguibile del browser installato, ad esempio chrome.exe --pack-extension="C:\work\addon-src". Il packaging crea un file .crx e, per un nuovo pacchetto, una chiave privata .pem.

Conserva il file PEM in privato e fai backup. Ricostruisci usando la stessa chiave, ad esempio chromium --pack-extension=/full/path/addon-src --pack-extension-key=/full/path/addon-src.pem. Una nuova chiave crea un nuovo ID dell’estensione e interrompe la continuità degli aggiornamenti.

Limiti di distribuzione e conversione

La firma di una XPI non può essere riutilizzata per la firma CRX. L’estrazione di una XPI fornisce file sorgente, non una firma Chromium trasferibile o l’identità dell’estensione.

Per la distribuzione pubblica di Chrome, carica lo ZIP della sorgente compatibile su Chrome Web Store. Per dispositivi gestiti dall’organizzazione, distribuisci la CRX tramite la policy enterprise del browser extension-install e, quando richiesto, un URL di aggiornamento approvato.

I convertitori di archivi online non possono portare le API del browser, validare il comportamento dell’estensione o generare un’identità di firma utilizzabile a lungo termine. Non caricare la sorgente dell’estensione o chiavi private .pem su un sito di conversione; usa strumenti locali come 7-Zip e Chrome, Edge o il packer di estensioni di Chromium.