插件加载参考

追踪 Claude Code 从何处加载每个插件，哪个设置文件决定是否加载，以及为什么更新没有产生任何变化。

当插件未加载、加载了与预期不同的副本，或未获取更新时，使用此页面查看哪个源、设置范围或磁盘上的文件决定了这一点。它提供了 Claude Code 在会话启动时和每次运行 /reload-plugins 时应用的规则。您也可以要求 Claude 阅读此页面并诊断您的设置。

从检查插件达到的阶段开始，了解已安装插件经过的三个阶段，或转到与您看到的情况相匹配的部分：

• 您关闭的插件仍然加载：查找插件的启用位置
• 更新没有产生任何变化：版本和更新
• 您正在查看 ~/.claude/plugins/ 下的文件：查找磁盘上的插件
• --plugin-dir 插件未加载，或加载了同名插件：名称冲突

检查插件达到的阶段

enabledPlugins 条目分阶段成为您可以使用的插件：您的设置声明它，Claude Code 将其获取到磁盘，运行中的会话加载它。当插件的行为与设置文件建议的不符时，检查它达到了哪个阶段：

• 已声明，在设置中：enabledPlugins 说明哪些插件应该打开，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 和 version
  • cache/ 保存插件文件
• 已加载，在运行中的会话中：Claude Code 在启动时或最后一次 /reload-plugins 时加载的插件集。对设置或磁盘的更改不会到达此层，直到您运行 /reload-plugins 或启动新会话。这就是为什么 claude plugin update 以 Restart to apply changes. 结尾，背景更新会提示您 Run /reload-plugins to apply

会话启动时磁盘上没有的插件和市场

插件在会话启动时从 installed_plugins.json 和缓存加载，不使用网络。会话启动后，Claude Code 在后台检查声明的市场：

• 设置声明但 known_marketplaces.json 缺少的市场：Claude Code 克隆它，然后重新加载插件并下载未缓存的已启用插件
• 声明的市场其源在设置中更改：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>。

查找插件的来源

每个插件都有形式为 <name>@<origin> 的 id，这是您在设置文件和 claude plugin list --json 中看到的。@ 之后的部分告诉您 Claude Code 在哪里找到了插件：

对于市场插件，<name> 是 marketplace.json 中的条目名称；对于 @inline 和 @skills-dir，它是插件清单中的 name。

此表中的源名称是保留的，因此没有市场可以命名为 inline、skills-dir 或 synced。

条目名称和清单名称

市场插件有两个名称，它们可能不同：

• marketplace.json 中的条目名称：安装和启用密钥。这是您在 enabledPlugins 中写入的内容，缓存目录的命名依据，以及 claude plugin list 显示的内容
• 清单中的 name：插件组件命名空间所在的位置，以及名称冲突比较的内容

通过存储库共享的插件

要通过存储库共享插件，请在 .claude/settings.json 中的 enabledPlugins 下列出它，或将其放在 .claude/skills/ 下。Claude Code 不扫描项目的 .claude/plugins/ 目录。

云会话不会添加存储库在 extraKnownMarketplaces 下列出的市场，因为这需要工作区信任对话框，云会话永远不会显示。

项目范围的技能目录插件仅从会话主工作目录的 .claude/skills/ 加载，并且仅在您接受该文件夹的工作区信任对话框后加载。它不会搜索从存储库根目录向上的父目录，就像普通技能和命令那样。如果您从子目录启动，存储库根目录中的插件不会加载。改为从存储库根目录启动，或 使用 /cd 将会话移到那里（v2.1.246 或更高版本）。

项目范围的插件被检入存储库，并到达克隆它的每个协作者。因为该内容来自存储库而不是来自您，它仅在应用于 .claude/settings.json 中项目允许规则的相同信任检查后加载。信任父文件夹或使用 -p 运行是不够的。运行代码的组件受到进一步限制：

• 它声明的 MCP 服务器经过与项目 .mcp.json 相同的每服务器批准
• 它声明为MCP 包、.mcpb 或 .dxt 文件或来自插件目录外文件的 MCP 服务器被跳过。内联声明它们或在插件目录内的 .mcp.json 中声明
• 后台监视器不加载

个人范围的插件没有这些限制。

