Ràng buộc phiên bản dependency của plugin

Bài viết được dịch tự động từ bài viết gốc, chưa được kiểm tra lại bởi con người. Chỉ những bài viết có dấu tick xanh cạnh tiêu đề là đã được kiểm tra.

Một plugin có thể phụ thuộc vào plugin khác bằng cách liệt kê chúng trong plugin.json hoặc trong entry marketplace. Mặc định, một dependency luôn theo phiên bản mới nhất, nên một bản release upstream có thể đổi dependency dưới plugin của bạn mà không báo trước. Ràng buộc phiên bản (version constraint) giữ dependency ở một khoảng phiên bản đã test cho tới khi bạn chủ động chuyển.

Khi cài một plugin có khai báo dependency, Claude Code tự resolve và cài chúng, liệt kê dependency nào đã thêm ở cuối output cài đặt. Nếu một dependency sau đó bị mất, /reload-plugins và auto-update nền sẽ cài lại nó (miễn là marketplace của nó đã có trong danh sách marketplace đã cấu hình).

Trang này dành cho tác giả plugin khai báo dependency trong plugin.json và người quản trị marketplace tag release. Để cài plugin có dependency, xem Khám phá và cài plugin.

Vì sao cần ràng buộc phiên bản dependency

Xét ví dụ một marketplace nội bộ nơi hai team publish plugin. Team platform duy trì secrets-vault, một MCP server bọc secrets backend. Team deploy duy trì deploy-kit, gọi secrets-vault để lấy credential khi deploy.

deploy-kit được test với secrets-vault v2.1.0. Không có ràng buộc phiên bản, lần tiếp theo team platform tag một release đổi tên MCP tool, auto-update sẽ chuyển secrets-vault của mọi kỹ sư sang bản mới và deploy-kit sẽ hỏng.

Với ràng buộc phiên bản, deploy-kit khai báo cần secrets-vault trong khoảng ~2.1.0. Kỹ sư có deploy-kit cài sẽ ở lại bản patch 2.1.x cao nhất khớp. Team deploy tự nâng cấp theo lịch riêng bằng cách publish bản deploy-kit mới với ràng buộc rộng hơn.

Khai báo dependency có ràng buộc phiên bản

Liệt kê dependency trong mảng dependencies của .claude-plugin/plugin.json. Mỗi entry là tên plugin hoặc một object có ràng buộc phiên bản:

