Langsung ke konten utama
Sebuah plugin dapat bergantung pada plugin lain dengan mencantumkannya di plugin.json atau di entri marketplacenya. Secara default, dependensi melacak versi terbaru yang tersedia, sehingga rilis upstream dapat mengubah dependensi di bawah plugin Anda tanpa peringatan. Batasan versi memungkinkan Anda menahan dependensi pada rentang versi yang telah diuji sampai Anda memilih untuk pindah. Ketika Anda menginstal plugin yang mendeklarasikan dependensi, Claude Code menyelesaikan dan menginstal dependensi tersebut secara otomatis dan mencantumkan dependensi mana yang ditambahkan di akhir output instalasi. Panduan ini ditujukan untuk penulis plugin yang mendeklarasikan dependensi di plugin.json dan untuk pengelola marketplace yang menandai rilis. Untuk menginstal plugin yang memiliki dependensi, lihat Temukan dan instal plugin. Untuk skema manifes lengkap, lihat Referensi Plugin.
Batasan versi dependensi memerlukan Claude Code v2.1.110 atau lebih baru.

​
Mengapa membatasi versi dependensi

Pertimbangkan marketplace internal di mana dua tim menerbitkan plugin. Tim platform memelihara secrets-vault, server MCP yang membungkus backend rahasia. Tim deploy memelihara deploy-kit, yang memanggil secrets-vault untuk mengambil kredensial selama deploy. deploy-kit diuji terhadap secrets-vault v2.1.0. Tanpa batasan versi, saat tim platform menandai rilis berikutnya yang mengganti nama alat MCP, auto-update memindahkan secrets-vault setiap insinyur ke versi baru dan deploy-kit rusak. Dengan batasan versi, deploy-kit mendeklarasikan bahwa ia memerlukan secrets-vault dalam rentang ~2.1.0. Insinyur dengan deploy-kit yang diinstal tetap berada di patch 2.1.x tertinggi yang cocok. Tim deploy meningkatkan sesuai jadwal mereka sendiri dengan menerbitkan versi deploy-kit baru dengan batasan yang lebih luas.

​
Deklarasikan dependensi dengan batasan versi

Cantumkan dependensi dalam array dependencies dari plugin.json plugin Anda. Setiap entri adalah nama plugin atau objek dengan batasan versi. Manifes berikut mendeklarasikan satu dependensi tanpa versi dan satu dependensi terbatas:
.claude-plugin/plugin.json
{
  "name": "deploy-kit",
  "version": "3.1.0",
  "dependencies": [
    "audit-logger",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}
Entri dapat berupa string kosong dengan hanya nama plugin, seperti "audit-logger" dalam contoh di atas, yang bergantung pada versi apa pun yang disediakan marketplace plugin tersebut. Untuk kontrol lebih, gunakan objek dengan bidang-bidang ini:
BidangTipeDeskripsi
namestringNama plugin. Diselesaikan dalam marketplace yang sama dengan plugin yang mendeklarasikan. Diperlukan.
versionstringRentang semver seperti ~2.1.0, ^2.0, >=1.4, atau =2.1.0. Dependensi diambil pada versi tertinggi yang ditandai yang memenuhi rentang ini.
marketplacestringMarketplace berbeda untuk menyelesaikan name di dalamnya. Dependensi lintas-marketplace diblokir kecuali marketplace target tercantum dalam allowCrossMarketplaceDependenciesOn di marketplace.json marketplace root.
Bidang version menerima ekspresi apa pun yang didukung oleh paket semver Node, termasuk rentang caret, tilde, hyphen, dan comparator. Versi pra-rilis seperti 2.0.0-beta.1 dikecualikan kecuali rentang Anda memilih dengan sufiks pra-rilis seperti ^2.0.0-0.

​
Bergantung pada plugin dari marketplace lain

Secara default, Claude Code menolak untuk auto-install dependensi yang berada di marketplace berbeda dari plugin yang mendeklarasikannya. Ini mencegah satu marketplace secara diam-diam menarik plugin dari sumber yang belum Anda tinjau. Untuk mengizinkannya, pengelola marketplace root menambahkan nama marketplace target ke allowCrossMarketplaceDependenciesOn di marketplace.json. Marketplace root adalah yang menghosting plugin yang diinstal pengguna; hanya daftar putihnya yang dikonsultasikan, sehingga kepercayaan tidak berantai melalui marketplace perantara. marketplace.json berikut memungkinkan deploy-kit bergantung pada plugin dari 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" }
      ]
    }
  ]
}
Jika bidang hilang atau tidak menyertakan marketplace target, instalasi gagal dengan kesalahan cross-marketplace yang menamai bidang yang akan diatur. Pengguna masih dapat menginstal dependensi secara manual terlebih dahulu, yang memenuhi batasan tanpa mengubah daftar putih.

