DeepSeek Harness 部署报错怎么解决？依赖解析、PATH 与构建脚本排错汇总

DeepSeek Harness 部署报错，先看报错属于哪一类：ERR_MODULE_NOT_FOUND 与 Cannot find package 是依赖解析问题，dsh 命令找不到是 PATH 问题，ERR_PNPM_IGNORED_BUILDS 是构建脚本问题。按速查表对号入座，翻到对应条目照做。

概览：部署报错先看类别

DeepSeek Harness 部署报错几乎都集中在依赖安装环节，而依赖安装报错又分三类：依赖解析、命令 PATH、构建脚本。 参考真实部署中一路踩过的报错，最典型的链条是：npx @deepseek-ai/dsh web 起不来 → 换 npm 全局或本地装 → 报 Cannot find package 批量缺失 → 换 pnpm 加 --shamefully-hoist → 再被 ERR_PNPM_IGNORED_BUILDS 拦住 → approve-builds 放行构建脚本 → 最终 npx dsh web 在 3080 端口启动成功。全程的每一步报错都是独立的一种排错方式：

DSH 的官方安装命令是 npx @deepseek-ai/dsh web（来源）。下面按三类展开，每类一个 H2、每条报错一个条目，按「报错信息 / 原因 / 解决方法」列。

第一类：依赖解析报错（ERR_MODULE_NOT_FOUND、Cannot find package）

这是部署报错的大头，根子都在 @deepseek-ai/dsh 是个 monorepo：插件系统通过 peer dependencies 引用众多独立包，npm 的扁平安装策略解析不了，必须换 pnpm。

ERR_MODULE_NOT_FOUND

• 报错信息：执行 npx @deepseek-ai/dsh web（来源）时提示 ERR_MODULE_NOT_FOUND: Cannot find package '@deepseek-ai/cordis-plugin-group'。
• 原因：npx 的临时缓存里依赖解析不完整，缺大量 peer 依赖。
• 解决方法：不要在 npx 上反复重试——问题不在网络，而在 npx 缓存机制装不全 peer 依赖。清掉缓存后按下面「Cannot find package 批量缺失」的 pnpm 链路在本地重装依赖。

Cannot find package 批量缺失

• 报错信息：本地 npm install @deepseek-ai/dsh --legacy-peer-deps 后启动，报大量 Cannot find package '@deepseek-ai/dsh-xxx'（如 dsh-timeout、dsh-atomic-write 等），覆盖 50+ 个插件包。
• 原因：@deepseek-ai/dsh 是 monorepo 项目，插件系统通过 peer dependencies 引用众多独立包；npm 的扁平安装策略无法正确解析这种结构。--legacy-peer-deps 只跳过 peer 冲突校验、并不会真的安装 peer 依赖，所以照旧缺包。
• 解决方法：清掉旧依赖和锁文件，换 pnpm 安装——pnpm 对 workspace 和 peer 依赖的处理更完善，--shamefully-hoist 能模拟 npm 的扁平结构，--config.dedupe-peer-dependents=false 关闭依赖去重（来源）：
  bash

  # 1. 在空目录里建 package.json（已有就跳过）
  npm init -y
  
  # 2. 清理旧依赖（Windows：del package-lock.json + rmdir /s /q node_modules）
  rm -rf node_modules package-lock.json
  
  # 3. 用 pnpm 安装 dsh（关键参数）
  npx pnpm add @deepseek-ai/dsh --shamefully-hoist --config.dedupe-peer-dependents=false
  

  如果 pnpm 命令本身找不到，一律用 npx pnpm 代替。这一步会下载 500+ 个包，耗时较长。

第二类：命令与 PATH 报错（dsh 命令找不到）

依赖装好了但命令起不来，多半是 PATH。这类报错有两张面孔：命令根本不存在、或命令存在但缺包。

dsh 命令找不到

