Vai al contenuto principale
Un plugin può dipendere da altri plugin elencandoli in plugin.json o nella sua voce del marketplace. Per impostazione predefinita, una dipendenza traccia la versione più recente disponibile, quindi un rilascio upstream può modificare la dipendenza del tuo plugin senza preavviso. I vincoli di versione ti permettono di mantenere una dipendenza a un intervallo di versione testato fino a quando non scegli di passare a una versione più recente. Quando installi un plugin che dichiara dipendenze, Claude Code le risolve e le installa automaticamente ed elenca quali dipendenze sono state aggiunte alla fine dell’output di installazione. Questa guida è per gli autori di plugin che dichiarano dipendenze in plugin.json e per i manutentori del marketplace che taggano i rilasci. Per installare plugin che hanno dipendenze, vedi Scopri e installa plugin. Per lo schema completo del manifest, vedi il Riferimento dei plugin.
I vincoli di versione delle dipendenze richiedono Claude Code v2.1.110 o successivo.

​
Perché vincolare le versioni delle dipendenze

Considera un marketplace interno in cui due team pubblicano plugin. Il team della piattaforma mantiene secrets-vault, un server MCP che avvolge un backend di segreti. Il team di deploy mantiene deploy-kit, che chiama secrets-vault per recuperare le credenziali durante i deploy. deploy-kit è testato rispetto a secrets-vault v2.1.0. Senza un vincolo di versione, la prossima volta che il team della piattaforma tagga un rilascio che rinomina uno strumento MCP, l’aggiornamento automatico sposta secrets-vault di ogni ingegnere alla nuova versione e deploy-kit si rompe. Con un vincolo di versione, deploy-kit dichiara che ha bisogno di secrets-vault nell’intervallo ~2.1.0. Gli ingegneri con deploy-kit installato rimangono sulla patch 2.1.x più alta corrispondente. Il team di deploy esegue l’aggiornamento secondo il proprio programma pubblicando una nuova versione di deploy-kit con un vincolo più ampio.

​
Dichiara una dipendenza con un vincolo di versione

