第 8 章 · 04 安全与发布最佳实践
文档摘要
第 8 章 · 04 安全与发布最佳实践 本节摘要:插件的安全底线是沙箱三禁令:插件子代理禁止 hooks、mcpServers、permissionMode——插件不能注册事件、不能配 MCP、不能改权限模型,从根上杜绝权限升级。组织侧用受管设置(启用白名单/禁装黑名单/市场管控)统一治理。发布有八步流程:搭结构 → 写清单 → 写文档 → 本地测试( )→ 打标签( )→ 提交市场 → 审核 → 上线。手工配置两小时 vs 插件两分钟的账,算清楚了再动手。 学习目标 阅读完本节,你应当能够: 背出插件沙箱三禁令及其防的是什么。 说出组织受管设置清单与强制时机。 背出发布八步流程,并说出 的作用。 说出本地测试与热重载方法,以及 Do's/Don'ts 要点。
第 8 章 · 04 安全与发布最佳实践
本节摘要:插件的安全底线是沙箱三禁令:插件子代理禁止 hooks、mcpServers、permissionMode——插件不能注册事件、不能配 MCP、不能改权限模型,从根上杜绝权限升级。组织侧用受管设置(启用白名单/禁装黑名单/市场管控)统一治理。发布有八步流程:搭结构 → 写清单 → 写文档 → 本地测试(
--plugin-dir)→ 打标签(claude plugin tag)→ 提交市场 → 审核 → 上线。手工配置两小时 vs 插件两分钟的账,算清楚了再动手。
学习目标
阅读完本节,你应当能够:
- 背出插件沙箱三禁令及其防的是什么。
- 说出组织受管设置清单与强制时机。
- 背出发布八步流程,并说出
claude plugin tag的作用。 - 说出本地测试与热重载方法,以及 Do's/Don'ts 要点。
一、沙箱三禁令:安全底线
插件子代理运行在受限沙箱里,frontmatter 三个键不允许出现:
| 禁用键 | 防的是什么 |
|---|---|
hooks |
子代理不能注册事件处理器——否则插件可在任何事件上执行任意代码 |
mcpServers |
子代理不能配置 MCP 服务器——否则可建立任意外部连接 |
permissionMode |
子代理不能改写权限模型——否则可绕过所有审批 |
一句话:插件只能使用宿主已声明的能力,不能自行扩张权限、不能私开通道、不能绕过审批。这保证安装一个插件最多获得它组件里明写的能力,不会静默升级为"全权限代理"。
二、组织受管设置:企业统一治理
管理员通过受管设置控制全组织插件行为(优先于用户级设置):
| 设置 | 作用 |
|---|---|
enabledPlugins |
默认启用白名单 |
deniedPlugins |
禁装黑名单 |
extraKnownMarketplaces |
追加市场来源 |
strictKnownMarketplaces |
限制可添加的市场(仅受管;空数组 = 全禁;模式数组 = 白名单) |
blockedMarketplaces |
市场黑名单(支持 hostPattern/pathPattern 正则) |
allowedChannelPlugins |
按发布渠道控制插件 |
强制时机(v2.1.117+):blockedMarketplaces 与 strictKnownMarketplaces 在每个插件生命周期事件(安装、更新、刷新、自动更新)都强制执行,不只是首次添加时——动态加了市场也逃不掉。
三、发布八步流程
- 搭好插件目录结构与全部组件(第 1 节的标准布局)。
- 写好
.claude-plugin/plugin.json清单。 - 写 README.md(描述/包含内容/安装/用法/需求)。
- 本地测试:
claude --plugin-dir ./my-plugin启动,验证命令可用、子代理正常、MCP 连得上、钩子执行正确、LSP 配置无误。--plugin-dir可重复(--plugin-dir ./a --plugin-dir ./b),支持 .zip 路径;--plugin-url可拉远程 zip 做一次会话测试。 - 打标签:
claude plugin tag v0.3.0——校验版本格式并创建对应 git 标签,官方推荐的发版方式。GitHub 与 Git 来源的ref/sha字段用于版本锁定,claude plugin validate校验结构。 - 提交市场(官方市场提交入口:claude.ai/settings/plugins/submit)。
- 等待审核与批准。
- 上线,用户一条命令安装。
开发期热重载:改文件自动检测,或 /reload-plugins 强制重读全部组件,不用重启会话。
四、成本账:手工配置 vs 插件
手工配置(2+ 小时):逐个装斜杠命令 → 单独建子代理 → 分别配 MCP → 手动挂钩子 → 写文档 → 分享给团队(然后祈祷每个人都配对)。
插件(2 分钟):
/plugin install pr-review # ✅ 全部装好配好 # ✅ 立即可用 # ✅ 团队可精确复现
五、Do's 与 Don'ts
Do's:名称清晰描述性;README 完整;严格 semver 版本化;组件整体联测;明确文档化需求;给用法示例;包含错误处理;合理打标签便于发现;保持向后兼容;插件聚焦内聚(不塞无关功能);带完整测试;文档化全部依赖。
Don'ts:捆绑无关功能;硬编码凭据;跳过测试;忘写文档;造重复插件;忽略版本管理;过度复杂化组件依赖;不处理错误。
六、故障排查速查
| 症状 | 排查 |
|---|---|
| 装不上 | /version 查版本兼容;JSON 校验清单;网络连通;ls -la 查权限 |
| 组件不加载 | 核对 plugin.json 路径与实际目录;chmod +x scripts/;/plugin debug <name> 看日志 |
| MCP 连不上 | 环境变量;独立 /mcp test 验证;检查 mcp/ 目录配置 |
| 命令不可用 | /plugin list --installed 确认装成功;/plugin status <name> 确认启用;重启;查命名冲突 |
| 钩子不执行 | 权限、语法、事件名;手动测试钩子 |
小结
插件安全靠两道闸:沙箱三禁令(插件子代理禁 hooks/mcpServers/permissionMode,防权限升级)与组织受管设置(白名单/黑名单/市场管控,全生命周期强制)。发布走八步:结构 → 清单 → 文档 → --plugin-dir 本地联测 → plugin tag 打标 → 提交 → 审核 → 上线。成本账一边是两小时手工、一边是两分钟安装——这就是插件存在的意义。到这里,Claude Code 的四大扩展机制(命令/技能/子代理/插件)全部收齐,下一章进入高级能力:检查点与自动化。
下一节预告:第 9 章检查点与高级特性——/rewind 回退、Plan Mode、Extended Thinking、Auto Mode。