如何将项目从 npm 或 Yarn 迁移到 pnpm？需要注意什么？

将项目从 npm 或 Yarn 迁移到 pnpm 需要注意以下步骤和问题：

迁移步骤：

1. 安装 pnpm

bash
# 使用 npm 安装
npm install -g pnpm

# 使用独立脚本安装
curl -fsSL https://get.pnpm.io/install.sh | sh -

# 使用 Homebrew (macOS)
brew install pnpm

1. 清理旧依赖

bash
# 删除 node_modules
rm -rf node_modules

# 删除旧的锁文件
rm package-lock.json  # npm
rm yarn.lock          # Yarn

1. 导入锁文件（可选）

bash
# pnpm 可以从 npm/yarn 锁文件导入
pnpm import

# 这会生成 pnpm-lock.yaml

1. 安装依赖

bash
pnpm install

处理常见问题：

1. 幽灵依赖问题

javascript
// ❌ 迁移前可以运行（幽灵依赖）
const lodash = require('lodash');  // 未在 package.json 中声明

// ✅ 迁移后需要显式声明
pnpm add lodash

1. peer dependencies 问题

bash
# pnpm 对 peer dependencies 检查更严格
# 可能会遇到 peer dependency 错误

# 解决方案 1：安装缺失的 peer dependencies
pnpm add react react-dom

# 解决方案 2：使用 overrides
# package.json
{
  "pnpm": {
    "overrides": {
      "react": "^18.0.0"
    }
  }
}

1. shamefully-hoist 配置

bash
# 如果项目依赖扁平化的 node_modules 结构
# .npmrc
shamefully-hoist=true

# 这会创建类似 npm 的扁平化结构
# 但会失去 pnpm 的严格依赖管理优势

配置文件迁移：

bash
# .npmrc 配置
shamefully-hoist=true          # 扁平化模式
strict-peer-dependencies=false # 不严格检查 peer dependencies
auto-install-peers=true        # 自动安装 peer dependencies

package.json 调整：

json
{
  "scripts": {
    "preinstall": "npx only-allow pnpm"  // 强制使用 pnpm
  },
  "engines": {
    "pnpm": ">=8.0.0"
  }
}

CI/CD 配置更新：

yaml
# GitHub Actions
- name: Setup pnpm
  uses: pnpm/action-setup@v2
  with:
    version: 8

- name: Install dependencies
  run: pnpm install --frozen-lockfile

monorepo 迁移：

yaml
# 创建 pnpm-workspace.yaml
packages:
  - 'packages/*'
  - 'apps/*'

json
// 更新包间依赖引用
{
  "dependencies": {
    "@my-org/utils": "workspace:*"  // 使用 workspace 协议
  }
}

迁移检查清单：

bash
# 1. 检查幽灵依赖
pnpm ls --depth=0

# 2. 检查 peer dependencies
pnpm install --strict-peer-dependencies

# 3. 运行测试
pnpm test

# 4. 构建项目
pnpm build

# 5. 检查脚本命令
pnpm run <script>

回滚方案：

bash
# 如果迁移失败，可以回滚
rm pnpm-lock.yaml
rm -rf node_modules
npm install  # 或 yarn install

迁移后的优势：

• 安装速度提升 2-3 倍
• 磁盘空间节省 50-70%
• 更严格的依赖管理
• 更好的 monorepo 支持