故障排查

插件安装失败排查

插件安装时报错？按这个清单逐步排查包名、manifest、版本格式和网络问题。

由 Plugin Hub 社区维护5 个章节

确认包名正确

DSH Plugin Hub 从 npm Registry 同步插件。安装时使用的包名必须和 npm 上发布的名称完全一致，包括 scope（如 @author/plugin-name）。

常见的包名错误包括：多打了空格、忘记 scope 前缀、大小写不匹配。npm 包名是全小写的。

bash

# 检查包是否存在于 npm
npm view @author/plugin-name

每个 DSH 插件的 package.json 必须包含 dsh.bundle 字段，指向 Cordis patch 文件。缺少这个字段的包会被 Hub 拒绝。

json

{
  "name": "my-plugin",
  "version": "1.0.0",
  "dsh": {
    "bundle": {
      "patch": "./cordis.patch.yml"
    }
  }
}

package.json 的 version 字段必须是精确的语义化版本号（如 1.2.3），不能带范围前缀（^、~）或标签。

使用 dsh-hub validate 在发布前检查所有格式问题：

bash

dsh-hub validate my-plugin

patch 文件路径是相对于 package.json 的。确保文件存在、YAML 语法正确、且包含至少一个有效的 entry。

dsh-hub validate 会检查 patch 文件中的 entry ID 是否与 hub 元数据中声明的 entryIds 匹配。

如果 npm Registry 暂时不可达，Hub 会自动重试。被拒绝的包会在一天后重新检查。你也可以在插件页面手动提交包名加速同步。