/reload-plugins 時應用的規則。您也可以要求 Claude 閱讀此頁面並診斷您的設定。
這些情況涵蓋在其他頁面上：
- 安裝、啟用、停用和更新步驟：請參閱 安裝和管理 plugins
- 您有特定的錯誤訊息：請參閱 Plugin 疑難排解
- 您關閉的 plugin 仍然載入：找出 plugin 在何處啟用
- 更新沒有改變任何內容：版本和更新
- 您正在查看
~/.claude/plugins/下的檔案：在磁碟上找出 plugins --plugin-dirplugin 未載入，或載入了同名 plugin：名稱衝突
檢查 plugin 達到哪個階段
enabledPlugins 項目通過多個階段成為您可以使用的 plugin：您的設定宣告它、Claude Code 將其提取到磁碟，以及執行中的工作階段載入它。當 plugin 的行為與設定檔建議的不符時，檢查它達到了哪個階段：
- 已宣告，在設定中：
enabledPlugins說明哪些 plugins 應該開啟，extraKnownMarketplaces說明哪些市場應該存在。當您執行claude plugin marketplace add時，Claude Code 會將市場寫入您的使用者設定中的extraKnownMarketplaces以及磁碟 - 已提取，在
~/.claude/plugins/下的磁碟上：Claude Code 已提取的記錄和提取的檔案本身：known_marketplaces.json記錄每個 Claude Code 已提取的市場，包括其source、installLocation、lastUpdated和autoUpdate。每個使用者有一個known_marketplaces.json，因此您在一個專案中新增的市場在每個專案中都可用installed_plugins.json記錄每個安裝及其scope、installPath和versioncache/保存 plugin 檔案
- 已載入，在執行中的工作階段中：Claude Code 在啟動時或最後一次
/reload-plugins時載入的 plugin 集合。對設定或磁碟的更改不會到達此層，直到您執行/reload-plugins或啟動新工作階段。這就是為什麼claude plugin update以Restart to apply changes.結尾，背景更新會提示您Run /reload-plugins to apply
在工作階段啟動時不在磁碟上的 Plugins 和市場
Plugins 在工作階段啟動時從installed_plugins.json 和快取載入，無需使用網路。工作階段啟動後，Claude Code 在背景檢查宣告的市場：
- 設定宣告但
known_marketplaces.json缺少的市場：Claude Code 複製它，然後重新載入 plugins 並下載尚未快取的已啟用 plugins - 宣告的市場其來源在設定中已變更：Claude Code 從新來源重新提取它並顯示
Plugins changed. Run /reload-plugins to activate.
/plugin Errors 標籤中顯示 Plugin "<name>" not cached at <path>，claude plugin list 在同一行新增 — run /plugin to refresh。如需修復，請參閱 Plugin "<name>" not cached at <path>。
找出 plugin 來自何處
每個 plugin 都有形式為<name>@<origin> 的 id，這是您在設定檔和 claude plugin list --json 中看到的。@ 之後的部分告訴您 Claude Code 在何處找到 plugin：
對於市場 plugin，
<name> 是 marketplace.json 中的項目名稱；對於 @inline 和 @skills-dir，它是 plugin 清單中的 name。
此表中的來源名稱是保留的，因此沒有市場可以命名為 inline、skills-dir 或 synced。
項目名稱和清單名稱
市場 plugin 有兩個名稱，它們可能不同：marketplace.json中的項目名稱：安裝和啟用金鑰。它是您在enabledPlugins中寫入的內容、快取目錄的命名依據，以及claude plugin list顯示的內容- 清單中的
name：plugin 的元件命名空間所在的位置，以及 名稱衝突 比較的內容
透過儲存庫共享的 Plugins
若要透過儲存庫共享 plugin，請在.claude/settings.json 中的 enabledPlugins 下列出它，或將其放在 .claude/skills/ 下。Claude Code 不掃描專案的 .claude/plugins/ 目錄。
雲端工作階段不會新增儲存庫在 extraKnownMarketplaces 下列出的市場，因為這需要工作區信任對話框，雲端工作階段永遠不會顯示。
專案範圍的技能目錄 plugin 僅從工作階段 主要工作目錄 的 .claude/skills/ 載入，且僅在您接受該資料夾的 工作區信任對話框 後。它不會 搜尋父目錄直到儲存庫根目錄 的方式，就像純技能和命令一樣。如果您從子目錄啟動，儲存庫根目錄的 plugin 不會載入。改為從儲存庫根目錄啟動，或 使用 /cd 將工作階段移到那裡（v2.1.246 或更新版本）。
專案範圍的 plugin 被簽入儲存庫，並到達複製它的每個協作者。因為該內容來自儲存庫而不是來自您，它僅在應用於 .claude/settings.json 中專案允許規則的相同信任檢查後載入。信任父資料夾或使用 -p 執行是不夠的。執行程式碼的元件受到進一步限制：
- 它宣告的 MCP 伺服器通過 相同的每個伺服器核准 作為專案
.mcp.json - 它宣告為 MCP 套件 的 MCP 伺服器、
.mcpb或.dxt檔案，或來自 plugin 目錄外的檔案被跳過。在 plugin 目錄內內聯或在.mcp.json中宣告它們 - 背景監視器 不載入
--plugin-dir 和技能目錄 plugins，請參閱 建立 plugins。
從 claude.ai 同步的 Plugins
您為 claude.ai 帳戶開啟的 plugin 也會在 Claude Code 中載入，與您從市場安裝的 plugins 並排。這包括您的組織為其成員開啟的 plugins。這些 plugins 中的每一個都以<name>@synced 載入，沒有市場，也沒有 安裝記錄。
在終端工作階段中，同步 plugin 的技能、代理、hooks、MCP 伺服器和 LSP 伺服器都會載入，具有與您安裝的市場 plugin 相同的信任。
如需 Cowork 載入的元件，請參閱 claude.com 上的 claude.ai 和 Cowork 中的 Plugins。
同步 plugins 在 Cowork 工作階段和您使用 claude.ai 帳戶登入的終端工作階段中載入：
- Cowork：Claude Code 在工作階段啟動時將它們下載到工作階段自己的環境中
- 終端工作階段：每次您啟動 Claude Code 時，它在背景同步一次，下載新的和更新的 plugins，並移除您或您的組織關閉的 plugins。終端工作階段中的同步需要 Claude Code v2.1.273 或更新版本
終端工作階段中的同步時機
因為終端同步在背景執行，它可能在您的工作階段啟動後完成。當它在互動式工作階段中新增、更新或移除同步 plugin 時，您會看到Plugins changed. Run /reload-plugins to activate. 執行 /reload-plugins 以在該工作階段中載入變更，或將其留待下次啟動 Claude Code 時。
如果您在工作階段執行時在 claude.ai 上啟用 plugin，該 plugin 會在您下次啟動 Claude Code 時下載。
終端同步的登入要求
在您的終端中，plugins 僅在您使用 claude.ai 帳戶登入的工作階段中同步。 如果您在較早版本的 Claude Code 上登入，該登入不涵蓋 plugins，直到 Claude Code 在背景更新它。若要更快獲得存取權，請再次執行/login。Plugin 同步然後在您下次啟動 Claude Code 時開始。
控制哪些同步 plugins 載入
您可以一次關閉一個同步 plugin，除了您的組織要求的 plugin，或關閉機器上的每個同步 plugin：- 一個 plugin：在您的殼層中執行
claude plugin disable <name>@synced，工作階段中的/pluginInstalled 標籤都在您的使用者級別enabledPlugins中儲存"<name>@synced": false。若要在每個環境中將 plugin 保留在專案之外，在專案的已提交.claude/settings.json中設定相同的金鑰 - 機器上的每個同步 plugin：在您的使用者設定中設定
syncClaudeAiPlugins為false，或您的組織在 受管設定 中設定它。Claude Code 停止下載，下次啟動時，它將已同步的 plugins 移到~/.claude/plugins/.trash/，不再載入它們。如果您的組織在 claude.ai 上關閉技能，plugins 也會停止同步 - 您的組織要求的 plugin：您的組織在 claude.ai 上標記為必需的 plugin 即使您之前停用它也會載入。
claude plugin disable拒絕它，顯示Plugin "<name>@synced" is required by your organization and can't be disabled here. Contact your admin to change it.，claude plugin list將其標記為required by your org
找出 plugin 在何處啟用
您可以在六個來源中的任何一個設定enabledPlugins 項目。該表從最低優先順序到最高列出它們，以及每個適用於誰。如需設定檔本身，請參閱 設定檔和它們影響的人。
這些來源逐個金鑰合併。對於每個 plugin id，適用的值是來自提及該 id 的最高優先順序來源的值。不提及該 id 的來源會保留來自較低優先順序來源的值。
在使用者設定中停用但仍然載入
如果您在~/.claude/settings.json 中將 plugin 設定為 false，但它仍然載入，較高優先順序來源中的 true 會覆蓋它。plugin 在 claude plugin list 和 /plugin 中的行顯示 Disabled in ~/.claude/settings.json but still loads — project settings enable it, which overrides your user setting。該訊息命名覆蓋您的來源：project、project, gitignored（針對 .claude/settings.local.json）、cli flag 或 managed。
若要選擇退出您機器上的專案啟用 plugin，在 .claude/settings.local.json 中將 id 設定為 false，其優先順序高於專案檔案。
在專案設定中啟用但未安裝
當 plugin 的唯一true 在專案的 .claude/settings.json 中時，Claude Code 不會在未安裝它的機器上提取它，除非其市場項目具有 相對路徑來源 或 種子目錄 已經保存它。相反，/plugin Errors 標籤顯示 Plugin "<name>" is enabled in project settings but isn't installed here。
相對路徑 plugin 不需要安裝記錄，因為它從市場本身載入。
Claude Code 僅當以下來源之一將其設定為 true 時才提取具有外部來源的 plugin：
- 您的使用者設定
- git 不追蹤的
.claude/settings.local.json --settings旗標- 受管設定
在磁碟上找出 plugins
Claude Code 在一個 plugins 根目錄下保存 plugin 檔案和狀態記錄，該目錄是~/.claude/plugins，除非您設定 CLAUDE_CODE_PLUGIN_CACHE_DIR。表中的每個路徑都相對於該根目錄。
因為
${CLAUDE_PLUGIN_ROOT} 指向版本目錄，plugin 的根路徑隨著每個版本而變化。改為在 ${CLAUDE_PLUGIN_DATA} 中保存 plugin 的持久檔案。
就地和複製的 plugins
Claude Code 根據 plugins 的來源，從您保存它們的位置就地載入某些 plugins，並將其餘的複製到快取中：--plugin-dir和技能目錄 plugins：目錄就地載入，永遠不會被複製。--plugin-url存檔或--plugin-dir.zip首先被提取到工作階段臨時目錄中- 您從本地目錄新增的市場中的相對路徑 plugins：plugin 從其在市場資料夾內的路徑就地載入。您對來源目錄的編輯在下次工作階段啟動或
/reload-plugins時生效，您無需增加版本。plugin 的 hook 程序和 MCP 和 LSP 伺服器接收指向來源目錄的CLAUDE_PLUGIN_ROOT。如需其 Node.js 套件依賴項，請參閱 依賴項安裝何時執行 - 連結模式 中的
command來源 plugins：命令列印的目錄通過快取項目中的連結就地載入 - 每個其他市場 plugin：Claude Code 在安裝時將 plugin 複製到
cache/<marketplace>/<plugin>/<version>/中並從該副本載入。plugin 目錄外的檔案不被複製，因此當 plugin 內的指令碼讀取 plugin 根目錄上方的路徑（例如../shared）時，它找不到它們
逃逸 plugin 目錄的路徑
無論 plugin 就地載入還是從快取副本載入，Claude Code 都不允許它宣告其自己目錄外的元件。它拒絕解決為 plugin 根目錄外的元件路徑，無論路徑是在plugin.json 還是市場項目中宣告的：
- 指向 plugin 外部的路徑，如寫入的那樣，例如
../shared-utils - 導致 plugin 外部的符號連結，除了 一個市場內 plugins 之間的連結
- 在 macOS 和 Linux 上，路徑中任何地方包含反斜杠的路徑，即使路徑保留在 plugin 內。因此使用反斜杠路徑宣告的元件僅在 Windows 上載入，因此使用正斜杠編寫元件路徑，例如
./commands/deploy.md
path escapes plugin directory 錯誤，plugin 載入時不包含該元件。
舊版本的清理
當您更新或卸載 plugin 時，Claude Code 將.orphaned_at 標記寫入舊版本目錄。它在 14 天後的背景清理中移除該目錄，因此已載入舊版本的工作階段繼續執行。
掃描僅在 installed_plugins.json 記錄至少一個安裝時執行。卸載最後一個 plugin 後，孤立目錄保留，直到您安裝另一個。
Node.js 套件依賴項
當 Claude Code 將 plugin 複製到快取時，它也會在那裡安裝 plugin 的 Node.js 套件依賴項，以便 plugin 的 hooks 和 MCP 伺服器可以載入它們。 本部分涵蓋 plugin 在其自己的package.json 中宣告的 npm 和 Bun 套件。對於依賴其他 plugins 的 plugins，請參閱 plugin 依賴項版本。
依賴項安裝何時執行
Claude Code 在每次建立複製版本目錄時在其中執行安裝：- 當您安裝 plugin 時
- 當 Claude Code 將 plugin 更新到新版本時
- 在工作階段啟動時，當已啟用 plugin 尚未快取時，例如在新機器上
${CLAUDE_PLUGIN_DATA}。
安裝僅在 plugin 的根目錄同時包含 package.json 和支援的鎖定檔案時執行。鎖定檔案決定 Claude Code 執行的命令：
如果 plugin 包含多個這些鎖定檔案中的一個，Claude Code 使用第一個匹配項，按順序檢查：
bun.lock、bun.lockb、npm-shrinkwrap.json、package-lock.json。
Claude Code 跳過 Yarn 和 pnpm 鎖定檔案以及 Bun 鎖定檔案旁邊的 bunfig.toml 的安裝：
- 如果您的 plugin 只有
yarn.lock或pnpm-lock.yaml，請將其替換為 npm 鎖定檔案 - 如果
bunfig.toml在 Bun 鎖定檔案的同一目錄中，移除bunfig.toml，或將 Bun 鎖定檔案替換為 npm 鎖定檔案
npm-shrinkwrap.json，因為 npm 從已發佈的套件中排除 package-lock.json。
依賴項安裝的限制
Claude Code 限制此依賴項安裝，以便 plugin 或其套件中的任何程式碼在安裝期間不執行，並限制其執行時間：- 凍結解決：Bun 和 npm 安裝鎖定檔案精確固定的內容，當
package.json和鎖定檔案不同意時失敗而不是重新解決版本 - 無生命週期指令碼：
--ignore-scripts防止preinstall、install和postinstall指令碼執行，因此在這些指令碼中建立原生模組的依賴項在此安裝期間下載但不編譯 - 60 秒超時：Claude Code 停止執行超過 60 秒的安裝並將其視為失敗
依賴項安裝失敗或被跳過時
失敗或跳過的安裝永遠不會阻止 plugin，每種情況都留下不同的跡象：- 失敗的安裝或因 Yarn 或 pnpm 鎖定檔案或
bunfig.toml而跳過的安裝在claude --debug輸出中顯示為警告 - 具有
package.json和無鎖定檔案的 plugin 被跳過，沒有日誌項目 - 超時的安裝可以在快取副本中留下部分
node_modules樹
版本和更新
如果 plugin 的作者推送了新提交，claude plugin update 列印 <name> is already at the latest version (<version>).，Claude Code 為 plugin 計算的版本未變更，因此磁碟上沒有任何變更。
Claude Code 為它安裝的每個 plugin 計算版本，這就是它如何檢測更新的方式。claude plugin update 和背景自動更新再次計算版本，當它與 installed_plugins.json 記錄的內容匹配時跳過 plugin。
版本也命名 plugin 的快取目錄。
固定 "version" 的清單是計算的版本在提交中保持相同的一種方式。請參閱 Claude Code 如何計算版本 以了解解決順序。
從本地目錄市場 就地載入 的 plugin 在每次工作階段啟動時載入其當前來源檔案，無論其版本字串說什麼。對於從 在 claude.ai 上託管的市場 的 plugin，claude.ai 為 plugin 記錄的版本是其版本，清單的 version 不被讀取。
Claude Code 如何計算版本
對於您按來源新增的市場，Claude Code 按 plugin 市場項目的source 類型選擇規則。市場參考 列出來源類型。對於該列表中除 command 外的每個來源類型：
- plugin 清單中的
version欄位首先出現 - 然後 plugin 市場項目中的
version欄位 - 當都未設定時，版本來自來源類型：
Claude Code 不從包含安裝路徑的儲存庫（例如 git 管理的
~/.claude）取得版本。
對於 command 來源，Claude Code 始終從命令產生的內容衍生版本：其自己的 12 字元雜湊，或當清單設定一個時 <manifest version>-<hash>。市場項目的 version 對於命令來源被忽略。如需雜湊涵蓋的內容，請參閱 複製模式和連結模式。
因為清單首先出現，固定 "version": "1.0.0" 的清單將每個使用者保留在快取副本上，直到其作者更改字串，無論他們推送多少提交。若要讓使用者改為追蹤提交，請從清單和項目中都省略 version。託管市場 涵蓋哪個選擇適合哪個發佈設定。
Claude Code 何時在安裝前重新整理市場
當您安裝 plugin 時，Claude Code 在其市場目錄的本地副本中查找它。您可以在工作階段中執行/plugin install 或在殼層中執行 claude plugin install，並使用或不使用其市場命名 plugin。該表顯示這些組合中哪些重新整理本地副本。
name@marketplace 安裝前的重新整理不取決於市場的自動更新設定或 DISABLE_AUTOUPDATER。
當重新整理失敗時，安裝從快取目錄進行，claude plugin install 報告 marketplace not refreshed。
Claude Code 在以下情況下跳過 name@marketplace 安裝前的重新整理：
- 市場從本地
file或directory來源新增，或在設定中內聯定義，具有settings來源 - 種子目錄 提供市場
- Claude Code 在過去 30 秒內重新整理了市場
- 您設定
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC - 受管設定 阻止市場，在這種情況下 Claude Code 也拒絕安裝
自動更新何時執行
在互動式工作階段中，在您傳送第一條訊息後，Claude Code 等待最多十分鐘的隨機延遲。然後它重新整理每個啟用自動更新的市場，並更新從它們在磁碟上安裝的 plugins。 執行中的工作階段保留它載入的版本，您會看到Plugin updated: <name> · Run /reload-plugins to apply。無論您是否重新載入，新版本在您下次啟動時載入。
哪些市場和 plugins 自動更新
市場是否自動更新遵循首先設定的：- 其
extraKnownMarketplaces項目中的autoUpdate在設定檔中 - 其
known_marketplaces.json項目中的autoUpdate，/pluginMarketplaces 下的 Enable auto-update 切換寫入。當設定檔也在extraKnownMarketplaces下宣告市場時，切換也將autoUpdate寫入該設定項目 - 預設：對於 Anthropic 的官方市場（例如
claude-plugins-official）開啟，對於knowledge-work-plugins和first-party-plugins關閉，對於 從 claude.ai 新增的市場 開啟，對於每個其他市場關閉
DISABLE_UPDATES=1、DISABLE_AUTOUPDATER=1 或 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1，整個傳遞關閉，Enable auto-update 切換隱藏，除非您也設定 FORCE_AUTOUPDATE_PLUGINS=1。環境變數參考 涵蓋每個變數的更廣泛效果。
自動更新也跳過其市場項目宣告 headersHelper 的 plugin。拒絕命令而不是詢問的安裝和更新 解釋何時此類 plugin 出現在 /plugin Errors 標籤中以及如何從那裡更新它。
當複製的 plugin 在工作階段中期更新時，hook 命令、監視器、MCP 伺服器和 LSP 伺服器繼續使用舊版本的路徑。執行 /reload-plugins 以將 hooks、MCP 伺服器和 LSP 伺服器切換到新路徑。監視器需要工作階段重新啟動。
何時命令來源重新執行
具有command 來源的 Plugins 不等待 自動更新傳遞。列印的目錄反映工具在命令執行時的狀態，因此 Claude Code 在以下時間再次執行 您接受的命令：
- 每次您安裝或更新 plugin 時
- 每個已啟用命令來源 plugin 每個工作階段一次，在工作階段啟動後不久在背景中。此執行不取決於市場的自動更新設定或
DISABLE_AUTOUPDATER - 在啟動或
/reload-plugins時，當已啟用 plugin 的已安裝版本在 plugin 快取中遺失時
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC 時，Claude Code 跳過兩個背景執行。明確安裝和更新仍然使用該變數集執行命令。
當命令的雜湊輸出已變更時，Claude Code 將結果安裝為新版本，並在執行中的互動式工作階段中重新載入它，切換 /reload-plugins 切換的相同元件。您會看到 plugin 已重新載入的通知。
如果就地重新載入會使工作階段的提示快取失效，Claude Code 改為提示您執行 /reload-plugins，它 警告快取成本並在使用 --force 重新執行時應用。
名稱衝突
當來自不同來源的已啟用 plugins 共享清單名稱時，此順序決定哪一個載入，從最高優先順序到最低：- 其 id 出現在受管設定
enabledPlugins中的 plugin，如true或false。其清單名稱與 id 的名稱部分匹配的--plugin-dir副本不被載入，您會看到--plugin-dir copy of "<name>" ignored: plugin is locked by managed settings - 已啟用的
--plugin-dir、--plugin-url或CLAUDE_CODE_PLUGIN_DIRSplugin。它替換同名的已安裝市場 plugin 或技能目錄 plugin：- 已安裝的市場 plugin：無聲替換。
claude plugin list仍然顯示市場行為已啟用，因為該行反映您的設定。只有當您使用--debug啟動時 Claude Code 在~/.claude/debug/下寫入的日誌記錄Plugin "<name>" from --plugin-dir overrides installed version - 技能目錄 plugin：替換為
/pluginErrors 標籤行，讀取Not loaded — the name "<name>" is already taken by a session-only plugin (--plugin-dir / --plugin-url), which takes precedence
- 已安裝的市場 plugin：無聲替換。
- 已安裝的市場 plugin。同名的技能目錄 plugin 獲得相同的
Not loaded行，命名已安裝的 plugin - 技能目錄 plugin。在這兩者之間，
~/.claude/skills/下的副本載入，專案的.claude/skills/副本被丟棄，帶有一行說明哪個路徑遮蔽了它 - 從 claude.ai 同步的 plugin。當來自任何其他來源的已啟用 plugin 與其名稱匹配時，Claude Code 載入該 plugin 並報告同步副本未載入。若要改為使用 claude.ai 副本，停用您自己的副本
hello-plugin 的 --plugin-dir plugin 在該 plugin 的清單也說 "name": "hello-plugin" 時替換 hello@example-marketplace。
防止工作階段專用 plugin 載入
若要防止--plugin-dir plugin 遮蔽任何內容，或在父程序為您傳遞旗標時關閉一個，在任何設定檔中將其 id 設定為 false。對於清單名稱為 hello-plugin 的 plugin，項目是 "enabledPlugins": {"hello-plugin@inline": false}。停用的工作階段專用 plugin 不遮蔽，因此市場或技能目錄副本改為載入。
後續步驟
- 安裝和管理 plugins：安裝、啟用、停用和更新步驟本身
- Plugin 疑難排解：按產生它們的階段的錯誤訊息
- Plugin 命令參考：此頁面上命名的旗標和命令
- 為您的組織管理 plugins：強制啟用或阻止 plugins 的受管設定