DeepSeek Harness npx 卡住怎么办？5 种常见原因与解决方法

DeepSeek Harness（简称 dsh） 是 DeepSeek 开源的 Agent 运行框架。执行 npx @deepseek-ai/dsh web 时卡住，是许多用户首次启动时都会遇到的典型问题。最常见的原因不是程序故障，而是首次运行需要下载大量依赖包，且终端没有任何进度提示——在 Windows 或网络较慢的环境下，等待 8 分钟甚至更久才出现 "dsh web: http://127.0.0.1:3080" 是正常现象。

以下是 5 种最常见原因及对应的解决方法。

一、原因一：首次下载慢，不是卡死

这是最常见的情况。首次执行 npx @deepseek-ai/dsh web 时，系统会自动下载 500+ 个依赖包，且终端没有进度提示。Windows 用户尤其容易遇到这种情况。

解决方法：

• 耐心等待：首次下载通常需要几十秒到几分钟。如果终端没有报错，只是在“沉默”状态，请继续等待，不要按 Ctrl+C 中断。
• 观察网络活动：可以打开任务管理器或资源监视器，查看网络是否在持续传输数据。有流量就说明正在下载，没有卡死。

二、原因二：网络问题或 npm 源慢

国内用户访问默认 npm 源速度较慢，容易导致下载超时或失败。

解决方法：

• 切换 npm 镜像源：执行以下命令，切换到国内镜像源：

  npm config set registry https://registry.npmmirror.com

• 配置代理：如果公司网络需要代理，在终端配置 npm 代理后再重试。

三、原因三：端口 3080 被占用

启动后终端显示 EADDRINUSE: 127.0.0.1:3080，说明 3080 端口被其他程序占用。

解决方法：

• 换端口启动：用 --port 参数指定其他端口：

  npx @deepseek-ai/dsh web --port 13080

• 杀掉占用端口的进程：在 Windows 上执行 netstat -ano | findstr 3080 找到 PID，然后用 taskkill /PID xxx /F 结束进程。

四、原因四：Node.js 版本不匹配或 Windows 原生绑定缺失

Harness 对 Node.js 版本有要求，建议使用 Node.js 22.19.0 或更新版本（推荐 24 LTS） 。此外，Windows 用户可能遇到 sharp 模块加载失败的错误。

解决方法：

• 检查 Node.js 版本：执行 node -v 确认版本是否符合要求。
• 手动安装依赖：如果报 sharp 模块错误，执行以下命令：

  npm install --include=optional sharp

• macOS arm64 用户：如果遇到 --expose-internals is required for HMR service 错误，用以下命令启动：

  node --expose-internals $(which npx) @deepseek-ai/dsh web

五、原因五：插件加载失败或配置文件损坏

终端报 plugin tree failed to load 等错误，说明插件加载失败。

解决方法：

• 清除 npx 缓存重新下载：

  npx clear-npx-cache

• 使用 --yes 强制重新安装：

  npx --yes @deepseek-ai/dsh web

• 查看完整配置：用 dsh --profile web --dump-config 检查配置加载情况。

六、终极解决：全局安装，彻底绕过 npx

如果以上方法都不奏效，最彻底的解决方式是全局安装 Harness，之后直接使用 dsh web 启动，完全绕过 npx 的临时下载过程。

npm install -g @deepseek-ai/dsh
dsh web

全局安装后，启动速度会大幅提升，也不再受 npx 下载慢的困扰。

七、总结

npx @deepseek-ai/dsh web 卡住时，按以下优先级排查：

1. 先等：首次下载 500+ 依赖包需要时间，可能长达 5-10 分钟
2. 换镜像源：npm config set registry https://registry.npmmirror.com
3. 换端口：--port 13080
4. 检查 Node 版本：需要 22.19.0+
5. 全局安装：npm install -g @deepseek-ai/dsh，彻底绕过 npx

大部分卡住的问题，要么是“等得不够久”，要么是“网络不够快”。全球安装是最彻底的解决方案。