Pular para o conteúdo principal
Um plugin pode depender de outros plugins listando-os em plugin.json ou em sua entrada de marketplace. Por padrão, uma dependência rastreia a versão mais recente disponível, portanto um lançamento upstream pode alterar a dependência sob seu plugin sem aviso. Restrições de versão permitem que você mantenha uma dependência em um intervalo de versão testado até que você escolha se mover. Quando você instala um plugin que declara dependências, Claude Code resolve e instala automaticamente e lista quais dependências foram adicionadas no final da saída de instalação. Este guia é para autores de plugins que declaram dependências em plugin.json e para mantenedores de marketplace que marcam lançamentos. Para instalar plugins que têm dependências, consulte Descobrir e instalar plugins. Para o esquema de manifesto completo, consulte a referência de Plugins.
Restrições de versão de dependência requerem Claude Code v2.1.110 ou posterior.

​
Por que restringir versões de dependências

Considere um marketplace interno onde dois times publicam plugins. O time de plataforma mantém secrets-vault, um servidor MCP que envolve um backend de segredos. O time de deploy mantém deploy-kit, que chama secrets-vault para buscar credenciais durante deploys. deploy-kit é testado contra secrets-vault v2.1.0. Sem uma restrição de versão, na próxima vez que o time de plataforma marcar um lançamento que renomeia uma ferramenta MCP, a atualização automática move secrets-vault de cada engenheiro para a nova versão e deploy-kit quebra. Com uma restrição de versão, deploy-kit declara que precisa de secrets-vault no intervalo ~2.1.0. Engenheiros com deploy-kit instalado permanecem na versão patch 2.1.x mais alta correspondente. O time de deploy faz upgrade em seu próprio cronograma publicando uma nova versão de deploy-kit com uma restrição mais ampla.

​
Declare uma dependência com uma restrição de versão