{
  "name": "deploy-kit",
  "version": "3.1.0",
  "dependencies": [
    "audit-logger",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}

Một entry có thể là string thuần chỉ tên plugin (như "audit-logger" ở trên), phụ thuộc vào bất kỳ phiên bản nào marketplace của nó cung cấp. Để kiểm soát chi tiết hơn, dùng object với các field:

Field	Kiểu	Mô tả
`name`	string	Tên plugin. Resolve trong cùng marketplace với plugin khai báo. Bắt buộc.
`version`	string	Một semver range như `~2.1.0`, `^2.0`, `>=1.4`, hoặc `=2.1.0`. Dependency được fetch ở phiên bản tag cao nhất khớp range này.
`marketplace`	string	Marketplace khác để resolve `name`. Dependency cross-marketplace bị chặn trừ khi marketplace target nằm trong `allowCrossMarketplaceDependenciesOn` của `marketplace.json` gốc.

Field version chấp nhận mọi biểu thức mà package semver của Node hỗ trợ. Phiên bản pre-release như 2.0.0-beta.1 bị loại trừ trừ khi range của bạn opt-in với hậu tố pre-release như ^2.0.0-0.

Đóng gói plugin cho team

Ngoài name bắt buộc, một plugin manifest có thể chỉ gồm mảng dependencies. Cài nó sẽ kéo theo mọi dependency, biến nó thành cách đóng gói một bộ plugin đã chọn lọc trong một lần cài:

{
  "name": "backend-standard",
  "version": "1.0.0",
  "description": "Bộ plugin chuẩn cho kỹ sư backend",
  "dependencies": [
    "secrets-vault",
    "deploy-kit",
    { "name": "db-migrate", "version": "^3.0" },
    "oncall-runbook"
  ]
}

Cài backend-standard sẽ resolve và cài cả bốn dependency.

Để thêm công cụ vào bộ chuẩn sau này, publish bản backend-standard mới có thêm dependency. Auto-update mặc định tắt cho marketplace không phải của Anthropic, nên kỹ sư nhận bản mới bằng một trong hai cách: bật auto-update cho marketplace trong /plugin, hoặc chạy claude plugin update backend-standard rồi /reload-plugins.

Để rollout bundle toàn tổ chức, thêm plugin bundle vào enabledPlugins trong managed settings.

Phụ thuộc plugin từ marketplace khác

Mặc định, Claude Code từ chối tự cài một dependency nằm ở marketplace khác với plugin khai báo nó, ngăn một marketplace âm thầm kéo theo plugin từ nguồn bạn chưa review.

Để cho phép, người quản trị marketplace gốc thêm tên marketplace target vào allowCrossMarketplaceDependenciesOn trong marketplace.json. Marketplace gốc là marketplace host plugin mà user đang cài; chỉ allowlist của nó được xét, nên trust không bắc cầu qua marketplace trung gian:

{
  "name": "acme-tools",
  "owner": { "name": "Acme" },
  "allowCrossMarketplaceDependenciesOn": ["acme-shared"],
  "plugins": [
    {
      "name": "deploy-kit",
      "source": "./deploy-kit",
      "dependencies": [
        { "name": "audit-logger", "marketplace": "acme-shared" }
      ]
    }
  ]
}

Nếu field này thiếu hoặc không có marketplace target, cài đặt lỗi với cross-marketplace nêu tên field cần đặt. User vẫn có thể cài dependency thủ công trước để thỏa ràng buộc mà không cần đổi allowlist.

Tag release plugin cho resolve phiên bản

Ràng buộc phiên bản resolve dựa trên git tag trên repository marketplace. Để Claude Code tìm được các phiên bản khả dụng của một dependency, release upstream phải tag theo quy ước tên cụ thể.

Tag mỗi release dạng {plugin-name}--v{version}, khớp field version trong plugin.json của commit đó. Từ thư mục plugin, chạy:

claude plugin tag --push

Lệnh claude plugin tag suy ra tên tag từ manifest plugin và entry marketplace bao quanh. Trước khi tạo tag, nó validate nội dung plugin, kiểm tra plugin.json và entry marketplace khớp phiên bản, yêu cầu working tree sạch dưới thư mục plugin, và từ chối nếu tag đã tồn tại.

--push push tag lên remote origin.
Nếu push lỗi, tag vẫn được tạo cục bộ và lệnh thoát với lỗi.
--dry-run in ra những gì sẽ được tag mà không tạo thật.

Chạy git tag secrets-vault--v2.1.0 trực tiếp tương đương nếu bạn tự giữ plugin.json và entry marketplace đồng bộ.

Khi bạn cài một plugin khai báo { "name": "secrets-vault", "version": "~2.1.0" }, Claude Code liệt kê tag của marketplace, lọc những tag bắt đầu bằng secrets-vault--v, và fetch phiên bản cao nhất thỏa ~2.1.0. Nếu không có tag khớp, plugin phụ thuộc bị disable kèm lỗi liệt kê phiên bản khả dụng.

Các ràng buộc tương tác với nhau ra sao

Khi nhiều plugin đã cài cùng ràng buộc một dependency, Claude Code giao (intersect) các range và resolve dependency về phiên bản cao nhất thỏa mãn tất cả. Bảng dưới minh họa các trường hợp thường gặp:

Plugin A yêu cầu	Plugin B yêu cầu	Kết quả
`^2.0`	`>=2.1`	Cài một bản ở tag `2.x` cao nhất từ `2.1.0` trở lên. Cả hai plugin load được.
`~2.1`	`~3.0`	Cài plugin B lỗi `range-conflict`. Plugin A và dependency giữ nguyên.
`=2.1.0`	không có	Dependency giữ ở `2.1.0`. Auto-update bỏ qua phiên bản mới hơn khi plugin A còn cài.

Khi bạn gỡ plugin cuối cùng ràng buộc một dependency, dependency đó thôi bị giữ và tiếp tục theo entry marketplace của nó ở lần update tiếp theo.

Bật/tắt plugin có dependency

Bật một plugin cũng bật các plugin nó phụ thuộc, và tắt một plugin bị chặn nếu plugin khác đang bật còn cần nó (yêu cầu Claude Code v2.1.143 trở lên).

Điều kiện	Kết quả
Một dependency chưa cài	Bật lỗi, in lệnh `claude plugin install` cho mỗi dependency thiếu
Một dependency bị chặn bởi chính sách plugin của tổ chức	Bật lỗi, nêu tên dependency bị chặn
Một dependency bị đặt `false` ở scope có độ ưu tiên cao hơn scope target	Bật lỗi. Bật dependency ở scope đó, hoặc truyền `--scope` để ghi vào đó
Mọi dependency đã cài và được phép	Bật thành công

Khi tắt một plugin, Claude Code từ chối nếu plugin khác đang bật vẫn phụ thuộc nó. Lỗi nêu tên các plugin phụ thuộc và cho một lệnh chuỗi tắt đúng thứ tự, kết thúc bằng plugin bạn yêu cầu:

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

Dọn dependency tự cài bị mồ côi

Dependency tự cài vẫn nằm trên đĩa sau khi plugin cài chúng bị gỡ. Chạy claude plugin prune để liệt kê và xóa các dependency tự cài không còn plugin nào cần (yêu cầu v2.1.121 trở lên):

claude plugin prune

Mặc định, prune hoạt động ở user scope và hỏi xác nhận trước khi xóa. --scope project/--scope local nhắm scope khác, --dry-run chỉ liệt kê, -y bỏ qua xác nhận.

Để prune như một phần của gỡ cài, truyền --prune vào claude plugin uninstall:

claude plugin uninstall deploy-kit --prune

Xử lý lỗi dependency

Lỗi	Ý nghĩa	Cách khắc phục
`dependency-unsatisfied`	Dependency khai báo chưa cài, hoặc đã cài nhưng disable	Chạy lệnh `claude plugin install` trong thông báo lỗi; thêm marketplace nếu chưa có
`range-conflict`	Yêu cầu phiên bản không thể kết hợp	Gỡ hoặc update một trong các plugin xung đột, sửa string `version` không hợp lệ, đơn giản hóa chuỗi `\|\|` dài
`dependency-version-unsatisfied`	Phiên bản dependency đã cài nằm ngoài range plugin này khai báo	Chạy `claude plugin install <dependency>@<marketplace>` để resolve lại
`no-matching-tag`	Repository dependency không có tag `{name}--v*` thỏa range	Kiểm tra upstream đã tag đúng quy ước, hoặc nới range của bạn

Để kiểm tra các lỗi này bằng lập trình, chạy claude plugin list --json.

Phuc Tran

Software Engineer | Learning Claude