PNPM 参考文档

什么是 PNPM

PNPM (Performant npm) 是一个快速、节省磁盘空间的 JavaScript 包管理器。它使用符号链接和硬链接的方式来共享依赖，避免了传统包管理器中依赖重复安装的问题。

安装 PNPM

使用 npm 安装

bash 
npm install -g pnpm

使用 curl 安装

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

使用 Homebrew 安装 (macOS)

bash 
brew install pnpm

常用命令

项目初始化

bash 
# 初始化一个新的项目
pnpm init

# 使用特定模板初始化项目
pnpm create vite
pnpm create react-app

依赖管理

bash 
# 安装所有依赖
pnpm install
pnpm i

# 安装生产依赖
pnpm install --prod
pnpm i -P

# 安装开发依赖
pnpm install --save-dev
pnpm i -D

# 全局安装包
pnpm install -g
pnpm i -g

# 添加依赖
pnpm add <package>
pnpm add <package>@<version>
pnpm add <package> --save-dev
pnpm add <package> --save-peer

# 更新依赖
pnpm update
pnpm up
pnpm update <package>
pnpm up <package>@<version>
pnpm update --latest
pnpm up -L

# 删除依赖
pnpm remove <package>
pnpm rm <package>
pnpm remove <package> --save-dev

# 列出依赖
pnpm list
pnpm ls
pnpm list --depth=0
pnpm ls -g

# 检查依赖问题
pnpm audit
pnpm audit fix

脚本命令

bash 
# 运行 package.json 中的脚本
pnpm run <script>
pnpm <script>  # 简写形式

# 运行多个脚本
pnpm run <script1> && pnpm run <script2>

# 查看可用脚本
pnpm run

包发布

bash 
# 发布包
pnpm publish

# 发布测试版本
pnpm publish --tag beta

# 撤销发布
pnpm unpublish <package>@<version>

存储管理

bash 
# 查看存储位置
pnpm store path

# 清理存储
pnpm store prune

# 清理未使用的依赖
pnpm prune

工作空间 (Monorepo)

bash 
# 安装所有工作空间的依赖
pnpm install -w

# 在所有工作空间运行命令
pnpm run <script> -r

# 在特定工作空间运行命令
pnpm run <script> --filter <package>

# 添加跨工作空间依赖
pnpm add <package> --filter <target-package>

配置选项

配置文件

PNPM 配置保存在 .npmrc 文件中，可以是：

  • 项目级：./.npmrc
  • 用户级：~/.npmrc
  • 全局：/etc/npmrc

常用配置

ini 
# 设置存储路径
store-dir=~/.pnpm-store

# 设置全局包路径
prefix=~/.pnpm-global

# 设置依赖安装方式
hopper=false

# 设置网络超时
timeout=120000

# 设置 registry
registry=https://registry.npmmirror.com/

# 开启工作空间支持
workspace=true

命令行配置

bash 
# 查看配置
pnpm config list
pnpm config get <key>

# 设置配置
pnpm config set <key> <value>
pnpm config set <key> <value> --global

# 删除配置
pnpm config delete <key>

工作空间 (Workspaces)

工作空间允许你在一个单一的代码仓库中管理多个包。

配置工作空间

在 package.json 中添加：

json 
{
  "name": "my-workspace",
  "private": true,
  "workspaces": [
    "packages/*",
    "apps/*"
  ]
}

工作空间命令

bash 
# 创建新的工作空间包
pnpm create vite packages/<package-name>

# 安装跨工作空间依赖
pnpm add <local-package> --filter <target-package>

# 运行所有工作空间的测试
pnpm test -r

# 运行特定工作空间的构建
pnpm build --filter <package-name>

高级功能

依赖隔离

bash 
# 创建隔离的依赖环境
pnpm dlx <command>
pnpm dlx create-vite

# 执行一次性命令
pnpm exec <command>
pnpm exec eslint

依赖分析

bash 
# 查看依赖图
pnpm why <package>
pnpm why <package> --depth=0

# 查看依赖关系
pnpm graph

其他实用命令

bash 
# 检查 PNPM 版本
pnpm --version
pnpm -v

# 查看帮助
pnpm help
pnpm help <command>

# 查看命令使用情况
pnpm <command> --help

# 清理 node_modules 和 dist
pnpm clean

迁移指南

从 npm 迁移

bash 
# 安装 pnpm
npm install -g pnpm

# 移除 npm 依赖
rm -rf node_modules package-lock.json

# 安装 pnpm 依赖
pnpm install

从 yarn 迁移

bash 
# 安装 pnpm
yarn global add pnpm

# 移除 yarn 依赖
rm -rf node_modules yarn.lock

# 安装 pnpm 依赖
pnpm install

常见问题

权限问题

如果遇到权限问题，可以尝试：

bash 
# 更改全局安装路径
pnpm config set prefix ~/.pnpm-global

# 或者使用 sudo (不推荐)
sudo pnpm install -g <package>

网络问题

bash 
# 设置镜像源
pnpm config set registry https://registry.npmmirror.com/

# 启用代理
pnpm config set proxy http://proxy.example.com:8080
pnpm config set https-proxy http://proxy.example.com:8080

兼容性问题

bash 
# 使用 Node.js 兼容版本
pnpm env use --global lts

# 查看兼容信息
pnpm info <package> engines

资源链接

最后更新：2026-02-07