使用 pnpm 替换 npm：一个完整的迁移指南

随着项目的增长，包管理工具的选择变得至关重要。npm 是 Node.js 默认的包管理工具，但随着一些性能和效率问题的显现，越来越多的开发者开始转向 pnpm，特别是在处理大型项目时。pnpm 提供了比 npm 更高效、更快速的依赖管理方式，尤其是在缓存和磁盘空间使用上表现得尤为突出。

如果你正在考虑将你的项目从 npm 迁移到 pnpm，这篇文章将帮助你总结整个过程中的挑战和解决方案，带你完成这一迁移过程。

1. 安装 pnpm

如果你之前使用的是 npm，那么首先要确保安装 pnpm。有几种方式可以安装 pnpm：

使用 Homebrew 安装 pnpm

在 macOS 上，你可以使用 Homebrew 来安装 pnpm：

brew install pnpm

或者，如果你已经安装了 Homebrew，可以使用以下命令升级 pnpm：

brew upgrade pnpm

使用 npm 安装 pnpm

如果你没有 Homebrew，也可以通过 npm 来全局安装 pnpm：

npm install -g pnpm

2. 将项目从 npm 切换到 pnpm

在切换到 pnpm 后，原先的 node_modules 文件夹和 package-lock.json 文件将被 pnpm 的机制替代。以下是步骤：

步骤 1：删除现有的 node_modules 和 package-lock.json

首先，确保删除旧的 node_modules 和 package-lock.json 文件，因为这些文件是针对 npm 的。

rm -rf node_modules package-lock.json

步骤 2：运行 pnpm 安装

然后，使用 pnpm 重新安装所有依赖：

pnpm install

这将重新生成一个 pnpm-lock.yaml 文件，并在 node_modules 中创建依赖。pnpm 会自动处理依赖树，并且与 npm 的行为兼容。

3. 配置 pnpm

如果你之前在使用 npm 时遇到了一些特定的依赖处理问题，pnpm 提供了一个配置选项 shamefully-hoist，允许你将依赖提升到顶层目录，这与 npm 的行为类似。启用此选项可以解决一些兼容性问题，尤其是当某些包要求它们的依赖位于 node_modules 根目录时。

要启用 shamefully-hoist：

pnpm config set shamefully-hoist true

这将使 pnpm 的行为更接近 npm，从而避免一些依赖冲突。

4. 使用 pnpm 执行脚本

在 package.json 中，脚本部分不需要做任何修改。pnpm 完全兼容 npm 的脚本，因此你可以直接运行 npm 脚本，如下所示：

"scripts": {
  "dev": "vite",
  "build": "vite build",
  "lint": "eslint .",
  "preview": "vite preview"
}

执行这些脚本时，你只需要使用 pnpm run 来代替 npm run：

• 启动开发服务器：pnpm run dev
• 构建项目：pnpm run build
• 运行 ESLint 检查：pnpm run lint
• 预览构建后的项目：pnpm run preview

5. 清理缓存和解决潜在问题

如果你在安装过程中遇到卡住的情况，可能是由于缓存或磁盘空间问题。在迁移到 pnpm 时，建议执行以下操作：

清理 pnpm 缓存

pnpm 使用全局缓存存储包，如果缓存有问题，可以通过以下命令清理：

pnpm store prune

检查磁盘空间

pnpm 会在磁盘上创建缓存和依赖目录，如果磁盘空间不足，安装过程可能会卡住。通过 df -h 命令检查你的磁盘空间，确保有足够空间来存储依赖。

6. 常见问题及解决方法

在迁移过程中，你可能会遇到一些常见问题，以下是一些解决方法：

问题 1：安装卡住

如果安装过程在某个阶段卡住，可能是由于缓存问题、磁盘空间不足或网络问题。可以尝试清理缓存并释放磁盘空间。

pnpm store prune
rm -rf node_modules pnpm-lock.yaml
pnpm install

问题 2：依赖未正确安装

如果某些依赖没有正确安装，首先确认你是否启用了 shamefully-hoist 配置，或者尝试删除 node_modules 并重新安装。

问题 3：权限问题

在 macOS 或 Linux 系统上，权限问题可能导致某些包无法正确安装。确保你有足够的权限运行安装命令，或者使用 sudo 来安装依赖。

总结

将项目从 npm 切换到 pnpm 是一个相对简单的过程，尤其是在 pnpm 完全兼容 npm 的脚本和依赖管理方式的情况下。通过以下步骤，你可以顺利地从 npm 迁移到 pnpm：

1. 安装 pnpm；
2. 删除旧的 node_modules 和 package-lock.json 文件；
3. 运行 pnpm install 来重新生成依赖；
4. 配置 shamefully-hoist（如果需要）；
5. 运行项目脚本，确保一切正常。

迁移到 pnpm 后，你将享受到更快速的依赖安装、更高效的缓存机制以及更节省磁盘空间的优势。

如果你遇到任何问题，可以参考本篇文章提供的解决方案，或者在相关社区中寻求帮助。