解决 pnpm dev 运行报错的坎坷历程

解决 `pnpm dev` 运行报错的坎坷历程

在项目开发过程中，在clone 完别人的代码后启动项目时：nodejs 和 pnpm 版本都没问题，但是 无法运行 pnpm dev 命令启动项目时，往往会遇到各种各样的报错问题。最近在处理 yudao-ui-admin-vue3 项目时，就接连遭遇了多个棘手的错误，经过一番摸索和尝试，最终成功解决。现将整个解决过程记录下来，希望能帮助到遇到类似问题的开发者。

一、`Command "dev" not found` 错误

问题描述

首次运行 pnpm dev 时，出现错误提示 ERR_PNPM_RECURSIVE_EXEC_FIRST_FAIL Command "dev" not found，这意味着 pnpm 找不到名为 dev 的脚本命令。

原因分析

这种情况通常是由于项目根目录下的 package.json 文件中，scripts 字段缺少 dev 脚本配置，或者依赖未正确安装导致相关命令无法执行。

解决过程

检查 package.json 配置 ：
打开项目根目录下的 package.json 文件，找到 scripts 字段，确认其中是否有 dev 相关的配置。我的项目中该字段内容如下：

json 复制代码

{
  "name": "yudao-ui-admin-vue3",
  "version": "2.4.1-snapshot",
  "scripts": {
    "dev": "vite --mode env.local",
    "build": "vite build",
    "preview": "vite preview"
  },
  "dependencies": {
    // 其他依赖...
  },
  "devDependencies": {
    // 其他开发依赖...
  }
}

可以看到，dev 脚本配置是存在的，说明不是脚本缺失的问题，可能是依赖安装异常导致。

重新安装依赖 ：

在终端中进入项目根目录（如果还未进入），执行以下命令删除 node_modules 目录和 pnpm-lock.yaml 文件（如果存在）：

bash 复制代码

# 删除 node_modules 目录
rm -rf node_modules
# 删除 pnpm-lock.yaml 文件（如果存在）
rm pnpm-lock.yaml

然后重新运行 pnpm install 安装依赖：

bash 复制代码

pnpm install

然而，再次执行 pnpm dev 后，该错误依旧存在，说明问题尚未解决，需要进一步排查。

二、`Permission denied` 错误

问题描述

在重新安装依赖后再次运行 pnpm dev，出现了新的错误提示 sh: /Users/ljj/Downloads/code_1/code 2/yudao-ui-admin-vue3/node_modules/.bin/vite: Permission denied，表示没有执行 vite 命令的权限。

原因分析

在 Linux 和 macOS 系统中，文件权限控制着用户对文件的读、写和执行操作。出现此错误，是因为当前用户对 vite 文件没有执行权限。

解决过程

使用 chmod 命令给 vite 文件添加可执行权限。在项目根目录下执行以下命令：

bash 复制代码

chmod +x node_modules/.bin/vite

chmod +x 命令用于给文件添加可执行权限。执行完这个命令后，再次运行 pnpm dev。这次虽然没有了权限错误，但又出现了新的报错。

三、`ERR_MODULE_NOT_FOUND` 错误

问题描述

运行 pnpm dev 后，出现了如下错误信息：

复制代码

> vite --mode env.local

node:internal/errors:496
    ErrorCaptureStackTrace(err);
    ^

Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'esbuild' imported from /Users/ljj/Downloads/code_1/code 2/yudao-ui-admin-vue3/node_modules/vite/dist/node/cli.js
    at new NodeError (node:internal/errors:405:5)
    at packageResolve (node:internal/modules/esm/resolve:916:9)
    at moduleResolve (node:internal/modules/esm/resolve:973:20)
    at defaultResolve (node:internal/modules/esm/resolve:1206:11)
    at ModuleLoader.defaultResolve (node:internal/modules/esm/loader:404:12)
    at ModuleLoader.resolve (node:internal/modules/esm/loader:373:25)
    at ModuleLoader.getModuleJob (node:internal/modules/esm/loader:250:38)
    at ModuleWrap.<anonymous> (node:internal/modules/esm/module_job:76:39)
    at link (node:internal/modules/esm/module_job:75:36) {
  code: 'ERR_MODULE_NOT_FOUND'
}

Node.js v18.20.8
 ELIFECYCLE  Command failed with exit code 1.

该错误表明 Node.js 无法找到 esbuild 包，而 esbuild 是 Vite 构建工具依赖的重要包，缺少它会导致 Vite 无法正常启动。

原因分析

可能是依赖安装过程中出现问题，导致 esbuild 包没有正确安装到项目中。

解决过程

再次重新安装依赖 ：
为了确保依赖安装的完整性，再次删除 node_modules 目录和 pnpm-lock.yaml 文件（如果存在），执行命令：

bash 复制代码

# 删除 node_modules 目录
rm -rf node_modules
# 删除 pnpm-lock.yaml 文件（如果存在）
rm pnpm-lock.yaml

然后重新执行 pnpm install 安装依赖：

bash 复制代码

pnpm install

执行完后，运行 pnpm dev，问题仍然存在，说明单纯重新安装所有依赖无法解决该问题。

手动安装 esbuild 包 ：

既然自动安装没有解决 esbuild 包缺失的问题，那么我们尝试手动安装 esbuild 包。在项目根目录下的终端中执行以下命令：

bash 复制代码

pnpm install esbuild --save-dev

--save-dev 参数表示将 esbuild 作为开发依赖安装到项目中。安装完成后，再次运行 pnpm dev。这次，项目终于成功启动！

总结

在解决 pnpm dev 运行报错的过程中，我们遇到了依赖配置、文件权限和依赖缺失等多种问题。通过逐步排查和针对性的解决措施，最终使项目能够顺利启动。在遇到类似问题时，我们可以从以下几个方面入手：

仔细检查 package.json 文件中的脚本配置和依赖列表，确保 dev 脚本存在且依赖完整。
确保文件和目录具有正确的权限，特别是可执行文件，如遇到权限问题，使用 chmod 命令进行调整。
当依赖安装出现问题时，尝试多次重新安装或手动安装缺失的依赖包。
注意 Node.js 版本与项目依赖的兼容性，必要时使用 nvm 等工具进行版本切换。

最后！如果以上你都试过了还是不行重启终端或者重启电脑清一下缓存就好了！！！

希望本文记录的详细解决过程能够为大家在开发过程中解决类似问题提供一些参考和帮助。如果大家还有其他更好的解决方法或遇到了不同的问题，欢迎在评论区交流分享！

解决 pnpm dev 运行报错的坎坷历程