有关如何编写 --plugin-dir 和技能目录插件，请参阅创建插件。

从 claude.ai 同步的插件

您为 claude.ai 账户打开的插件也会在 Claude Code 中加载，与您从市场安装的插件一起。这包括您的组织为其成员打开的插件。这些插件中的每一个都作为 <name>@synced 加载，没有市场，也没有安装记录。

在终端会话中，同步插件的技能、代理、hooks、MCP 服务器和 LSP 服务器都加载，具有与您安装的市场插件相同的信任。

有关 Cowork 加载的组件，请参阅 claude.com 上的claude.ai 和 Cowork 中的插件。

同步插件在 Cowork 会话和您使用 claude.ai 账户登录的终端会话中加载：

• Cowork：Claude Code 在会话启动时将它们下载到会话自己的环境中
• 终端会话：每次启动 Claude Code 时，它在后台同步一次，下载新的和更新的插件，并删除您或您的组织关闭的插件。终端会话中的同步需要 Claude Code v2.1.273 或更高版本

终端会话中的同步时间

因为终端同步在后台运行，它可能在您的会话启动后完成。当它在交互式会话中添加、更新或删除同步插件时，您会看到 Plugins changed. Run /reload-plugins to activate. 运行 /reload-plugins 以在该会话中加载更改，或将其留到下次启动 Claude Code 时。

如果您在会话运行时在 claude.ai 上启用插件，该插件将在下次启动 Claude Code 时下载。

终端同步的登录要求

在您的终端中，插件仅在您使用 claude.ai 账户登录的会话中同步。

如果您在早期版本的 Claude Code 上登录，该登录不会覆盖插件，直到 Claude Code 在后台续期。要更快获得访问权限，请再次运行 /login。插件同步然后在下次启动 Claude Code 时开始。

控制哪些同步插件加载

您可以逐个关闭同步插件，除了您的组织要求的插件，或关闭机器上的每个同步插件：

• 一个插件：在您的 shell 中运行 claude plugin disable <name>@synced，会话中 /plugin Installed 选项卡都在您的用户级enabledPlugins中保存 "<name>@synced": false。要在每个环境中将插件排除在项目之外，请在项目的已提交 .claude/settings.json 中设置相同的密钥
• 机器上的每个同步插件：在您的用户设置中设置 syncClaudeAiPlugins 为 false，或您的组织在托管设置中设置它。Claude Code 停止下载，下次启动时，它将已同步的插件移到 ~/.claude/plugins/.trash/，不再加载它们。如果您的组织在 claude.ai 上关闭技能，插件也会停止同步
• 您的组织要求的插件：您的组织在 claude.ai 上标记为必需的插件即使您之前禁用了它也会加载。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

有关在 claude.ai 上删除插件，请参阅管理已安装的插件。

查找插件的启用位置

您可以在六个源中的任何一个中设置 enabledPlugins 条目。该表从最低优先级到最高优先级列出它们，以及每个适用于谁。有关设置文件本身，请参阅设置文件及其影响的人。

这些源逐个密钥合并。对于每个插件 id，应用的值来自提及该 id 的最高优先级源。不提及该 id 的源将较低优先级源的值保留在有效状态。

在用户设置中禁用但仍然加载

如果您在 ~/.claude/settings.json 中将插件设置为 false 并且它仍然加载，较高优先级源中的 true 正在覆盖它。插件在 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。

要在您的机器上选择退出项目启用的插件，请在 .claude/settings.local.json 中将 id 设置为 false，它的优先级高于项目文件。

在项目设置中启用但未安装

当插件的唯一 true 在项目的 .claude/settings.json 中时，Claude Code 不会在未安装它的机器上获取它，除非其市场条目具有相对路径源或种子目录已经保存它。相反，/plugin Errors 选项卡显示 Plugin "<name>" is enabled in project settings but isn't installed here。

相对路径插件不需要安装记录，因为它从市场本身加载。

Claude Code 仅当以下源之一将其设置为 true 时才获取具有外部源的插件：

• 您的用户设置
• git 不跟踪的 .claude/settings.local.json
• --settings 标志
• 托管设置

查找磁盘上的插件

