Claude Code 外掛 plugin.json 新增 engines:以前版本不夠要等載入失敗才知道,現在安裝更新就先擋,可是舊版看不懂這個欄位
寫外掛的人如果想告訴使用者「這個外掛要 Claude Code 某個版本以上才跑得動」,在 v2.1.323 之前,manifest 裡沒有官方欄位可以放這句話。
這是從兩個地方讀出來的。v2.1.323 的 release note 用的動詞是 Added,也就是這個欄位是那一版才新增的。而文件另外寫了,v2.0.15 到 v2.1.75 的版本碰到這個鍵會直接拒絕整份 manifest,等於那些舊版根本不認識它。
那以前的作者怎麼辦?我沒有找到 11 月 12 日之前、明文教人「手動寫版本要求」的舊文件快照,所以接下來「以前」那一半,是我拿旁證推出來的,不是官方曾經說過的話。先把旁證擺出來。
以前:版本門檻只存在於人的腦袋
文件在談 userConfig 的 options 時,有這麼一句:「If you declare options on any field, users on Claude Code versions before v2.1.271 can’t load the plugin.」宣告了 options,v2.1.271 以前的使用者就載入不了。
這句話的位置很有意思。它是寫給外掛作者看的警告,說你用了這個功能,就會把一批使用者擋在門外。可是警告只是警告,manifest 裡沒有任何欄位能讓你把「v2.1.271 以上」這個條件交給程式去判斷。
所以我的推論是這樣:以前版本不夠的使用者,經驗是外掛直接載入失敗;要讓他們事先知道,作者只能在 README 或發布說明裡寫一句「請升級」,再期待有人讀。這比較像食譜上手寫一行「烤箱要 200 度以上」,烤箱本身不會看。
上面這段「以前怎麼做」是推論。證據只有兩條:release note 對 engines 用的是 Added,以及文件裡 userConfig 那句 v2.1.271 的警告。我沒有看到舊版文件逐字寫過「請在 README 註明版本」。
現在:烤箱自己看食譜
截至 11 月 17 日,這個欄位上線五天了(v2.1.323,11 月 12 日發布)。release note 的原文是:
Added
engines["claude-code"]toplugin.json: plugins outside their stated Claude Code version range are not installed, updated or loaded, and install and update pick the newest version that fits
文件對欄位的寫法,值是 npm 風格的 semver range,放在 claude-code 這個鍵底下,文件給的例子長這樣:
1 | { |
這個 >=2.1.400 是文件的範例,不是某個外掛的真實設定。
把兩個時代放在一起對照,變的是「誰來判斷」。以前判斷的人是使用者,而且發現得晚,是載入失敗的那一刻。現在判斷的人換成 Claude Code 自己,時間點提前到安裝與更新,動作是「不安裝、不更新、不載入」。同一個條件,從一句提醒變成一道門。
release note 後半句我想多停一下:install 和 update 會挑「符合範圍的最新版」。這句話預設了同一個外掛有好幾個版本,而且各版宣告的範圍不一樣。我的讀法是,作者可以讓新版外掛宣告 >= 較高的 Claude Code 版本,舊版外掛維持原樣,使用者的 Claude Code 自己去挑它能裝的那一版。這是我對這句話的解讀,release note 沒有舉這個例子。選版本這件事,跟外掛彼此依賴時怎麼選版是同一個味道,我在 你的外掛依賴別人的外掛,Claude Code 怎麼決定要裝哪一版 拆過 dependencies 那一邊,這篇不重講。
擋舊版的欄位,舊版看不懂
文件裡有一句,我讀了兩遍:
Requires Claude Code v2.1.323 or later. To keep the plugin working on v2.0.15 through v2.1.75, omit
engines. Those versions reject the manifest with anUnrecognized keyerror when it has the field
要讓外掛繼續在 v2.0.15 到 v2.1.75 上跑,就別寫 engines,因為那些版本看到不認得的鍵會報 Unrecognized key,整份 manifest 被拒。
你寫 engines 的目的,是擋掉太舊的 Claude Code。但太舊的版本,恰恰是不認得這個欄位的版本。欄位只在讀得懂它的版本上生效;在 v2.0.15 到 v2.1.75 這批手上,它不是沒反應,是直接把外掛弄壞。
再往下推一步,這是我自己的推論,文件沒有這樣說。engines 這道門,只有 v2.1.323 以上的版本會去看,所以下限寫在 2.1.323 以下的部分,這道門本身看不到。拿前面的 userConfig 當例子:外掛用了 options,下限照理是 >=2.1.271,可是 v2.1.323 以前的版本讀不懂 engines,>=2.1.271 這個條件它們也就沒機會執行。至於 v2.1.76 到 v2.1.322 碰到這個鍵實際會怎樣,文件只講了 v2.0.15 到 v2.1.75 會報錯,中間那一段它沒說,標「未查證」。
我的取捨
要不要寫,看你的使用者分布。外掛還想照顧 v2.1.75 以前的人,就別寫,這是文件自己給的退路。外掛只服務比較新的環境,或者你已經準備好用多個版本分流,寫上去才划算,因為那時它能把「載入失敗」換成「安裝階段就清楚擋下」。
換句話說,寫 engines 等於同時做兩件事:把不合的新環境擋在外面,也放棄還在舊版的那批人。動手前,我會先把後者算清楚。會讓我改變想法的條件有兩個:文件之後說明 v2.0.15 到 v2.1.75 的版本其實能容忍這個鍵,或者有人實際驗出安裝路徑對超出範圍的外掛沒有擋,那「現在是一道門」這句話就得整個重寫。
這篇我只讀了 v2.1.323 的 release note 與官方 plugins-reference 文件,沒有實際跑過。「不安裝、不更新、不載入」以及「挑符合範圍的最新版」都只是照 release note 原文轉述,我沒有走過 marketplace 的安裝與更新流程驗證。「v2.0.15 到 v2.1.75 回 Unrecognized key」同樣只引文件,我手上沒有那些舊版可以跑。文件引文取自現行版,我沒有比對過 11 月 17 日當天的版本。
回到那個烤箱。以前食譜是一張紙,寫著「要 200 度以上」,燒壞了才知道誰沒看。現在食譜上多了一欄機器看得懂的溫度要求,烤箱讀得懂就自己決定開不開工。真正改的是責任的位置:從「作者提醒、使用者自己顧」搬到「外掛自己說清楚、本體負責拒絕」。這一搬留下一個還沒解的洞,就是讀不懂這一欄的舊烤箱,沒有人替它們把關。你手上的外掛要不要寫這一行,我會先查自己的使用者裡,有多少人還停在 v2.1.322 以前,再決定寫不寫。
原文來源:Claude Code v2.1.323 release、Plugins reference - Claude Code Docs


















