Node.js 环境看似正常但 DSH 命令不可用怎么办

先看结论

Node.js 能输出版本但 DeepSeek Harness（DSH）或 npx 仍不可用，通常不是 DSH Web UI 本身的问题，而是当前终端解析到了不符合要求的 Node 版本、node/npm/npx 来自不同安装目录，或编辑器仍保留安装前的旧 PATH。先在发生错误的同一个终端检查版本和实际路径，再验证 npm Registry 和 DSH CLI；不要一开始就删除全部缓存或依赖。

本文在 2026-08-29 按 DSH 0.1.1-rc.2 固定源码复核。该版本根包声明 Node.js 范围为 ^22.19.0 || >=24.0.0：Node 22 必须至少为 22.19.0，Node 23 不在声明范围内，Node 24 及以上符合该字段。GitHub 0.1.2-alpha.1 仍是预发布版，npm 默认安装版本仍为 0.1.1-rc.2。

第一步：在出错终端检查版本

先运行：

node --version
npm --version
npx --version

预期结果是三条命令都能输出版本，且 node --version 满足 ^22.19.0 || >=24.0.0。如果 node 成功但 npm 或 npx 提示找不到命令，说明 Node 安装或 PATH 不完整，应先修复运行时环境，不要继续修改 DSH Profile。

如果刚安装或切换过 Node.js，完全退出当前终端和图形界面编辑器，再重新打开。编辑器内置终端可能继承应用启动时的旧环境变量，仅新建一个终端标签不一定会刷新。

第二步：确认三个命令来自哪里

macOS 或 Linux：

command -v node
command -v npm
command -v npx
node -p "process.execPath"

Windows PowerShell：

Get-Command node,npm,npx | Select-Object Name,Source
where.exe node
where.exe npx
node -p "process.execPath"

检查 node、npm 和 npx 是否属于同一套 Node 安装。常见冲突包括：系统安装与 nvm/fnm/Volta 同时存在、编辑器终端与系统终端 PATH 不同、Windows Store 别名覆盖真实可执行文件，或者旧 Node 目录排在新目录前面。

如果输出了多个路径，不要直接删除目录。先记录路径和版本，再按照正在使用的版本管理器切换或修复 PATH；完成后重新打开终端并重复本节命令。

第三步：确认 npm 能看到 DSH

先只查询 npm 元数据：

npm view @deepseek-ai/dsh version

在 2026-08-29 复核时，预期返回 0.1.1-rc.2。这一步需要访问 npm Registry；如果出现 DNS、代理、证书、超时或 Registry 地址错误，应先处理网络和 npm 配置。

GitHub 出现 0.1.2-alpha.1 Release 不表示普通 npx @deepseek-ai/dsh 会自动安装该版本。默认命令遵循 npm dist-tag；不要根据 GitHub Tag 猜测一个安装命令，也不要为了追新版本更换未知 Registry。

第四步：用低影响命令检查 CLI

版本、路径和 Registry 都正常后，先查看固定基线的帮助信息：

npx --yes @deepseek-ai/[email protected] --help

预期结果是 DSH 输出 CLI 帮助，而不是启动 Web UI。如果首次运行需要从 npm 下载包，终端会产生网络访问和本机 npm 缓存；公司网络或代理环境应先确认允许的 Registry。

帮助能够显示，说明 Node、npx 和 DSH CLI 的基本链路成立。随后再按安装 DeepSeek Harness 并启动 DSH Web UI执行正式启动命令。

症状怎样分流

不要先做这些操作

• 不要因为一次失败就删除整个 npm 缓存、用户目录或项目锁文件；
• 不要同时切换 Node 版本、Registry、终端和 DSH 版本，否则无法判断哪个变化解决了问题；
• 不要复制带有陌生代理、镜像或全局安装参数的命令；
• 不要把 GitHub alpha Release 当成 npm 默认分发；
• 不要用另一个终端的成功结果代替实际出错终端的检查。

每次只改变一个因素，并记录命令、路径、版本和结果。这样可以把问题稳定分为运行时、PATH、网络、CLI、Web UI 或模型配置，而不是反复重装全部环境。

修复后的最小验收

完成修复后应满足：

1. node --version 符合官方固定版本的 engines；
2. node、npm 和 npx 来自预期的同一套安装；
3. npm view @deepseek-ai/dsh version 能返回 npm 当前默认版本；
4. 固定版本的 --help 能输出 CLI 帮助；
5. 正式启动失败时能进入对应错误页，而不是继续盲目重装 Node。

环境验收完成后，可以继续DeepSeek Harness 中文入门并完成第一次 Session。