Claude Code 在一个插件根目录下保存插件文件和状态记录，该目录是 ~/.claude/plugins，除非您设置了 CLAUDE_CODE_PLUGIN_CACHE_DIR。表中的每个路径都相对于该根目录。

因为 ${CLAUDE_PLUGIN_ROOT} 指向版本目录，插件的根路径随每个版本更改。改为在 ${CLAUDE_PLUGIN_DATA} 中保留插件的持久文件。

就地和复制的插件

Claude Code 根据插件的来源，从您保存它们的位置就地加载某些插件，并将其余的复制到缓存中：

• --plugin-dir 和技能目录插件：目录就地加载，永远不会被复制。--plugin-url 存档或 --plugin-dir .zip 首先被提取到会话临时目录中
• 您从本地目录添加的市场中的相对路径插件：插件从市场文件夹内的其路径就地加载。您对源目录的编辑在下次会话启动或 /reload-plugins 时生效，您不需要增加版本。插件的 hook 进程以及 MCP 和 LSP 服务器接收指向源目录的 CLAUDE_PLUGIN_ROOT。有关其 Node.js 包依赖项，请参阅依赖项安装何时运行
• 链接模式中的 command 源插件：命令打印的目录通过缓存条目中的链接就地加载
• 每个其他市场插件：Claude Code 在安装时将插件复制到 cache/<marketplace>/<plugin>/<version>/ 中，并从该副本加载。插件目录外的文件不会被复制，因此当复制的插件内的脚本读取插件根目录上方的路径（如 ../shared）时，它找不到它们

逃逸插件目录的路径

无论插件就地加载还是从缓存副本加载，Claude Code 都不允许它声明其自己目录外的组件。它拒绝解析到插件根目录外的组件路径，无论路径是在 plugin.json 还是市场条目中声明的：

• 按书写指向插件外的路径，例如 ../shared-utils
• 导致插件外的符号链接，除了市场内插件之间的链接
• 在 macOS 和 Linux 上，路径中任何地方包含反斜杠的路径，即使路径保留在插件内。因此使用反斜杠路径声明的组件仅在 Windows 上加载，所以使用正斜杠编写组件路径，例如 ./commands/deploy.md

被拒绝的路径显示为path escapes plugin directory错误，插件加载时不包含该组件。

以前版本的清理

当您更新或卸载插件时，Claude Code 将 .orphaned_at 标记写入以前的版本目录。它在 14 天后的后台清理中删除该目录，因此已加载旧版本的会话继续运行。

扫描仅在 installed_plugins.json 记录至少一个安装时运行。卸载最后一个插件后，孤立目录保留到您安装另一个。

Node.js 包依赖项

当 Claude Code 将插件复制到缓存中时，它也会在那里安装插件的 Node.js 包依赖项，以便插件的 hooks 和 MCP 服务器可以加载它们。

本部分涵盖插件在其自己的 package.json 中声明的 npm 和 Bun 包。对于依赖其他插件的插件，请参阅插件依赖项版本。

依赖项安装何时运行

Claude Code 在创建复制的版本目录时在其内部运行安装：

• 当您安装插件时
• 当 Claude Code 将插件更新到新版本时
• 在会话启动时，当已启用的插件未缓存时，例如在新机器上

对于从本地目录市场就地加载的相对路径插件，Claude Code 不会将依赖项安装到源目录中。自己在那里安装它们，或从 hook 安装到${CLAUDE_PLUGIN_DATA}。

安装仅在插件的根目录同时包含 package.json 和支持的锁定文件时运行。锁定文件决定 Claude Code 运行的命令：

如果插件包含这些锁定文件中的多个，Claude Code 使用第一个匹配项，按顺序检查：bun.lock、bun.lockb、npm-shrinkwrap.json、package-lock.json。

Claude Code 跳过 Yarn 和 pnpm 锁定文件以及 Bun 锁定文件旁边的 bunfig.toml 的安装：

• 如果您的插件仅有 yarn.lock 或 pnpm-lock.yaml，请将其替换为 npm 锁定文件
• 如果 bunfig.toml 与 Bun 锁定文件在同一目录中，请删除 bunfig.toml，或将 Bun 锁定文件替换为 npm 锁定文件

