pnpm 使用指南：核心特性、常用命令与最佳实践 | 高效管理项目依赖

以下是 pnpm 的详细使用指南，涵盖核心特性、常用命令、高级用法和最佳实践，帮助你高效管理项目依赖。

一、pnpm 核心特性

1. 内容寻址存储

   • 所有依赖版本全局存储一次（~/.pnpm-store），通过硬链接复用，节省磁盘空间。
   • 不同项目的相同依赖版本共享同一份文件，避免重复安装。

2. 非扁平化 node_modules

   • 依赖树严格按层级结构组织，避免「幽灵依赖」（未声明的包被意外引用）。
   • 每个包只能访问其声明的直接依赖。

3. Monorepo 友好

   • 原生支持 workspace 多项目管理，通过 pnpm-workspace.yaml 配置子项目路径。

4. 高性能

   • 依赖安装速度比 Yarn/npm 更快（硬链接 + 并发下载）。

二、安装与初始化

1. 安装 pnpm

# 使用 npm 安装
npm install -g pnpm

# 验证安装
pnpm -v

2. 初始化项目

# 创建新项目
mkdir my-project && cd my-project
pnpm init

# 或从现有项目迁移
rm -rf node_modules package-lock.json
pnpm install

三、常用命令

1. 依赖管理

2. 项目运行

3. Monorepo 管理

四、高级用法

1. 依赖版本控制

# 锁定依赖版本（生成 pnpm-lock.yaml）
pnpm install --frozen-lockfile

# 选择性忽略依赖更新
pnpm override add <package>@<version>

2. 依赖安全检查

# 检查依赖漏洞
pnpm audit

# 自动修复漏洞
pnpm audit fix

3. 缓存管理

# 清理全局缓存
pnpm store prune

# 查看缓存路径
pnpm store path

4. 发布包

# 打包并发布到 npm
pnpm publish

# 跳过构建直接发布
pnpm publish --no-build

五、配置文件

1. .npmrc 配置示例

# 设置全局存储路径
store-dir=/path/to/pnpm-store

# 提升依赖到 node_modules 根目录（解决兼容性问题）
shamefully-hoist=true

# 禁用自动安装 peerDependencies
auto-install-peers=false

2. pnpm-workspace.yaml 示例

packages:
  - 'packages/**'    # 所有子项目
  - '!packages/private/**'  # 排除私有包

六、常见问题解决

1. 依赖找不到（幽灵依赖）

• 原因：未在 package.json 中声明的依赖被直接引用。
• 解决：安装缺失的依赖或启用 shamefully-hoist=true（牺牲严格隔离性）。

2. 工具链兼容性问题

• 场景：Webpack/Jest 等工具因 node_modules 结构报错。
• 解决：在 .npmrc 中启用：

  shamefully-hoist=true
  

3. Monorepo 依赖共享

• 场景：多个子项目共用同一依赖的不同版本。
• 解决：通过 pnpm.overrides 强制统一版本（根目录 package.json）：

  {
    "pnpm": {
      "overrides": {
        "lodash": "4.17.21"
      }
    }
  }
  

七、性能优化建议

1. 利用缓存加速 CI/CD
   • 在 CI 中缓存 ~/.pnpm-store 和 node_modules。
2. 并行安装依赖

   pnpm install --recursive --parallel
   

3. 按需安装
   • 使用 --filter 仅安装必要子项目的依赖。

八、与其他工具对比

九、总结

• 选择 pnpm 的场景：
  • 追求安装速度和磁盘效率。
  • 需要严格的依赖隔离（避免幽灵依赖）。
  • 管理 Monorepo 项目。
• 核心优势：
  • 节省 50%+ 的磁盘空间。
  • 依赖管理更安全、可靠。

通过合理配置和命令组合，pnpm 能显著提升项目管理效率，尤其适合中大型项目或 Monorepo 架构。