Claude Code 插件 zip 怎么装

marketplace 用 archive 源通过 HTTPS 下发 zip，可选 SHA-256 校验，无需 git 与 npm，v2.1.224+。

Claude Code 插件 zip 怎么装

内网插件不想开 git 权限，也不想要求每人装 npm 拉构建物。claude code 插件 zip 怎么装：从 v2.1.224 起，marketplace 的 marketplace.json 可用 source: "archive"，Claude Code 通过 HTTPS 下载 zip 安装；可选 sha256 钉死 digest，用户侧无需 git 或 npm。

作者：CodePass 技术编辑

archive 源在 marketplace 里怎么写

Plugin marketplaces 文档 的 Zip archives 小节定义了字段。最小条目：

{
  "name": "my-plugin",
  "source": {
    "source": "archive",
    "url": "https://artifacts.example.com/claude-plugins/my-plugin-2.1.0.zip"
  }
}

带完整性校验：

{
  "source": "archive",
  "url": "https://artifacts.example.com/claude-plugins/my-plugin-2.1.0.zip",
  "sha256": "abc123...64位十六进制..."
}

digest 大小写均可；不匹配时立即报 Plugin archive integrity check failed 并拒绝安装。url 必须是 HTTPS，拒绝 http://、loopback、link-local 与云 metadata 主机，每一跳 redirect 也要满足同样规则。单包上限 256 MiB。v2.1.120–223 用户会看到「source type not supported」；整库 marketplace 在更旧 CLI 上可能完全加载不了，IT 推送升级包应先于内部 marketplace 切换 archive 源。

版本号：若 plugin.json 与 marketplace 条目都没写 version，Claude Code 用 sha256（或下载内容的 digest）当版本键；你若手写 version，更新 zip 后必须 bump version，否则用户缓存旧包。Week 32 changelog 把这条和「Marketplaces can distribute a plugin as a zip archive」一并发布，要求 CLI v2.1.224+。企业 rollout 时先在试点组验证 /plugin update 能拉到新 digest，再全量改 marketplace 条目。

zip 目录结构两种都认

打 zip 时可以包「插件内容」或「含一层文件夹的插件」：

my-plugin.zip          my-plugin.zip
├── .claude-plugin/    └── my-plugin/
├── skills/                ├── .claude-plugin/
└── ...                    └── skills/

Claude Code 先在 archive 根找 .claude-plugin/，找不到再进唯一顶层文件夹找；嵌套更深会安装失败。.claude-plugin/plugin.json 仍是 manifest 真源，与 git marketplace 相同。构建流水线里常用 CI 产出 zip 上传到 S3、Artifactory generic repo 或 nginx 静态目录，不必为了 Claude Code 单独维护 git clone 权限。

打 zip 前确认 .claude-plugin/plugin.json 的 name 与 marketplace 条目一致，避免装完在 /plugin 里显示陌生 id。256 MiB 上限对含 node 依赖的 MCP server 通常够用；若 bundle 过大，应把运行时依赖改成「用户机已安装 CLI」而不是把 node_modules 打进 archive。sha256 应用 shasum -a 256 或 openssl dgst -sha256 对最终上传字节计算，与 CDN 压缩或 Range 请求无关。

用户侧：注册 marketplace 与安装

团队内分发通常两步：host marketplace.json + 各插件 zip URL；成员添加 marketplace 后再 /plugin install。

claude plugin marketplace add https://artifacts.example.com/claude-marketplace/marketplace.json

或在 ~/.claude/settings.json 的 extraKnownMarketplaces 写 URL。成员在 TUI 里 /plugin 浏览安装；Week 32 还称从 /plugin 安装的插件在「安全时」当前会话立即激活，摘要会显示 Plugin is now active 或提示 /reload-plugins。

command 源 marketplace 仍适合动态生成插件列表；archive 源适合版本钉死的制品。两者可并存于同一 marketplace.json，不同插件各选最顺手的分发方式。git 源适合开源协作与社区 marketplace 提交流程；archive 适合合规不允许开发者 clone 内网 git 的场景，只需只读 HTTPS 拉 zip。

单次调试不必进 marketplace：会话级加载 zip：

