dsh-web-ui 常见问题排查：安装失败与插件不显示的 6 个终极解决方案
项目地址: https://gitcode.com/gh_mirrors/ds/dsh-web-ui dsh-web-ui 是 DeepSeek Harness（DSH）Web UI 的插件与皮肤集合，安装后可在侧边栏获得任务看板、Git 图谱、右侧面板、移动端远程、宠物与皮肤中心等丰富能力。不少新手在安装 dsh-web-ui 插件时遇到「安装失败」或「插件不显示」的困惑，其实绝大多数情况几分钟就能解决。本文整理了 6 个高频问题的终极排查方案，建议按顺序逐一排查。📌
一、安装前快速回顾：dsh-web-ui 插件装在哪里
DSH 插件通过 dsh plugin 命令安装进 profile（dsh web 对应 web profile）。推荐直接安装聚合包 dsh-web-ui-all，一个包装齐全部功能插件与皮肤；只想用皮肤则安装 dsh-skins。
一行命令装齐全家桶：
dsh plugin --profile web add @linxin666/[email protected]
装完重启 dsh web，侧边栏即可看到全部插件入口。
二、解决方案 1：插件不显示？先重启 dsh web
侧边栏没有新入口，十有八九是安装后没有重启 dsh web。这是「插件不显示」最常见的原因，没有之一。重启命令很简单：
dsh web
重启后若仍不显示，再继续往下排查。
三、解决方案 2：安装报错 ERR_PNPM_IGNORED_BUILDS 怎么办
首次安装若提示 ERR_PNPM_IGNORED_BUILDS（pnpm 拒绝依赖的构建脚本），说明 pnpm 的安全策略拦截了部分依赖的原生构建。解决办法：把 cloudflared / cpu-features / ssh2 加入 profile 的 pnpm-workspace.yaml 的 allowBuilds 列表，然后重新执行安装命令即可。
四、解决方案 3：宿主已挂载但 UI 不显示怎么修复
如果你是通过仓库源码方式调试安装，要注意 profile 目录并不是 pnpm workspace，聚合包里的 workspace:* 依赖会回退拉取 npm 已发布版本；若 npm 版本滞后或损坏，就会出现「宿主已挂载但 UI 不显示」的现象。此时运行：
node scripts/link-profile.mjs
该脚本会把全家桶构建产物链接进 ~/.dsh/profiles/node_modules/@linxin666/，让全部子包走本地代码，再重启 dsh web 即可。
五、解决方案 4：插件功能缺失？检查版本号与 registry 缓存
个别环境对 npm latest 的解析可能受 registry 缓存影响；历史版本 0.1.1 的 dsh-pet 还缺少运行时文件（lib/types/*.js），安装后会出现功能缺失。带版本号安装最稳妥：
dsh plugin --profile web add @linxin666/[email protected]
升级时把 @0.1.12 换成新版本号即可。
六、解决方案 5：NPM_TOKEN 认证失败导致安装中断
从仓库源码构建（pnpm install）依赖官方 NPM SDK 包，若仍使用私有 scope 认证，缺少 NPM_TOKEN 环境变量会导致拉包失败。设置环境变量，并把 token 写入用户级 ~/.npmrc：
export NPM_TOKEN='<你的令牌>'
七、解决方案 6：皮肤不显示或切换失败
皮肤资产全部内置在 dsh-skins 一个包里，无需为每款皮肤单独安装。只想用皮肤，只装这个包即可：
dsh plugin --profile web add @linxin666/dsh-skins
皮肤启用互斥由 dsh-skin use 管理：切换皮肤时先试穿再应用，退出试穿完全还原，不会互相覆盖。✅
八、如何验证 dsh-web-ui 插件安装成功
安装成功后，可用 dsh --profile web --dump-config 确认插件配置层已挂载；或重启 dsh web 后看到侧边栏出现对应入口即生效。所有插件的开关与参数统一收纳于「设置 > 插件配置」，修改即时生效。
九、如何彻底卸载 dsh-web-ui 插件
卸载一条命令即可：
dsh plugin --profile web remove @linxin666/dsh-web-ui-all
卸载后同样需要重启 dsh web 才会生效。
结语：排查顺序记住「先重启，再查源」
遇到安装失败或插件不显示，遵循「先重启 → 查版本 → 查构建脚本 → 查依赖来源」的顺序，绝大多数问题都能快速定位。更多安装细节可查看 docs/plugins.md，各插件源码分布在 packages/ 目录下（如 packages/dsh-task-board/、packages/dsh-web-ui-settings/）；需要修改源码调试时，再考虑 clone 仓库本地构建，仓库地址 https://gitcode.com/gh_mirrors/ds/dsh-web-ui ，克隆后依次执行 pnpm install、pnpm -r build、node scripts/link-profile.mjs 即可挂载全家桶。
转载自 CSDN-专业IT技术社区
原文链接：https://blog.csdn.net/gitblog_01200/article/details/156013115