包含 npm 锁定文件以到达最多用户。Claude Code 从用户的 PATH 运行匹配的锁定文件的包管理器，如果缺少该包管理器，不会尝试其他锁定文件。

对于通过 npm 源分发的插件，使用 npm-shrinkwrap.json，因为 npm 从已发布的包中排除 package-lock.json。

依赖项安装的限制

Claude Code 限制此依赖项安装，以便插件或其包中的任何代码在安装期间不执行，并限制其运行时间：

• 冻结解析：Bun 和 npm 安装锁定文件精确固定的内容，当 package.json 和锁定文件不一致时失败而不是重新解析版本
• 无生命周期脚本：--ignore-scripts 防止 preinstall、install 和 postinstall 脚本运行，因此在这些脚本中构建本机模块的依赖项在此安装期间下载但不编译
• 60 秒超时：Claude Code 停止运行超过 60 秒的安装并将其视为失败

Claude Code 在此依赖项安装之前获取 npm 源插件，包的任何自己的安装脚本在获取期间不运行。请参阅 npm 插件源。

您无法关闭自动安装。没有设置或环境变量禁用它。

在受限网络中，请参阅网络访问要求以允许的主机。

依赖项安装失败或被跳过时

失败或跳过的安装永远不会阻止插件，每种情况都留下不同的迹象：

• 失败的安装或因 Yarn 或 pnpm 锁定文件或 bunfig.toml 而跳过的安装在 claude --debug 输出中显示为警告
• 具有 package.json 且没有锁定文件的插件被跳过，没有日志条目
• 超时的安装可能在缓存副本中留下部分 node_modules 树

当自动安装无法提供依赖项时，从 hook 安装到持久数据目录。这包括需要其生命周期脚本来构建的包、Python 依赖项以及使用 Yarn 或 pnpm 锁定的插件。

版本和更新

如果插件的作者推送了新提交，claude plugin update 打印 <name> is already at the latest version (<version>).，Claude Code 为插件计算的版本未更改，因此磁盘上没有任何更改。

Claude Code 为它安装的每个插件计算一个版本，这就是它如何检测更新的方式。claude plugin update 和后台自动更新重新计算版本，当它与 installed_plugins.json 记录的内容匹配时跳过插件。

版本也命名插件的缓存目录。

固定 "version" 的清单是计算的版本在提交中保持相同的一种方式。有关解析顺序，请参阅Claude Code 如何计算版本。

从本地目录市场就地加载的插件在每次会话启动时加载其当前源文件，无论其版本字符串说什么。对于来自托管在 claude.ai 上的市场的插件，claude.ai 为插件记录的版本是其版本，清单的 version 不被读取。

Claude Code 如何计算版本

对于您添加的市场，Claude Code 按插件市场条目的 source 类型选择规则。市场参考列出源类型。对于该列表中除 command 外的每个源类型：

1. 插件清单中的 version 字段首先出现
2. 然后是插件市场条目中的 version 字段
3. 当都未设置时，版本来自源类型：

Claude Code 不从包含安装路径的存储库（如 git 管理的 ~/.claude）获取版本。

对于 command 源，Claude Code 始终从命令生成的内容派生版本：单独的 12 字符哈希，或当清单设置一个时的 <manifest version>-<hash>。市场条目的 version 对命令源被忽略。有关哈希覆盖的内容，请参阅复制模式和链接模式。

因为清单首先出现，固定 "version": "1.0.0" 的清单将每个用户保留在缓存副本上，直到其作者更改字符串，无论他们推送多少提交。要让用户跟踪提交，请从清单和条目中都省略 version。托管市场涵盖哪个选择适合哪个发布设置。

Claude Code 在安装前何时刷新市场

当您安装插件时，Claude Code 在其市场目录的本地副本中查找它。您可以在会话中运行 /plugin install 或在 shell 中运行 claude plugin install，并使用或不使用其市场命名插件。该表显示这些组合中哪些刷新本地副本。

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 等待最多十分钟的随机延迟。然后它刷新每个启用自动更新的市场，并更新从它们安装的磁盘上的插件。

运行中的会话保留它加载的版本，您会看到 Plugin updated: <name> · Run /reload-plugins to apply。无论您是否重新加载，新版本都会在下次启动时加载。

