Vincola le versioni delle dipendenze dei plugin

Dichiara vincoli di versione sulle dipendenze dei plugin e raggruppa un set di plugin curato dietro un'unica installazione.

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 consentono 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, ad eccezione di una dipendenza la cui voce del marketplace ha una command source o una headersHelper, che installi tu stesso per primo. Successivamente, /reload-plugins, l'aggiornamento automatico del marketplace del plugin dipendente, l'esecuzione nuova di claude plugin install sul plugin dipendente e claude plugin marketplace add installano ciascuno qualsiasi dipendenza dichiarata che non sia ancora installata, secondo le stesse regole; se una rimane non risolta, vedi Risolvi gli errori di dipendenza.

Questa guida è per gli autori di plugin che dichiarano dipendenze in plugin.json e per i manutentori del marketplace che taggano i rilasci. Le dipendenze qui sono altri plugin; per i pacchetti npm e Bun che un plugin stesso utilizza, vedi Dipendenze dei pacchetti Node.js. Per installare plugin che hanno dipendenze, vedi Scopri e installa plugin. Per lo schema completo del manifest, vedi il Riferimento dei plugin.

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.

Il seguente manifest dichiara una dipendenza senza versione e una dipendenza vincolata:

{
  "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:

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.

Raggruppare i plugin per un team

Oltre al name obbligatorio, un manifest di plugin può consistere solo in un array dependencies. L'installazione di questo plugin scarica tutte le dipendenze, il che lo rende un modo per raggruppare un set di plugin curato dietro un'unica installazione.

Ad esempio, un team di piattaforma può pubblicare bundle specifici per ruolo in un marketplace interno in modo che gli ingegneri eseguano un solo claude plugin install invece di installare ogni strumento separatamente:

{
  "name": "backend-standard",
  "version": "1.0.0",
  "description": "Standard plugin set for backend engineers",
  "dependencies": [
    "secrets-vault",
    "deploy-kit",
    { "name": "db-migrate", "version": "^3.0" },
    "oncall-runbook"
  ]
}

L'installazione di backend-standard risolve e installa tutte e quattro le dipendenze.

Per aggiungere uno strumento al set standard in seguito, pubblicare una nuova versione di backend-standard con la dipendenza aggiuntiva. L'auto-aggiornamento è disabilitato per impostazione predefinita per i marketplace non Anthropic, quindi gli ingegneri acquisiscono la nuova versione in uno di due modi:

• Abilitare l'auto-aggiornamento per il marketplace in /plugin. Il prossimo auto-aggiornamento sposta il bundle alla nuova versione e installa tutte le dipendenze che aggiunge.
• Eseguire claude plugin update backend-standard, quindi /reload-plugins per installare le dipendenze appena aggiunte.

Per distribuire i bundle in tutta l'organizzazione, aggiungere il plugin bundle a enabledPlugins nelle impostazioni gestite.

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:

{
  "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.

Testare un plugin e la sua dipendenza localmente

Se state sviluppando un plugin e il plugin da cui dipende contemporaneamente, caricate entrambi con --plugin-dir:

claude --plugin-dir ./my-dependency --plugin-dir ./my-plugin

La copia locale della dipendenza soddisfa la voce di dipendenza del vostro plugin, anche quando la voce nomina un marketplace, quindi non è necessario installare la dipendenza dal suo marketplace. Claude Code non controlla un vincolo di versione rispetto a una copia locale, quindi il plugin.json locale non ha bisogno di una version. Prima della v2.1.242, una voce di dipendenza che nominava un marketplace non corrispondeva mai alla copia locale, e Claude Code disabilitava il vostro plugin al caricamento.

Quando entrambi i plugin si trovano in una cartella padre, potete passare quella cartella a --plugin-dir una sola volta. Se la cartella non è essa stessa un plugin, Claude Code carica ogni cartella figlio che ha un .claude-plugin/plugin.json. Richiede Claude Code v2.1.265 o successivo.

Se non avete installato la dipendenza dal suo marketplace, il vostro plugin smette di caricarsi quando la copia locale scompare:

• Avete disabilitato la copia locale: Claude Code disabilita il vostro plugin al prossimo caricamento del plugin. Per una voce di dipendenza che nomina un marketplace, Claude Code segnala Dependency "<name>@inline" is disabled — enable it or remove the dependency; per una voce con nome semplice, la segnala per il suo nome semplice. <name>@inline è il modo in cui Claude Code identifica ogni plugin --plugin-dir e --plugin-url.
• Avete avviato una sessione senza il flag --plugin-dir della dipendenza: Claude Code segnala la dipendenza come non installata. Passate di nuovo il flag, oppure installate la dipendenza dal suo marketplace.

Rilasci di tag plugin per la risoluzione delle versioni

Claude Code risolve i vincoli di versione rispetto ai tag git nel repository che ospita la dipendenza: il repository del plugin stesso per le fonti plugin github, url e git-subdir, oppure il repository del marketplace per un plugin a cui il marketplace fa riferimento tramite un percorso relativo. Affinché Claude Code trovi le versioni disponibili di una dipendenza, i rilasci del plugin upstream devono essere taggati utilizzando una convenzione di denominazione specifica.

Tagga ogni rilascio come {plugin-name}--v{version}, dove {version} corrisponde al campo version nel plugin.json di quel commit. Dalla directory del plugin, esegui:

claude plugin tag --push

Il comando claude plugin tag deriva il nome del tag dal manifest del plugin e dalla voce del marketplace che lo contiene. Prima di creare il tag, convalida il contenuto del plugin, verifica che plugin.json e la voce del marketplace concordino sulla versione, richiede un albero di lavoro pulito nella directory del plugin e rifiuta se il tag esiste già.

• --push spinge il tag al remote origin, quindi il repository ha bisogno di un remote origin configurato. Passa --remote per spingere a uno diverso.
• Se lo spinta fallisce, il tag viene comunque creato localmente e il comando esce con un errore.
• Con --push, un'esecuzione riuscita termina con Created tag secrets-vault--v2.1.0 e Pushed to origin, dove l'ultima riga nomina il remote a cui è stato spinto. Senza --push, il comando stampa il comando git push da eseguire.
• --dry-run stampa ciò che verrebbe taggato senza crearlo.

Eseguire git tag secrets-vault--v2.1.0 direttamente è equivalente se mantieni plugin.json e la voce del marketplace sincronizzati da solo.

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 nel repository che ospita secrets-vault, filtra quelli che iniziano con secrets-vault--v e recupera la versione più alta che soddisfa ~2.1.0. Se nessun tag nel repository del plugin stesso soddisfa l'intervallo, l'installazione fallisce con Dependency "secrets-vault@acme-tools" has no git tag satisfying ~2.1.0, che nomina la dipendenza insieme al suo marketplace. Per un plugin con percorso relativo senza tag corrispondente, Claude Code installa la copia corrente del marketplace e verifica il vincolo quando il plugin viene caricato.

Per un plugin a cui il marketplace fa riferimento tramite un percorso relativo, un marketplace aggiunto come percorso di cartella locale risolve i tag nello stesso modo quando la cartella è un repository git. Ciò richiede Claude Code v2.1.196 o successivo. In due casi Claude Code installa la dipendenza dal contenuto corrente della cartella:

• Le versioni precedenti non leggono i tag da un marketplace di cartella locale, quindi una dipendenza vincolata viene caricata solo se quella copia soddisfa l'intervallo.
• Una cartella locale che non è un repository git non ha tag, indipendentemente dalla versione.

Il semver del tag risolto viene registrato separatamente dalla version di plugin.json, quindi i controlli dei vincoli utilizzano il tag che è stato effettivamente recuperato anche se plugin.json in quel commit ha un valore obsoleto. Il nome della directory della cache per un'installazione risolta da tag include un suffisso SHA commit di 12 caratteri, quindi se un manutentore sposta forzatamente un tag a un commit diverso, l'installazione successiva ottiene una directory della cache nuova invece di riutilizzare contenuto obsoleto.

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.

L'aggiornamento automatico recupera una dipendenza vincolata al tag git più alto che soddisfa l'intervallo di ogni plugin installato, piuttosto che alla versione più recente del marketplace, quindi la dipendenza continua a ricevere aggiornamenti all'interno del suo intervallo consentito. Se nessun tag soddisfa tutti gli intervalli, l'aggiornamento automatico salta quella dipendenza e elenca il salto nella scheda Errori di /plugin, nominando 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.

Abilita o disabilita un plugin con dipendenze

Questa sezione copre i plugin installati da un marketplace. Per una copia che hai caricato con --plugin-dir, vedi Testa un plugin e la sua dipendenza localmente.

L'abilitazione di un plugin abilita anche i plugin da cui dipende, e la disabilitazione di un plugin è bloccata se un altro plugin abilitato ne ha ancora bisogno.

Quando abiliti un plugin, Claude Code abilita anche le sue dipendenze nello stesso ambito. Se una dipendenza ha le sue dipendenze, Claude Code abilita anche quelle. Il messaggio di successo elenca cos'altro è stato abilitato insieme al plugin che hai denominato. Se una dipendenza non può essere abilitata, il comando rifiuta e ti dice cosa sta bloccando e come risolvere:

Questo vale anche quando una dipendenza imposta defaultEnabled: false nel suo manifest, perché Claude Code scrive un true esplicito per essa. Lo stesso vale all'installazione: una dipendenza richiamata per soddisfare un plugin attivo si installa con true indipendentemente dal suo valore predefinito.

Quando disabiliti un plugin, Claude Code rifiuta se un altro plugin abilitato ne dipende ancora. L'errore nomina i plugin che ne dipendono e ti fornisce un comando concatenato che li disabilita nell'ordine corretto, terminando con quello che hai richiesto.

Ad esempio, se deploy-kit dipende da secrets-vault, la disabilitazione di secrets-vault da sola fallisce con un output simile al seguente:

secrets-vault is still required by deploy-kit. Disable that plugin first, or
disable everything together: claude plugin disable deploy-kit@acme-tools && claude plugin disable secrets-vault@acme-tools

Copia il comando concatenato dall'errore per disabilitare l'intero set in un unico passaggio.

Rimuovi le dipendenze auto-installate orfane

Le dipendenze auto-installate rimangono su disco dopo che i plugin che le hanno installate vengono disinstallati, nel caso in cui tu voglia reinstallare un plugin dipendente o desideri continuare a utilizzare la dipendenza direttamente. Per pulirle, esegui claude plugin prune per elencare le dipendenze auto-installate che non hanno più alcun plugin installato che le richiede e rimuoverle dopo un prompt di conferma.

claude plugin prune

Se nulla si qualifica per la rimozione, il comando stampa Nothing to prune con il motivo ed esce. Questo è l'output previsto su un'installazione nuova, non un errore.

Per impostazione predefinita, prune opera a livello di utente e chiede conferma prima di rimuovere qualsiasi cosa:

• --scope project o --scope local indirizza un ambito diverso.
• --dry-run elenca cosa verrebbe rimosso senza modificare nulla.
• -y salta il prompt di conferma. Quando stdin o stdout non è un terminale, prune elenca gli orfani ed esce senza rimuoverli a meno che non venga passato -y.

Per eseguire prune come parte di una disinstallazione, passa --prune a claude plugin uninstall. Dopo aver rimosso il plugin denominato, Claude Code scansiona e rimuove eventuali dipendenze auto-installate che sono ora orfane. I plugin che hai installato tu stesso non vengono mai eliminati, solo quelli installati automaticamente attraverso l'array dependencies di un altro plugin.

Lo stesso comportamento di conferma si applica. Quando stdin o stdout non è un terminale, la disinstallazione si completa comunque, ma il passaggio prune elenca gli orfani e non rimuove nulla a meno che non venga passato -y.

Ad esempio, per disinstallare deploy-kit e pulire le dipendenze che lascia dietro:

claude plugin uninstall deploy-kit --prune

Risolvi gli errori delle dipendenze

I problemi di dipendenza emergono in claude plugin list e nell'interfaccia /plugin, come messaggi di errore descrittivi anziché i codici letterali in questa tabella. Claude Code disabilita il plugin interessato fino a quando non risolvi l'errore. La tabella seguente elenca gli errori più comuni e come risolverli.

Per controllare questi errori a livello di programmazione, esegui claude plugin list --json. I plugin con problemi includono un campo errors che li elenca. I plugin che si sono caricati correttamente omettono il campo.

Vedi anche

• Crea plugin: costruisci plugin con skills, agent e hooks
• Crea e distribuisci un marketplace di plugin: ospita plugin per il tuo team
• Riferimento dei plugin: lo schema completo di plugin.json
• Gestione delle versioni: come la versione di un plugin viene risolta e utilizzata come chiave di cache