运行项目报错sh: ts-node-dev: command not found的原因与解决方案

运行项目时抛出错误：sh: ts-node-dev: command not found
已尝试删除package-lock.json后重新安装依赖，问题仍存在。项目正常运行时的scripts配置如下：

"scripts": {
  "tsc": "tsc",
  "dev": "ts-node-dev index.ts",
  "lint": "eslint --ext .ts .",
  "start": "node index.js"
}

• ts-node-dev未被声明为项目依赖：之前能运行大概率是全局环境安装过该包，后续全局包被卸载、Node版本切换导致全局路径变更后，系统就无法找到对应命令。如果包本身没有写在package.json的依赖列表中，仅删除lock文件重装时npm不会主动安装这个包，报错会持续存在。
• 命令执行方式错误：直接在系统终端输入ts-node-dev xxx时，系统只会遍历全局环境变量配置的路径查找可执行文件，不会主动检索项目本地node_modules/.bin目录下的命令，必然触发找不到命令的报错。
• 依赖安装文件损坏：仅删除package-lock.json不会清理已经存在残缺文件的node_modules目录，叠加npm本地缓存的坏包影响，重装后依然可能缺失可执行文件的软链。
• Node版本切换导致路径失效：使用nvm、n等工具切换Node版本后，不同版本的全局包路径、本地依赖的软链目标路径都会发生变化，之前安装生成的依赖链接会全部失效。
• 包管理器混用：比如之前用yarn/pnpm安装依赖，后续换npm执行命令，不同包管理器的依赖目录链接逻辑不一致，会出现可执行文件查找失败的问题。

按优先级从高到低尝试即可：

• 明确将ts-node-dev安装为项目开发依赖
  执行对应包管理器的安装命令，确保依赖被写入package.json的devDependencies字段：

  # npm 用户执行
  npm install ts-node-dev --save-dev
  # yarn 用户执行
  yarn add ts-node-dev --dev
  # pnpm 用户执行
  pnpm add ts-node-dev -D
  

• 通过包管理器入口执行命令，不要直接调用全局命令
  直接运行配置好的dev脚本即可，包管理器执行脚本时会自动将本地node_modules/.bin加入临时环境变量，可正确定位到命令：

  npm run dev
  # 对应yarn、pnpm命令为 yarn dev / pnpm dev
  

  如果需要临时直接调用命令，加npx前缀即可，npx会自动检索本地依赖目录下的可执行文件：

  npx ts-node-dev index.ts
  

• 上述操作无效时，彻底清理残留依赖后重装
  仅删除lock文件无法解决文件损坏问题，需要同步清理依赖目录和缓存：

  # 删除所有依赖目录和各包管理器的lock文件
  rm -rf node_modules package-lock.json yarn.lock pnpm-lock.yaml
  # 强制清理npm缓存
  npm cache clean --force
  # 重新执行全量依赖安装
  npm install
  

• 校验当前Node.js版本
  如果近期切换过Node版本，切回项目之前正常运行时使用的版本，删除node_modules目录后重新安装依赖，即可解决软链路径不匹配的问题。
• 统一包管理器使用
  安装依赖、运行脚本全程使用同一款包管理器，不要npm、yarn、pnpm混用，避免依赖链接结构冲突。

内容的提问来源于stack exchange，提问作者abdhafizahmed