Zum Hauptinhalt springen
Ein Plugin kann von anderen Plugins abhängen, indem es diese in plugin.json oder in seinem Marketplace-Eintrag auflistet. Standardmäßig verfolgt eine Abhängigkeit die neueste verfügbare Version, sodass eine vorgelagerte Veröffentlichung die Abhängigkeit Ihres Plugins ohne Warnung ändern kann. Versionsbeschränkungen ermöglichen es Ihnen, eine Abhängigkeit in einem getesteten Versionsbereich zu halten, bis Sie sich entscheiden, sie zu aktualisieren. Wenn Sie ein Plugin installieren, das Abhängigkeiten deklariert, löst Claude Code diese automatisch auf und installiert sie. Am Ende der Installationsausgabe wird aufgelistet, welche Abhängigkeiten hinzugefügt wurden. Diese Anleitung ist für Plugin-Autoren, die Abhängigkeiten in plugin.json deklarieren, und für Marketplace-Verwalter, die Versionen taggen. Um Plugins mit Abhängigkeiten zu installieren, siehe Plugins entdecken und installieren. Für das vollständige Manifest-Schema siehe die Plugins-Referenz.
Versionsbeschränkungen für Abhängigkeiten erfordern Claude Code v2.1.110 oder später.

​
Warum Versionsbeschränkungen verwenden

Stellen Sie sich einen internen Marketplace vor, auf dem zwei Teams Plugins veröffentlichen. Das Platform-Team verwaltet secrets-vault, einen MCP-Server, der ein Secrets-Backend umhüllt. Das Deploy-Team verwaltet deploy-kit, das secrets-vault aufruft, um während Deployments Anmeldedaten abzurufen. deploy-kit wird gegen secrets-vault v2.1.0 getestet. Ohne Versionsbeschränkung führt die nächste Veröffentlichung des Platform-Teams, die ein MCP-Tool umbenennt, dazu, dass die automatische Aktualisierung secrets-vault auf die neue Version für jeden Ingenieur aktualisiert und deploy-kit bricht. Mit einer Versionsbeschränkung deklariert deploy-kit, dass es secrets-vault im Bereich ~2.1.0 benötigt. Ingenieure mit installiertem deploy-kit bleiben auf der höchsten passenden 2.1.x-Patch-Version. Das Deploy-Team aktualisiert nach eigenem Zeitplan, indem es eine neue deploy-kit-Version mit einer breiteren Beschränkung veröffentlicht.

​
Abhängigkeit mit Versionsbeschränkung deklarieren

Listet Abhängigkeiten im dependencies-Array der plugin.json Ihres Plugins auf. Jeder Eintrag ist entweder ein Plugin-Name oder ein Objekt mit einer Versionsbeschränkung. Das folgende Manifest deklariert eine unversionierte Abhängigkeit und eine beschränkte Abhängigkeit:
.claude-plugin/plugin.json
{
  "name": "deploy-kit",
  "version": "3.1.0",
  "dependencies": [
    "audit-logger",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}
Ein Eintrag kann ein einfacher String mit nur dem Plugin-Namen sein, wie "audit-logger" im obigen Beispiel, das von der Version abhängt, die der Marketplace dieses Plugins bereitstellt. Für mehr Kontrolle verwenden Sie ein Objekt mit diesen Feldern:
FeldTypBeschreibung
namestringPlugin-Name. Wird im selben Marketplace wie das deklarierte Plugin aufgelöst. Erforderlich.
versionstringEin semver-Bereich wie ~2.1.0, ^2.0, >=1.4 oder =2.1.0. Die Abhängigkeit wird in der höchsten getaggten Version abgerufen, die diesen Bereich erfüllt.
marketplacestringEin anderer Marketplace, um name darin aufzulösen. Marketplace-übergreifende Abhängigkeiten sind blockiert, es sei denn, der Ziel-Marketplace ist in allowCrossMarketplaceDependenciesOn in der marketplace.json des Root-Marketplace aufgelistet.
Das version-Feld akzeptiert jeden Ausdruck, der vom semver-Paket von Node unterstützt wird, einschließlich Caret-, Tilde-, Bindestrich- und Vergleichsbereiche. Vorabversionen wie 2.0.0-beta.1 sind ausgeschlossen, es sei denn, Ihr Bereich entscheidet sich mit einem Vorabversions-Suffix wie ^2.0.0-0 dafür.

​
Abhängigkeit von einem Plugin aus einem anderen Marketplace

Standardmäßig weigert sich Claude Code, eine Abhängigkeit automatisch zu installieren, die sich in einem anderen Marketplace als das Plugin befindet, das sie deklariert. Dies verhindert, dass ein Marketplace stillschweigend Plugins aus einer Quelle abruft, die Sie nicht überprüft haben. Um dies zu ermöglichen, fügt der Verwalter des Root-Marketplace den Namen des Ziel-Marketplace zu allowCrossMarketplaceDependenciesOn in marketplace.json hinzu. Der Root-Marketplace ist derjenige, der das Plugin hostet, das der Benutzer installiert. Nur seine Allowlist wird konsultiert, daher vertraut nicht durch zwischengelagerte Marketplaces. Die folgende marketplace.json ermöglicht es deploy-kit, von einem Plugin aus acme-shared abhängig zu sein:
.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" }
      ]
    }
  ]
}
Wenn das Feld fehlt oder den Ziel-Marketplace nicht enthält, schlägt die Installation mit einem cross-marketplace-Fehler fehl, der das zu setzende Feld benennt. Benutzer können die Abhängigkeit immer noch manuell zuerst installieren, was die Beschränkung erfüllt, ohne die Allowlist zu ändern.