• 报错信息：npm install -g @deepseek-ai/dsh 全局安装完成后，敲 dsh web 提示命令找不到。
• 原因：npm 全局包的 bin 目录没有加进 PATH，shell 找不到 dsh 可执行文件。
• 解决方法：
  1. 查全局 bin 目录：npm prefix -g，把输出目录（Windows 常见 %AppData%\npm，macOS/Linux 常见 /usr/local/bin）加进 PATH。
  2. 更省事的做法：放弃全局安装，用 pnpm 在本地项目目录安装，之后一律用 npx dsh web 启动——npx 会自动用本地 node_modules/.bin 里的 dsh。

缺什么补什么的死循环

• 报错信息：手动把 PATH 配好后运行 dsh web，仍报缺 cordis-plugin-loader 等包，补一个又缺一个。
• 原因：npm 默认不会自动安装 peer dependencies，而 DSH 依赖数十个内部子包，手动安装永远补不完。
• 解决方法：停止手动补齐。这属于依赖解析问题，回到第一类的 pnpm 链路重新安装依赖，一次性把 peer 依赖装全。

第三类：构建脚本与网络报错（ERR_PNPM_IGNORED_BUILDS、error 23）

换 pnpm 后依赖解析过了，但 pnpm 的安全策略会默认忽略原生模块的构建脚本，网络不稳还会刷超时警告。这两类各有一种标准处理。

ERR_PNPM_IGNORED_BUILDS

• 报错信息：pnpm 安装完成后提示 [ERR_PNPM_IGNORED_BUILDS] Ignored build scripts: ... Run "pnpm approve-builds" to pick which dependencies should be allowed to run scripts.（来源）。
• 原因：pnpm 安全策略默认不执行依赖的构建脚本，node-pty、koffi 等原生模块没有编译，运行时就崩。
• 解决方法：批准构建脚本后重装（来源）：
  bash

  # 1. 批准构建脚本：交互界面按 a 全选，然后确认 Yes
  npx pnpm approve-builds
  
  # 2. 重新安装，执行这些脚本
  npx pnpm install --shamefully-hoist --config.dedupe-peer-dependents=false
  

  这次 node-pty、koffi 等原生模块会成功编译，不再报错。

网络超时 error 23

• 报错信息：下载依赖时刷大量网络超时警告 error (23)。
• 原因：网络不稳定，某个包下载超时。
• 解决方法：不用管，pnpm 会自动重试并最终完成所有包的下载（来源）；重试太多次还失败，把 npm registry 切到镜像源再跑一次 npx pnpm install。

完整排查流程

任何部署报错按这个顺序走，多数问题在换 pnpm 那一步就解决了。

1. 看报错类别 → 对照概览的速查表，定位是依赖解析、PATH 还是构建脚本。
2. 依赖解析报错 → 清 node_modules 与锁文件，换 pnpm 加 --shamefully-hoist 重装（最关键一步）。
3. 命令找不到 → npm prefix -g 查 PATH；或直接本地装、用 npx dsh 启动。
4. 构建脚本被忽略 → npx pnpm approve-builds 全选放行，再 pnpm install。
5. 启动验证 → npx dsh web，终端显示访问地址 http://localhost:3080 即排错完成。
6. 插件辅助 → 部署跑通后再装 DSH plugin，安装报错可在 DSH Plugin Hub 的插件中心一键安装，规避命令行 github 源缺构建产物的问题。

注意事项

1. Node.js 版本 18 及以上，太低会解析不了依赖声明。
2. 换包管理器前先清 node_modules 和锁文件，别混着装。
3. --legacy-peer-deps 只跳过 peer 校验，救不了 monorepo 的缺包问题，别拿来硬扛。
4. pnpm 命令找不到就用 npx pnpm，两者不冲突。
5. 全局安装不是必须的，本地 pnpm 装 + npx dsh web 更干净。
6. 网络 error (23) 会自动重试，别中断安装。
7. 启动后地址是 http://localhost:3080，端口被占先查占用进程。

来源：DeepSeek Harness 官方文档 - Quickstart、DeepSeek Harness README、dsh CLI README、pnpm approve-builds、pnpm settings