安装 npm、pnpm 及常见报错解决方案

在前端开发中，npm 和 pnpm 是两种常用的包管理工具。npm 是 Node.js 默认的包管理工具，而 pnpm 是一个高效的包管理工具，通过硬链接和符号链接优化了依赖管理的速度和磁盘使用。本文将介绍如何安装 npm 和 pnpm，以及常见的安装报错及解决方案。

一、安装 npm

1.1 安装 Node.js 及 npm

npm 是 Node.js 的默认包管理工具，安装 npm 通常是通过安装 Node.js 自动完成的。

  1. 使用 Node.js 官方安装包：

    • 前往 Node.js 官网 下载适合操作系统的安装包。
    • 安装完成后，npm 会自动安装在系统中。

  2. 使用包管理工具安装（Linux/Unix 系统）：

    • 对于 Ubuntu/Debian 系统，可以使用以下命令：

      sudo apt update
sudo apt install nodejs npm

    • 对于 CentOS/RHEL 系统：

      sudo yum install epel-release
sudo yum install nodejs npm

  3. 使用 nvm 安装（推荐）：

    nvm（Node Version Manager）是一个用于管理 Node.js 版本的工具，使用 nvm 可以方便地切换 Node.js 版本，并且每个版本自带 npm。

    • 安装 nvm：

      curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.2/install.sh | bash

      安装完成后，执行以下命令来加载 nvm：

      source ~/.bashrc

    • 使用 nvm 安装 Node.js：

      nvm install node

    安装完成后，npm 会自动安装。

1.2 验证 npm 安装

安装完成后，验证 npm 是否安装成功：

npm -v

如果能正确输出版本号，则说明 npm 安装成功。

二、安装 pnpm

pnpm 是一种替代 npm 和 Yarn 的包管理工具，具有更快的安装速度和更高效的磁盘使用。

2.1 使用 npm 安装 pnpm

pnpm 是一个 npm 包，因此可以直接通过 npm 安装：

npm install -g pnpm

该命令会全局安装 pnpm，安装完成后可以通过以下命令验证安装：

pnpm -v

2.2 使用 corepack 安装 pnpm

corepack 是 Node.js v16.10.0 引入的一个工具，用于管理包管理器版本。使用 corepack 可以轻松安装 pnpm：

corepack enable
corepack prepare pnpm@latest --activate

这将安装最新版本的 pnpm 并将其激活为全局包管理器。

三、常见安装报错及解决方案

3.1 EACCES: permission denied, mkdir 错误

错误描述：
安装全局包时，出现权限错误：

EACCES: permission denied, mkdir '/usr/local/lib/node_modules'

原因分析：
该错误通常由系统权限不足引起，npm 尝试在系统目录中创建文件夹时被拒绝。

解决方案：

  1. 避免使用 sudo 安装全局包：
    通过修改 npm 全局包安装路径，避免使用 sudo 安装全局包。

    mkdir ~/.npm-global
npm config set prefix '~/.npm-global'

    然后将全局路径添加到环境变量：

    export PATH=~/.npm-global/bin:$PATH

    将此配置写入 ~/.bashrc 或 ~/.bash_profile 文件中，确保每次终端启动时自动加载。

  2. 使用 nvm 管理 Node.js 版本：
    nvm 会将 Node.js 安装在用户目录下，因此不需要修改全局路径即可避免权限问题。

3.2 ELIFECYCLE 错误

错误描述：
安装或运行 npm 脚本时出现 ELIFECYCLE 错误，通常类似如下：

npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! my-app@1.0.0 start: `node index.js`
npm ERR! Exit status 1

原因分析：
该错误通常表示 npm 在执行某个脚本时发生了错误，导致进程以非零退出状态终止。

解决方案：

  1. 检查日志：查看错误信息，检查导致脚本失败的具体原因，通常错误信息会指向代码中的具体问题。

  2. 检查依赖项：有时依赖项之间的冲突或版本问题会导致脚本执行失败，尝试删除 node_modules 目录并重新安装依赖：

    rm -rf node_modules
npm install
  3. 使用不同的 Node.js 版本：某些脚本可能与特定版本的 Node.js 不兼容，尝试使用 nvm 切换到不同版本的 Node.js 运行脚本。

3.3 ENOSPC: no space left on device 错误

错误描述：
安装依赖时，出现磁盘空间不足的错误：

npm ERR! code ENOSPC
npm ERR! syscall write
npm ERR! errno ENOSPC
npm ERR! no space left on device

原因分析：
该错误表示磁盘空间已满，无法再写入文件。

解决方案：

  1. 清理磁盘空间：删除不必要的文件，释放磁盘空间。

  2. 清理 npm 缓存：npm 缓存占用了大量空间，可以清理缓存释放空间：

    npm cache clean --force

3.4 ERR_OSSL_EVP_UNSUPPORTED 错误

错误描述：
在 Node.js 17 及以上版本中，运行某些 npm 脚本时出现 SSL 相关错误：

Error: error:0308010C:digital envelope routines::unsupported

原因分析：
Node.js 17 默认启用了 OpenSSL 3.0，而某些依赖项不支持此版本的加密算法。

解决方案：

  1. 降级 Node.js 版本：切换到 Node.js 16 或更低版本，该版本不启用 OpenSSL 3.0。

  2. 设置环境变量：设置 NODE_OPTIONS 环境变量，禁用 OpenSSL 3.0 的加密算法：

    export NODE_OPTIONS=--openssl-legacy-provider

四、思维导图

安装 npm 和 pnpm 及常见报错解决方案
    1. 安装 npm
        1.1 官方安装包
        1.2 使用包管理工具
        1.3 使用 nvm
    2. 安装 pnpm
        2.1 使用 npm 安装
        2.2 使用 corepack 安装
    3. 常见报错及解决方案
        3.1 EACCES: permission denied
        3.2 ELIFECYCLE 错误
        3.3 ENOSPC: no space left on device
        3.4 ERR_OSSL_EVP_UNSUPPORTED 错误

五、总结

在安装 npm 和 pnpm 时，常见的报错多与权限设置、依赖冲突、磁盘空间不足等有关。通过合理配置 npm 全局路径、使用 nvm 管理 Node.js 版本，以及处理依赖冲突和清理磁盘空间，可以有效解决这些问题，确保包管理工具的顺利安装与使用。