哪些市场和插件自动更新

市场是否自动更新遵循首先设置的以下内容：

1. 其 extraKnownMarketplaces 条目中的 autoUpdate 在设置文件中
2. 其 known_marketplaces.json 条目中的 autoUpdate，/plugin Marketplaces 下的 Enable auto-update 切换写入。当设置文件也在 extraKnownMarketplaces 下声明市场时，切换也将 autoUpdate 写入该设置条目
3. 默认值：对于 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 Errors 选项卡中以及如何从那里更新它。

当复制的插件在会话中期更新时，hook 命令、监视器、MCP 服务器和 LSP 服务器继续使用以前版本的路径。运行 /reload-plugins 以将 hooks、MCP 服务器和 LSP 服务器切换到新路径。监视器需要会话重启。

何时命令源重新运行

具有 command 源的插件不等待自动更新传递。打印的目录反映工具在命令运行时的状态，因此 Claude Code 在以下时间再次运行您接受的命令：

• 每次安装或更新插件时
• 每个已启用的命令源插件每个会话一次，在会话启动后不久在后台。此运行不取决于市场的自动更新设置或 DISABLE_AUTOUPDATER
• 在启动或 /reload-plugins 时，当已启用的插件的已安装版本在插件缓存中丢失时

当您设置 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC 时，Claude Code 跳过两个后台运行。显式安装和更新仍然使用该变量集运行命令。

当命令的哈希输出已更改时，Claude Code 将结果安装为新版本并在运行中的交互式会话中重新加载它，切换/reload-plugins 切换的相同组件。您会看到插件已重新加载的通知。

如果就地重新加载会使会话的提示缓存失效，Claude Code 改为提示您运行 /reload-plugins，它警告缓存成本并在使用 --force 重新运行时应用。

名称冲突

当来自不同来源的已启用插件共享清单名称时，此顺序决定哪个加载，从最高优先级到最低：

1. 其 id 出现在托管设置 enabledPlugins 中的插件，作为 true 或 false。其清单名称与 id 的名称部分匹配的 --plugin-dir 副本不被加载，您会看到 --plugin-dir copy of "<name>" ignored: plugin is locked by managed settings
2. 已启用的 --plugin-dir、--plugin-url 或 CLAUDE_CODE_PLUGIN_DIRS 插件。它替换同名的已安装市场插件或技能目录插件：
   • 已安装的市场插件：无声替换。claude plugin list 仍然显示市场行为已启用，因为该行反映您的设置。仅当您使用 --debug 启动时 Claude Code 在 ~/.claude/debug/ 下写入的日志记录 Plugin "<name>" from --plugin-dir overrides installed version
   • 技能目录插件：替换为 /plugin Errors 选项卡行，读取 Not loaded — the name "<name>" is already taken by a session-only plugin (--plugin-dir / --plugin-url), which takes precedence
3. 已安装的市场插件。同名的技能目录插件获得相同的 Not loaded 行，命名已安装的插件
4. 技能目录插件。在这两者之间，~/.claude/skills/ 下的副本加载，项目的 .claude/skills/ 副本被删除，带有一行说明哪个路径遮蔽了它
5. 从 claude.ai 同步的插件。当来自任何其他来源的已启用插件与其名称匹配时，Claude Code 加载该插件并报告同步副本未加载。要改为使用 claude.ai 副本，请禁用您自己的副本

因为顺序比较清单名称，名为 hello-plugin 的 --plugin-dir 插件在该插件的清单也说 "name": "hello-plugin" 时替换 hello@example-marketplace。

防止会话专用插件加载

要防止 --plugin-dir 插件遮蔽任何内容，或在父进程为您传递标志时关闭一个，请在任何设置文件中将其 id 设置为 false。对于清单名称为 hello-plugin 的插件，条目是 "enabledPlugins": {"hello-plugin@inline": false}。禁用的会话专用插件不遮蔽，因此市场或技能目录副本加载。

后续步骤

• 安装和管理插件：安装、启用、禁用和更新步骤本身
• 插件故障排除：按生成它们的阶段分类的错误消息
• 插件命令参考：此页面上命名的标志和命令
• 为您的组织管理插件：强制启用或阻止插件的托管设置