​
Plugin-Versionen für Versionsauflösung taggen

Versionsbeschränkungen werden gegen Git-Tags im Marketplace-Repository aufgelöst. Damit Claude Code die verfügbaren Versionen einer Abhängigkeit findet, müssen die Versionen des vorgelagerten Plugins mit einer bestimmten Namenskonvention getaggt werden. Taggen Sie jede Veröffentlichung als {plugin-name}--v{version}, wobei {version} dem version-Feld in der plugin.json dieses Commits entspricht. 
git tag secrets-vault--v2.1.0
git push origin secrets-vault--v2.1.0
Das Plugin-Namen-Präfix ermöglicht es einem Marketplace-Repository, mehrere Plugins mit unabhängigen Versionslinien zu hosten. Der --v-Trennzeichen wird als Präfix-Übereinstimmung auf dem vollständigen Plugin-Namen analysiert, sodass Plugin-Namen, die Bindestriche enthalten, korrekt behandelt werden. Wenn Sie ein Plugin installieren, das { "name": "secrets-vault", "version": "~2.1.0" } deklariert, listet Claude Code die Tags des Marketplace auf, filtert diejenigen, die mit secrets-vault--v beginnen, und ruft die höchste Version ab, die ~2.1.0 erfüllt. Wenn kein passender Tag vorhanden ist, wird das abhängige Plugin mit einem Fehler deaktiviert, der die verfügbaren Versionen auflistet.
Für npm-Marketplace-Quellen steuert die Beschränkung nicht, welche Version abgerufen wird, da die Tag-basierte Auflösung nur auf Git-gestützten Quellen gilt. Die Beschränkung wird immer noch zur Ladezeit überprüft, und das abhängige Plugin wird mit dependency-version-unsatisfied deaktiviert, wenn die installierte Version sie nicht erfüllt.

​
Wie Beschränkungen interagieren

Wenn mehrere installierte Plugins dieselbe Abhängigkeit beschränken, schneidet Claude Code ihre Bereiche ab und löst die Abhängigkeit zur höchsten Version auf, die alle erfüllt. Die folgende Tabelle zeigt, wie häufige Kombinationen aufgelöst werden.
Plugin A erfordertPlugin B erfordertErgebnis
^2.0>=2.1Eine Installation auf dem höchsten 2.x-Tag bei oder über 2.1.0. Beide Plugins werden geladen.
~2.1~3.0Installation von Plugin B schlägt mit range-conflict fehl. Plugin A und die Abhängigkeit bleiben wie sie waren.
=2.1.0keineDie Abhängigkeit bleibt bei 2.1.0. Die automatische Aktualisierung überspringt neuere Versionen, während Plugin A installiert ist.
Die automatische Aktualisierung überprüft jede beschränkte Abhängigkeit gegen den Bereich jedes installierten Plugins, bevor eine Aktualisierung angewendet wird. Wenn der Marketplace eine Abhängigkeit zu einer Version außerhalb eines Bereichs verschiebt, wird die Aktualisierung übersprungen und die Übersprungsmeldung benennt das einschränkende Plugin. Wenn Sie das letzte Plugin deinstallieren, das eine Abhängigkeit beschränkt, wird die Abhängigkeit nicht mehr gehalten und verfolgt bei der nächsten Aktualisierung wieder ihren Marketplace-Eintrag.

​
Abhängigkeitsfehler beheben

Abhängigkeitsprobleme erscheinen in claude plugin list, in der /plugin-Schnittstelle und in /doctor. Das betroffene Plugin wird deaktiviert, bis Sie den Fehler beheben. Die häufigsten Fehler und deren Behebungen sind unten aufgelistet.
FehlerBedeutungWie zu beheben
range-conflictDie Versionsanforderungen für eine Abhängigkeit können nicht kombiniert werden. Die Fehlermeldung benennt die Ursache: Keine Version erfüllt alle Bereiche, ein Bereich ist keine gültige Semver-Syntax, oder die kombinierten Bereiche sind zu komplex zum Schneiden.Deinstallieren oder aktualisieren Sie eines der in Konflikt stehenden Plugins, beheben Sie alle ungültigen version-Strings, vereinfachen Sie lange ||-Ketten, oder bitten Sie den vorgelagerten Autor, seine Beschränkung zu erweitern.
dependency-version-unsatisfiedDie Version der installierten Abhängigkeit liegt außerhalb des deklarierten Bereichs dieses Plugins.Führen Sie claude plugin install <dependency>@<marketplace> aus, um die Abhängigkeit gegen alle aktuellen Beschränkungen neu aufzulösen.
no-matching-tagDas Repository der Abhängigkeit hat kein {name}--v*-Tag, das den Bereich erfüllt.Überprüfen Sie, dass die vorgelagerte Stelle Versionen mit der obigen Konvention getaggt hat, oder lockern Sie Ihren Bereich.
Um diese Fehler programmgesteuert zu überprüfen, führen Sie claude plugin list --json aus und lesen Sie das errors-Feld auf jedem Plugin.

​
Siehe auch