​
Tandai rilis plugin untuk resolusi versi

Batasan versi diselesaikan terhadap tag git di repositori marketplace. Agar Claude Code menemukan versi yang tersedia dari dependensi, rilis plugin upstream harus ditandai menggunakan konvensi penamaan tertentu. Tandai setiap rilis sebagai {plugin-name}--v{version}, di mana {version} cocok dengan bidang version di plugin.json commit tersebut. 
git tag secrets-vault--v2.1.0
git push origin secrets-vault--v2.1.0
Awalan nama plugin memungkinkan satu repositori marketplace menghosting beberapa plugin dengan lini versi independen. Pemisah --v diuraikan sebagai pencocokan awalan pada nama plugin lengkap, sehingga nama plugin yang berisi tanda hubung ditangani dengan benar. Ketika Anda menginstal plugin yang mendeklarasikan { "name": "secrets-vault", "version": "~2.1.0" }, Claude Code mencantumkan tag marketplace, memfilter ke yang dimulai dengan secrets-vault--v, dan mengambil versi tertinggi yang memenuhi ~2.1.0. Jika tidak ada tag yang cocok, plugin dependen dinonaktifkan dengan kesalahan yang mencantumkan versi yang tersedia.
Untuk sumber marketplace npm, batasan tidak mengontrol versi mana yang diambil, karena resolusi berbasis tag hanya berlaku untuk sumber yang didukung git. Batasan masih diperiksa pada waktu muat, dan plugin dependen dinonaktifkan dengan dependency-version-unsatisfied jika versi yang diinstal tidak memenuhinya.

​
Bagaimana batasan berinteraksi

Ketika beberapa plugin yang diinstal membatasi dependensi yang sama, Claude Code memotong rentang mereka dan menyelesaikan dependensi ke versi tertinggi yang memenuhi semuanya. Tabel di bawah menunjukkan bagaimana kombinasi umum diselesaikan.
Plugin A memerlukanPlugin B memerlukanHasil
^2.0>=2.1Satu instalasi pada tag 2.x tertinggi pada atau di atas 2.1.0. Kedua plugin dimuat.
~2.1~3.0Instalasi plugin B gagal dengan range-conflict. Plugin A dan dependensi tetap seperti sebelumnya.
=2.1.0tidak adaDependensi tetap di 2.1.0. Auto-update melewati versi yang lebih baru saat plugin A diinstal.
Auto-update memeriksa setiap dependensi terbatas terhadap rentang setiap plugin yang diinstal sebelum menerapkan pembaruan. Jika marketplace memindahkan dependensi ke versi di luar rentang apa pun, pembaruan dilewati dan pesan lewati menamai plugin yang membatasi. Ketika Anda mencopot plugin terakhir yang membatasi dependensi, dependensi tidak lagi ditahan dan melanjutkan pelacakan entri marketplacenya pada pembaruan berikutnya.

​
Selesaikan kesalahan dependensi

Masalah dependensi muncul di claude plugin list, di antarmuka /plugin, dan di /doctor. Plugin yang terpengaruh dinonaktifkan sampai Anda menyelesaikan kesalahan. Kesalahan paling umum dan perbaikannya tercantum di bawah.
KesalahanArtiCara menyelesaikan
range-conflictPersyaratan versi untuk dependensi tidak dapat digabungkan. Pesan kesalahan menamai penyebabnya: tidak ada versi yang memenuhi semua rentang, rentang bukan sintaks semver yang valid, atau rentang gabungan terlalu kompleks untuk dipotongan.Copot atau perbarui salah satu plugin yang bertentangan, perbaiki string version yang tidak valid, sederhanakan rantai || panjang, atau minta penulis upstream untuk memperluas batasannya.
dependency-version-unsatisfiedVersi dependensi yang diinstal berada di luar rentang yang dideklarasikan plugin ini.Jalankan claude plugin install <dependency>@<marketplace> untuk menyelesaikan kembali dependensi terhadap semua batasan saat ini.
no-matching-tagRepositori dependensi tidak memiliki tag {name}--v* yang memenuhi rentang.Periksa bahwa upstream telah menandai rilis menggunakan konvensi di atas, atau relakskan rentang Anda.
Untuk memeriksa kesalahan ini secara terprogram, jalankan claude plugin list --json dan baca bidang errors pada setiap plugin.

​
Lihat juga