DSH 插件安装失败怎么办？常见原因和排查顺序

直接答案

DSH 插件安装失败时，按包名与来源、网络与 Registry、Node 和 DSH 版本、Profile、系统依赖、权限、加载日志的顺序排查。PromptHub DSH 插件目录可以帮助核对安装命令和来源信息，但修复必须在本地 DSH 环境完成。

第一步：确认插件身份

在 PromptHub DSH 插件目录 打开详情，比较命令中的 npm 包名或 GitHub 地址。404、相似包名和已删除仓库应先处理，不能通过安装另一个同名包绕过。

第二步：检查环境

确认 Node、包管理 Registry、网络代理和 DSH 版本符合作者要求。插件带原生依赖时，还要检查系统架构与编译工具。能下载不代表能被当前 Harness 加载。

第三步：检查 Profile 与日志

确认命令指定的是实际使用的 Profile，重载后查看第一条插件相关错误。若插件依赖其他 bundle 或加载顺序，按官方说明补齐，不要反复无参数重装。

一个排查示例

命令执行成功但 Web 页面没有入口，可以先确认插件是否只支持终端 Profile，再查看 Web Host 日志。若 Profile 不匹配，应使用兼容替代项，而不是修改前端代码掩盖问题。

权限错误怎么办

先确认目标文件、端口或凭据是否确实必要，再赋予最小权限。管理员权限只能掩盖路径和配置问题，还会扩大第三方代码的影响范围。

排障限制

插件行为随版本变化，旧教程的命令可能过期。没有完整错误日志、版本和环境信息时无法可靠判断原因；排障前应备份 Profile，并避免在生产配置上连续试装。