Elenca le dipendenze nell’array dependencies del file .claude-plugin/plugin.json del tuo plugin. Ogni voce è un nome di plugin o un oggetto con un vincolo di versione. Il seguente manifest dichiara una dipendenza senza versione e una dipendenza vincolata:
.claude-plugin/plugin.json
{
  "name": "deploy-kit",
  "version": "3.1.0",
  "dependencies": [
    "audit-logger",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}
Una voce può essere una stringa semplice con solo il nome del plugin, come "audit-logger" nell’esempio sopra, che dipende da qualsiasi versione fornita dal marketplace di quel plugin. Per un maggiore controllo, usa un oggetto con questi campi:
CampoTipoDescrizione
namestringNome del plugin. Si risolve all’interno dello stesso marketplace del plugin dichiarante. Obbligatorio.
versionstringUn intervallo semver come ~2.1.0, ^2.0, >=1.4, o =2.1.0. La dipendenza viene recuperata alla versione taggata più alta che soddisfa questo intervallo.
marketplacestringUn marketplace diverso in cui risolvere name. Le dipendenze cross-marketplace sono bloccate a meno che il marketplace di destinazione non sia elencato in allowCrossMarketplaceDependenciesOn nel file marketplace.json del marketplace root.
Il campo version accetta qualsiasi espressione supportata dal pacchetto semver di Node, inclusi intervalli caret, tilde, hyphen e comparator. Le versioni pre-release come 2.0.0-beta.1 sono escluse a meno che il tuo intervallo non opti per un suffisso pre-release come ^2.0.0-0.

​
Dipendi da un plugin di un altro marketplace

Per impostazione predefinita, Claude Code rifiuta di installare automaticamente una dipendenza che si trova in un marketplace diverso da quello del plugin che la dichiara. Questo impedisce a un marketplace di estrarre silenziosamente plugin da una fonte che non hai revisionato. Per consentirlo, il manutentore del marketplace root aggiunge il nome del marketplace di destinazione a allowCrossMarketplaceDependenciesOn in marketplace.json. Il marketplace root è quello che ospita il plugin che l’utente sta installando; solo la sua lista di autorizzazione viene consultata, quindi la fiducia non si propaga attraverso i marketplace intermedi. Il seguente marketplace.json consente a deploy-kit di dipendere da un plugin di acme-shared:
.claude-plugin/marketplace.json
{
  "name": "acme-tools",
  "owner": { "name": "Acme" },
  "allowCrossMarketplaceDependenciesOn": ["acme-shared"],
  "plugins": [
    {
      "name": "deploy-kit",
      "source": "./deploy-kit",
      "dependencies": [
        { "name": "audit-logger", "marketplace": "acme-shared" }
      ]
    }
  ]
}
Se il campo è mancante o non include il marketplace di destinazione, l’installazione fallisce con un errore cross-marketplace che nomina il campo da impostare. Gli utenti possono comunque installare manualmente la dipendenza per prima, il che soddisfa il vincolo senza modificare la lista di autorizzazione.

​
Tagga i rilasci dei plugin per la risoluzione della versione

I vincoli di versione si risolvono rispetto ai tag git nel repository del marketplace. Affinché Claude Code trovi le versioni disponibili di una dipendenza, i rilasci del plugin upstream devono essere taggati usando una convenzione di denominazione specifica. Tagga ogni rilascio come {plugin-name}--v{version}, dove {version} corrisponde al campo version nel file plugin.json di quel commit. 
git tag secrets-vault--v2.1.0
git push origin secrets-vault--v2.1.0
Il prefisso del nome del plugin consente a un repository del marketplace di ospitare più plugin con linee di versione indipendenti. Il separatore --v viene analizzato come una corrispondenza di prefisso sul nome completo del plugin, quindi i nomi dei plugin che contengono trattini vengono gestiti correttamente. Quando installi un plugin che dichiara { "name": "secrets-vault", "version": "~2.1.0" }, Claude Code elenca i tag del marketplace, filtra quelli che iniziano con secrets-vault--v e recupera la versione più alta che soddisfa ~2.1.0. Se non esiste un tag corrispondente, il plugin dipendente viene disabilitato con un errore che elenca le versioni disponibili.
Per le fonti del marketplace npm, il vincolo non controlla quale versione viene recuperata, poiché la risoluzione basata su tag si applica solo alle fonti supportate da git. Il vincolo viene comunque controllato al momento del caricamento e il plugin dipendente viene disabilitato con dependency-version-unsatisfied se la versione installata non lo soddisfa.

​
Come i vincoli interagiscono

Quando più plugin installati vincolano la stessa dipendenza, Claude Code interseca i loro intervalli e risolve la dipendenza alla versione più alta che soddisfa tutti loro. La tabella seguente mostra come si risolvono le combinazioni comuni.
Plugin A richiedePlugin B richiedeRisultato
^2.0>=2.1Un’installazione al tag 2.x più alto a o sopra 2.1.0. Entrambi i plugin si caricano.
~2.1~3.0L’installazione del plugin B fallisce con range-conflict. Plugin A e la dipendenza rimangono come erano.
=2.1.0nessunoLa dipendenza rimane a 2.1.0. L’aggiornamento automatico salta le versioni più recenti mentre il plugin A è installato.
L’aggiornamento automatico controlla ogni dipendenza vincolata rispetto all’intervallo di ogni plugin installato prima di applicare un aggiornamento. Se il marketplace sposta una dipendenza a una versione al di fuori di qualsiasi intervallo, l’aggiornamento viene saltato e il messaggio di salto nomina il plugin vincolante. Quando disinstalli l’ultimo plugin che vincola una dipendenza, la dipendenza non viene più mantenuta e riprende a tracciare la sua voce del marketplace al prossimo aggiornamento.

​
Risolvi gli errori delle dipendenze

I problemi di dipendenza emergono in claude plugin list, nell’interfaccia /plugin e in /doctor. Il plugin interessato viene disabilitato fino a quando non risolvi l’errore. Gli errori più comuni e le loro correzioni sono elencati di seguito.
ErroreSignificatoCome risolvere
range-conflictI requisiti di versione per una dipendenza non possono essere combinati. Il messaggio di errore nomina la causa: nessuna versione soddisfa tutti gli intervalli, un intervallo non è una sintassi semver valida, o gli intervalli combinati sono troppo complessi da intersecare.Disinstalla o aggiorna uno dei plugin in conflitto, correggi qualsiasi stringa version non valida, semplifica le catene || lunghe, o chiedi all’autore upstream di ampliare il suo vincolo.
dependency-version-unsatisfiedLa versione della dipendenza installata è al di fuori dell’intervallo dichiarato di questo plugin.Esegui claude plugin install <dependency>@<marketplace> per ri-risolvere la dipendenza rispetto a tutti i vincoli attuali.
no-matching-tagIl repository della dipendenza non ha un tag {name}--v* che soddisfa l’intervallo.Verifica che l’upstream abbia taggato i rilasci usando la convenzione sopra, o rilassa il tuo intervallo.
Per controllare questi errori a livello di programmazione, esegui claude plugin list --json e leggi il campo errors su ogni plugin.

​
Vedi anche