claude --plugin-dir ./my-plugin.zip
claude --plugin-url https://artifacts.example.com/my-plugin.zip

--plugin-dir 本地路径；--plugin-url 拉远程 archive，仅当次会话，失败会在 /plugin 的 Errors tab 留记录。与 Claude Code CLI 基础 里其它 --plugin-dir 开发流一致，适合 CI 产出物 smoke test。本地 zip 与已装 marketplace 插件同名时，本地副本当次会话优先，方便在不 uninstall 的情况下试改 skill 或 MCP 定义；managed settings 强制启用/禁用的插件除外。

Week 32 还称 /plugin 安装后若安全则当前会话立即激活，摘要显示 Plugin is now active 或提示 /reload-plugins。archive 装完后 hooks 与 MCP 同样走信任模型：只从你能控制的 HTTPS 源拉包，别把预签名 URL 贴在公开 issue 里。插件若含 shell hooks，zip 分发并不能减少审查义务，只是省去 git clone 步骤。

HTTPS、headers 与私有制品库

若 marketplace 本身从带 headers 的 URL 注册（例如 extraKnownMarketplaces 里配 Bearer），Claude Code 对与 marketplace 同 origin 的 archive 下载会附带这些 headers；跨 origin 的 zip URL 不会带 marketplace 凭证，redirect 离开 origin 也会丢 headers，避免把内部 token 泄露给第三方 CDN。私有 Artifactory 若插件 zip 与 marketplace.json 同 host，可一套鉴权；插件在另一域名则应对 zip 桶单独签可读 URL（预签名 S3 等）。

组织 managed settings 还可限制 strictKnownMarketplaces / blockedMarketplaces；archive 源与 git 源受同一套策略约束。插件内 MCP server 仍走各自 OAuth，zip 只解决分发，不替代 secrets 管理。Skills 与 MCP 组件规范见 Skills 和 MCP 有什么区别；Cursor 侧若也要装同一 skill 目录，路径规则见 Cursor 怎么加载 Claude Skills，但 Cursor 不读 Claude marketplace archive，需要单独打包或 git submodule。

内网 CI 典型流水线：pnpm build → 打 zip → 算 sha256 → 上传制品库 → 更新 marketplace.json 的 url/version/sha256 → 成员 /plugin update。与 git marketplace 相比，archive 不暴露源码 host 凭证给开发者 laptop，只需 HTTPS 读权限。失败排查看 /plugin Errors：下载失败、digest 不匹配、zip 内缺 .claude-plugin/ 三类最常见。

私有仓库若已用 git marketplace，不必全员改 archive；archive 适合「插件构建物与源码 repo 分离」或「外包方只交付 zip」的采购流程。与 Claude Code CLI 基础 的 --plugin-dir ./dir 开发循环配合：本地目录迭代 → CI 打 zip → 同一 manifest 名进 marketplace，减少 hand-edit JSON 出错。

常见问题

v2.1.223 装 archive 插件报不支持怎么办？

文档写明 v2.1.120–223 安装 archive 条目会失败并提示升级 Claude Code。升到 v2.1.224 或更新后再 /plugin update。若 marketplace 混有 archive 与 git 源，旧 CLI 可能整库加载失败，优先升级再添加 marketplace。Windows/macOS/Linux 行为一致，均走同一 HTTPS 校验逻辑。

sha256 和 plugin.json 的 version 都要改吗？

sha256 用于完整性；version 用于更新检测与缓存键。只换 zip 不改 version 时，用户可能认为已最新而跳过更新。推荐每次发新 zip 同时 bump version 并更新 sha256 pin。若省略 version 且省略 sha256，更新检测最弱，只适合本地 --plugin-url 试装，不适合生产 marketplace。

可以用内网 HTTP 文件服务器吗？

不行。archive url 必须 HTTPS 且通过 host 安全校验。内网请用 TLS 终结的 nginx、企业 Artifactory HTTPS 端点，或短期预签名 HTTPS URL。Self-signed 证书需走 OS 信任链或 managed 分发根证书，否则 Claude Code 拒绝下载并在 Errors 里记 TLS 失败。Air-gapped 环境若无 outbound HTTPS，archive 源无法在线安装，只能 --plugin-dir 离线拷 zip。

参考资料