pnpm 安装完全指南 | Node.js 包管理器快速上手与配置教程

pnpm 是一款快速、节省磁盘空间的 Node.js 包管理器。它通过硬链接和符号链接的方式，避免了传统包管理器（如 npm 和 yarn）中重复安装包的问题，显著提升了安装速度并减少了磁盘占用。

为什么选择 pnpm？

pnpm vs npm vs Yarn 对比

特性	pnpm	npm	Yarn
安装速度	⚡⚡⚡ 非常快	⚡ 一般	⚡⚡ 快
磁盘空间	💾 最省	💾💾 占用大	💾💾 占用大
严格依赖	✅ 是	❌ 否	⚠️ 部分
Monorepo 支持	✅ 原生支持	⚠️ 需要 Workspaces	✅ 支持
安全性	🔒 高	🔒 中	🔒 高
社区生态	📦 良好	📦📦 最好	📦 良好

pnpm 的核心优势

1. 节省磁盘空间：全局存储包，项目间共享
2. 快速安装：智能缓存机制，避免重复下载
3. 严格的依赖管理：防止幽灵依赖问题
4. 优秀的 Monorepo 支持：内置 workspace 功能
5. 兼容性强：完全兼容 npm 的 package.json 格式

安装前准备

系统要求

• Node.js: 版本 >= 16.14（推荐 LTS 版本）
• 操作系统: Windows / macOS / Linux
• 磁盘空间: 至少 500MB 可用空间

检查 Node.js 版本

# 查看 Node.js 版本
node -v

# 查看 npm 版本
npm -v

# 如果版本过低，建议升级
# 使用 nvm (Node Version Manager)
nvm install --lts
nvm use --lts

安装

Windows - PowerShell

iwr https://get.pnpm.io/install.ps1 -useb | iex

Windows - CMD

npm install -g pnpm

macOS / Linux - 官方脚本

curl -fsSL https://get.pnpm.io/install.sh | sh -

NPM

npm install -g pnpm

HomeBrew - macOS

brew install pnpm

Corepack - Node.js 16.13+

corepack enable
corepack prepare pnpm@latest --activate

Scoop - Windows

scoop install nodejs
scoop install pnpm

Arch Linux

sudo pacman -S pnpm

Fedora

sudo dnf install pnpm

验证安装

# 查看 pnpm 版本
pnpm -v

# 输出示例：8.15.0

# 查看详细信息
pnpm --version
pnpm doctor  # 检查环境配置

安装故障排查

问题 1：权限不足

# 错误：EACCES: permission denied

# 解决方案 1：使用 sudo（不推荐）
sudo npm install -g pnpm

# 解决方案 2：修复 npm 权限（推荐）
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g pnpm

问题 2：网络超时

# 错误：ETIMEDOUT / ECONNRESET

# 解决方案：使用国内镜像
npm config set registry https://registry.npmmirror.com
npm install -g pnpm

问题 3：Node.js 版本过低

# 错误：Unsupported engine

# 解决方案：升级 Node.js
nvm install 18
nvm use 18
npm install -g pnpm

更新

pnpm up                //更新所有依赖项
pnpm upgrade 包        //更新包
pnpm upgrade 包 --global   //更新全局包

pnpm 自我更新

# 更新 pnpm 到最新版本
pnpm add -g pnpm

# 更新到指定版本
pnpm add -g pnpm@8.15.0

# 查看可更新版本
pnpm outdated -g

# 回退到上一个版本
pnpm add -g pnpm@previous

自动更新配置

# 启用自动更新检查
pnpm config set auto-install-peers true

# 设置更新策略
pnpm config set save-exact true  # 锁定精确版本

设置存储路径

pnpm config set store-dir /path/to/.pnpm-store

存储路径详解

pnpm 将所有包存储在全局商店中，然后通过硬链接引用到各个项目。

# 查看当前存储路径
pnpm store path

# 默认路径：
# macOS/Linux: ~/.local/share/pnpm/store
# Windows: %LOCALAPPDATA%\pnpm\store

# 自定义存储路径
pnpm config set store-dir /Volumes/SSD/pnpm-store

# 验证配置
pnpm config get store-dir

存储管理命令

# 查看存储使用情况
pnpm store status

# 清理未使用的包
pnpm store prune

# 清理所有缓存
pnpm store clear

# 验证存储完整性
pnpm store verify

# 查看存储大小
du -sh $(pnpm store path)