Liste dependências no array dependencies do plugin.json do seu plugin. Cada entrada é um nome de plugin ou um objeto com uma restrição de versão. O manifesto a seguir declara uma dependência sem versão e uma dependência restrita:
.claude-plugin/plugin.json
{
  "name": "deploy-kit",
  "version": "3.1.0",
  "dependencies": [
    "audit-logger",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}
Uma entrada pode ser uma string simples com apenas o nome do plugin, como "audit-logger" no exemplo acima, que depende de qualquer versão que o marketplace desse plugin forneça. Para mais controle, use um objeto com estes campos:
CampoTipoDescrição
namestringNome do plugin. Resolve dentro do mesmo marketplace que o plugin declarante. Obrigatório.
versionstringUm intervalo semver como ~2.1.0, ^2.0, >=1.4, ou =2.1.0. A dependência é buscada na versão marcada mais alta que satisfaz este intervalo.
marketplacestringUm marketplace diferente para resolver name. Dependências entre marketplaces são bloqueadas a menos que o marketplace de destino esteja listado em allowCrossMarketplaceDependenciesOn no marketplace.json do marketplace raiz.
O campo version aceita qualquer expressão suportada pelo pacote semver do Node, incluindo intervalos de circunflexo, til, hífen e comparador. Versões pré-lançamento como 2.0.0-beta.1 são excluídas a menos que seu intervalo opte por um sufixo pré-lançamento como ^2.0.0-0.

​
Dependa de um plugin de outro marketplace

Por padrão, Claude Code recusa auto-instalar uma dependência que vive em um marketplace diferente do plugin que a declara. Isso evita que um marketplace puxe silenciosamente plugins de uma fonte que você não revisou. Para permitir, o mantenedor do marketplace raiz adiciona o nome do marketplace de destino a allowCrossMarketplaceDependenciesOn em marketplace.json. O marketplace raiz é aquele que hospeda o plugin que o usuário está instalando; apenas sua lista de permissões é consultada, portanto a confiança não se encadeia através de marketplaces intermediários. O seguinte marketplace.json permite que deploy-kit dependa de um plugin de 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 o campo estiver faltando ou não incluir o marketplace de destino, a instalação falha com um erro cross-marketplace nomeando o campo a ser definido. Os usuários ainda podem instalar a dependência manualmente primeiro, o que satisfaz a restrição sem alterar a lista de permissões.

​
Marque lançamentos de plugins para resolução de versão

Restrições de versão resolvem contra tags git no repositório do marketplace. Para Claude Code encontrar as versões disponíveis de uma dependência, os lançamentos do plugin upstream devem ser marcados usando uma convenção de nomenclatura específica. Marque cada lançamento como {plugin-name}--v{version}, onde {version} corresponde ao campo version no plugin.json daquele commit. 
git tag secrets-vault--v2.1.0
git push origin secrets-vault--v2.1.0
O prefixo de nome do plugin permite que um repositório de marketplace hospede múltiplos plugins com linhas de versão independentes. O separador --v é analisado como uma correspondência de prefixo no nome completo do plugin, portanto nomes de plugins que contêm hífens são tratados corretamente. Quando você instala um plugin que declara { "name": "secrets-vault", "version": "~2.1.0" }, Claude Code lista as tags do marketplace, filtra aquelas começando com secrets-vault--v, e busca a versão mais alta satisfazendo ~2.1.0. Se nenhuma tag correspondente existir, o plugin dependente é desabilitado com um erro listando as versões disponíveis.
Para fontes de marketplace npm, a restrição não controla qual versão é buscada, já que a resolução baseada em tag se aplica apenas a fontes apoiadas por git. A restrição ainda é verificada no tempo de carregamento, e o plugin dependente é desabilitado com dependency-version-unsatisfied se a versão instalada não a satisfizer.

​
Como restrições interagem

Quando vários plugins instalados restringem a mesma dependência, Claude Code intersecciona seus intervalos e resolve a dependência para a versão mais alta que satisfaz todos eles. A tabela abaixo mostra como combinações comuns resolvem.
Plugin A requerPlugin B requerResultado
^2.0>=2.1Uma instalação na tag 2.x mais alta em ou acima de 2.1.0. Ambos os plugins carregam.
~2.1~3.0Instalação do plugin B falha com range-conflict. Plugin A e a dependência permanecem como estavam.
=2.1.0nenhumA dependência permanece em 2.1.0. Auto-update pula versões mais recentes enquanto plugin A está instalado.
Auto-update verifica cada dependência restrita contra o intervalo de cada plugin instalado antes de aplicar uma atualização. Se o marketplace move uma dependência para uma versão fora de qualquer intervalo, a atualização é pulada e a mensagem de pulo nomeia o plugin restringidor. Quando você desinstala o último plugin que restringe uma dependência, a dependência não é mais mantida e retoma o rastreamento de sua entrada de marketplace na próxima atualização.

​
Resolva erros de dependência

Problemas de dependência aparecem em claude plugin list, na interface /plugin, e em /doctor. O plugin afetado é desabilitado até que você resolva o erro. Os erros mais comuns e suas correções estão listados abaixo.
ErroSignificadoComo resolver
range-conflictOs requisitos de versão para uma dependência não podem ser combinados. A mensagem de erro nomeia a causa: nenhuma versão satisfaz todos os intervalos, um intervalo não é sintaxe semver válida, ou os intervalos combinados são muito complexos para interseccionar.Desinstale ou atualize um dos plugins conflitantes, corrija qualquer string version inválida, simplifique cadeias || longas, ou peça ao autor upstream para ampliar sua restrição.
dependency-version-unsatisfiedA versão da dependência instalada está fora do intervalo declarado deste plugin.Execute claude plugin install <dependency>@<marketplace> para re-resolver a dependência contra todas as restrições atuais.
no-matching-tagO repositório da dependência não tem uma tag {name}--v* satisfazendo o intervalo.Verifique se o upstream marcou lançamentos usando a convenção acima, ou relaxe seu intervalo.
Para verificar esses erros programaticamente, execute claude plugin list --json e leia o campo errors em cada plugin.

​
Veja também