Claude Code本地插件离线安装的完整操作步骤

摘要：本文针对无法配置外部 Claude Code 插件市场（如网络限制、SSH验证失败、市场源无法访问等场景），详细介绍本地插件离线安装的完整工作流，步骤清晰、可操作性强，适合新手快速上手，解决插件安装受阻问题，同时附常见问题排查，方便后续查阅使用。

一、前言（适用场景）

在使用 Claude Code 过程中，经常会遇到无法配置外部插件市场的情况，比如：

1. 网络限制，无法访问官方或第三方插件市场源（如 GitHub SSH 验证失败、HTTPS 源无法连接）；
2. 插件市场加载失败，提示 Exit code 1 等报错，无法正常添加市场源；

针对以上场景，无需纠结于插件市场配置，直接通过「本地插件离线安装」即可解决，全程无需联网（仅下载插件包时需短暂联网，可提前下载备用），操作简单且高效。

二、前期准备（必做步骤）

1.下载插件离线包

从可访问的平台（如 GitHub、Gitee 等）下载需要的 Claude Code 插件离线包，推荐下载方式：

1. 打开插件的 GitHub 仓库（如 superpowers 插件：https://github.com/ccplugins/awesome-claude-code-plugins）；
2. 点击右上角「Code」，选择「Download ZIP」，将插件包下载到本地（无需解压，后续统一操作）；

三、完整离线安装步骤（核心流程）

步骤1：解压插件离线包

将下载好的插件 ZIP 压缩包，解压到本地任意位置（建议解压到桌面，方便后续复制），解压后会得到一个插件文件夹（如 superpowers-main），打开文件夹，确认内部包含核心文件：

1. 必备文件：plugin.json（插件配置文件，无此文件则插件无法识别）；
2. 可选文件：skills 文件夹。

步骤2：安装离线插件

方法1：在命令行的claude code中

1.使用/plugin，进入插件页面，选择marketplace，选择add Marketplace，将文件路径写入到指定位置（文件路径就是市场地址）。

2.切换到discover，就可以识别到插件，根据提示进行安装。

方法2：在ide中，以我使用的trae为例：

1.在claude code中输入/manage plugins，进入管理插件对话框。

2.将下载的文件地址写入到指定位置。然后切换到plugins，根据提示进行an'z

步骤3：重启 Claude Code，验证安装

1. 关闭当前打开的 Claude Code（包括后台进程，避免缓存导致插件无法加载）；

2. 重新打开 Claude Code，等待软件加载完成；

3. 验证方法：在聊天框输入 /plugin ，然后切换到installed，查看是否有刚安装的插件，且标注「enabled」（已启用）；

4. 进一步验证：输入 /skills 唤起技能面板，查看插件对应的技能是否显示，点击「Run」可正常调用，即代表安装成功。

四、全局配置优化（可选，提升使用效率）

若需要让插件在所有项目中全局生效，且无需重复配置，可按以下步骤操作：

打开 Claude Code 安装目录下的用户目录（即 .claude所在目录）；

新建一个 claude.md 文件（全局配置文件）；

在文件中写入常用配置，例如：

1. 固定输出格式：「所有技能调用输出均使用中文，代码符合对应语言规范（如 Python 符合 PEP8）」；
2. 默认启用插件：「默认启用 superpowers 插件，加载所有技能」；
3. 常用 prompt 模板：可提前写入常用的代码调试、分析模板，减少重复输入。

保存文件，重启 Claude Code 后，全局配置即可生效，所有项目都会默认使用该配置。

五、常见问题排查（避坑指南）

问题1：输入 /plugin list installed 看不到插件

排查方向：

1. 插件文件夹未放到正确目录：重新确认 plugins 目录路径，确保插件文件夹完整复制（未遗漏子文件）；
2. 未重启 Claude Code：关闭软件并结束后台进程，重新打开后再验证；
3. 插件版本不兼容：下载与当前 Claude Code 版本匹配的插件，或更新 Claude Code 到最新版本。