迁移存储位置

# 1. 停止所有 pnpm 进程
# 2. 移动存储目录
mv ~/.local/share/pnpm/store /new/location/pnpm-store

# 3. 更新配置
pnpm config set store-dir /new/location/pnpm-store

# 4. 验证
pnpm store path

环境变量配置

常用环境变量

# ~/.bashrc 或 ~/.zshrc

# pnpm 主目录
export PNPM_HOME="$HOME/.local/share/pnpm"
export PATH="$PNPM_HOME:$PATH"

# 存储路径
export PNPM_STORE_PATH="/path/to/store"

# 虚拟存储目录
export PNPM_VIRTUAL_STORE_DIR=".pnpm"

# 并发数
export PNPM_CONCURRENCY=10

# 网络超时时间（毫秒）
export PNPM_FETCH_TIMEOUT=60000

配置文件 .npmrc

# 项目级别：项目根目录/.npmrc
# 用户级别：~/.npmrc

# ~/.npmrc

# 注册表
registry=https://registry.npmmirror.com

# 存储路径
store-dir=/path/to/pnpm-store

# 并发数
child-concurrency=10

# 严格对等依赖
strict-peer-dependencies=true

# 自动安装对等依赖
auto-install-peers=true

# 保存确切版本
save-exact=true

# 忽略脚本（提升安装速度）
ignore-scripts=true

# 离线模式
offline=false

# 偏好离线
prefer-offline=false

首次使用配置

初始化项目

# 创建新项目
mkdir my-project
cd my-project

# 初始化 package.json
pnpm init

# 安装第一个包
pnpm add lodash

# 安装开发依赖
pnpm add -D typescript @types/node

# 查看生成的文件
ls -la
# package.json
# pnpm-lock.yaml  # pnpm 的锁文件
# node_modules/   # 包含符号链接

pnpm-workspace.yaml（Monorepo）

# pnpm-workspace.yaml
packages:
  # 所有子包
  - 'packages/*'
  # 特定目录
  - 'apps/*'
  # 排除某些目录
  - '!**/test/**'

性能优化技巧

1. 启用并行安装

pnpm config set child-concurrency 10

2. 使用离线模式

# 首次安装后，可以离线工作
pnpm install --offline

# 或优先使用缓存
pnpm install --prefer-offline

3. 忽略可选依赖

pnpm config set optional false

4. 压缩锁文件

pnpm config set lockfile-compress true

常见问题解答

Q1: pnpm 与 npm/yarn 兼容吗？

A: 完全兼容！pnpm 可以读取 npm 和 yarn 的 package.json，并生成自己的 pnpm-lock.yaml。

# 从 npm 迁移
rm -rf node_modules package-lock.json
pnpm install

# 从 yarn 迁移
rm -rf node_modules yarn.lock
pnpm install

Q2: 如何处理幽灵依赖？

A: pnpm 默认禁止幽灵依赖。如果需要访问未声明的依赖：

// package.json
{
  "pnpm": {
    "overrides": {
      "some-package": "1.0.0"
    }
  }
}

Q3: pnpm 支持 hooks 吗？

A: 支持！pnpm 完全兼容 npm scripts。

{
  "scripts": {
    "preinstall": "echo 'Installing...'",
    "postinstall": "echo 'Installed!'"
  }
}

Q4: 如何在 CI/CD 中使用 pnpm？

# GitHub Actions 示例
name: CI
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: pnpm/action-setup@v2
        with:
          version: 8
      - uses: actions/setup-node@v3
        with:
          node-version: 18
          cache: 'pnpm'
      - run: pnpm install
      - run: pnpm build

总结

pnpm 是现代 Node.js 项目的理想包管理器选择：

1. ✅ 速度快：智能缓存，并行安装
2. ✅ 省空间：全局存储，硬链接共享
3. ✅ 更安全：严格的依赖管理
4. ✅ 易迁移：完全兼容 npm/yarn
5. ✅ 功能强：原生 Monorepo 支持

关键命令速查：

pnpm -v                  # 查看版本
pnpm install             # 安装依赖
pnpm add <pkg>           # 添加包
pnpm remove <pkg>        # 移除包
pnpm update              # 更新包
pnpm store path          # 查看存储路径
pnpm store prune         # 清理缓存

下一步学习：

• pnpm 切换镜像源
• pnpm 管理依赖项
• Docker 容器技术

开始使用 pnpm，让你的项目开发更高效！🚀