pnpm 完全指南 - 技术栈

文章目录

- [📦 什么是 pnpm？](#📦 什么是 pnpm？)
- [🚀 安装 pnpm](#🚀 安装 pnpm)
- - [1. 使用 npm 安装（推荐）](#1. 使用 npm 安装（推荐）)
  - [2. 使用独立脚本安装](#2. 使用独立脚本安装)
  - [3. 使用包管理器安装](#3. 使用包管理器安装)
- [⚙️ 配置 PNPM](#⚙️ 配置 PNPM)
- - [1. 设置存储路径](#1. 设置存储路径)
  - [2. 配置镜像源（加速下载）](#2. 配置镜像源（加速下载）)
  - [3. 常用配置](#3. 常用配置)
- [📁 项目初始化](#📁 项目初始化)
- - [1. 创建新项目](#1. 创建新项目)
  - [2. 初始化现有项目](#2. 初始化现有项目)
- [📦 包管理命令](#📦 包管理命令)
- - [1. 安装包](#1. 安装包)
  - [2. 更新包](#2. 更新包)
  - [3. 卸载包](#3. 卸载包)
  - [4. 查看包信息](#4. 查看包信息)
- [🏗️ 脚本执行](#🏗️ 脚本执行)
- - [1. 运行 package.json 中的脚本](#1. 运行 package.json 中的脚本)
  - [2. 直接执行命令](#2. 直接执行命令)
- [🔧 工作区（Workspace）](#🔧 工作区（Workspace）)
- - [1. 创建工作区](#1. 创建工作区)
  - [2. 工作区命令](#2. 工作区命令)
- [🚀 高级功能](#🚀 高级功能)
- - [1. 缓存管理](#1. 缓存管理)
  - [2. 性能优化](#2. 性能优化)
  - [3. 安全检查](#3. 安全检查)
- [📊 与 npm/yarn 命令对比](#📊 与 npm/yarn 命令对比)
- [🎯 最佳实践](#🎯 最佳实践)
- - [1. 项目设置](#1. 项目设置)
  - [2. 依赖管理](#2. 依赖管理)
  - [3. CI/CD 配置](#3. CI/CD 配置)
  - [4. 性能优化](#4. 性能优化)
- [🔍 故障排除](#🔍 故障排除)
- - [1. 常见问题](#1. 常见问题)
  - [2. 调试命令](#2. 调试命令)
  - [3. 环境检查](#3. 环境检查)
- [📚 资源链接](#📚 资源链接)
- [🎉 总结](#🎉 总结)

📦 什么是 pnpm？

pnpm（Performant NPM）是一个快速、节省磁盘空间的包管理器，它使用硬链接和符号链接来管理 node_modules，相比 npm 和 yarn 有更好的性能和磁盘空间利用率。

🚀 安装 pnpm

1. 使用 npm 安装（推荐）

bash 复制代码

# 全局安装 pnpm
npm install -g pnpm

# 验证安装
pnpm --version

2. 使用独立脚本安装

bash 复制代码

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

# Windows (PowerShell)
iwr https://get.pnpm.io/install.ps1 -useb | iex

3. 使用包管理器安装

bash 复制代码

# macOS (Homebrew)
brew install pnpm

# Linux (使用包管理器)
# Arch Linux
sudo pacman -S pnpm

# Fedora
sudo dnf install pnpm

# Ubuntu/Debian
sudo apt install pnpm

⚙️ 配置 PNPM

1. 设置存储路径

bash 复制代码

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

# 设置存储路径（Linux/macOS）
export PNPM_HOME="$HOME/.local/share/pnpm"
export PATH="$PNPM_HOME:$PATH"

# 设置存储路径（Windows）
# 添加环境变量 PNPM_HOME=C:\Users\用户名\.pnpm-store

2. 配置镜像源（加速下载）

bash 复制代码

# 查看当前源
pnpm config get registry

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

# 设置官方源
pnpm config set registry https://registry.npmjs.org/

# 设置公司私有源
pnpm config set registry http://your-private-registry.com/

3. 常用配置

bash 复制代码

# 设置全局安装路径
pnpm config set global-dir ~/.pnpm-global

# 设置并发数（默认16）
pnpm config set fetch-concurrency 8

# 设置网络超时
pnpm config set network-timeout 60000

# 查看所有配置
pnpm config list

📁 项目初始化

1. 创建新项目

bash 复制代码

# 创建新目录并初始化
mkdir my-project
cd my-project
pnpm init

# 使用模板创建
pnpm create vite my-vite-app
pnpm create next-app my-next-app
pnpm create react-app my-react-app

2. 初始化现有项目

bash 复制代码

# 从 package.json 安装依赖
pnpm install

# 生产环境安装（不安装 devDependencies）
pnpm install --prod

# 只安装 package.json 中的依赖（不更新 lock 文件）
pnpm install --frozen-lockfile

📦 包管理命令

1. 安装包

bash 复制代码

# 安装到 dependencies
pnpm add <package-name>
pnpm add lodash
pnpm add express@4.18.2

# 安装到 devDependencies
pnpm add -D <package-name>
pnpm add -D typescript
pnpm add -D eslint@^8.0.0

# 安装到 optionalDependencies
pnpm add -O <package-name>

# 全局安装
pnpm add -g <package-name>
pnpm add -g nodemon
pnpm add -g @vue/cli

# 安装特定版本
pnpm add react@18.2.0
pnpm add webpack@^5.0.0

2. 更新包

bash 复制代码

# 更新所有包
pnpm update

# 更新特定包
pnpm update <package-name>
pnpm update lodash

# 更新到最新版本（忽略 semver）
pnpm update --latest
pnpm update react --latest

# 交互式更新
pnpm update -i

3. 卸载包

bash 复制代码

# 卸载包
pnpm remove <package-name>
pnpm remove lodash

# 全局卸载
pnpm remove -g <package-name>
pnpm remove -g typescript

# 卸载并清理
pnpm remove <package-name> --recursive

4. 查看包信息

bash 复制代码

# 查看已安装的包
pnpm list
pnpm ls

# 查看全局安装的包
pnpm list -g

# 查看特定包
pnpm list <package-name>
pnpm list react

# 查看过时的包
pnpm outdated

🏗️ 脚本执行

1. 运行 package.json 中的脚本

bash 复制代码

# 运行脚本
pnpm run <script-name>
pnpm run dev
pnpm run build
pnpm run test

# 简写（start、test、dev 等常用脚本）
pnpm start
pnpm test
pnpm dev

# 传递参数给脚本
pnpm run build -- --mode production
pnpm test -- --coverage

2. 直接执行命令

bash 复制代码

# 直接执行 node_modules/.bin 中的命令
pnpm exec <command>
pnpm exec eslint src/
pnpm exec jest --coverage

# 等价于 npx
pnpm dlx <command>
pnpm dlx create-react-app my-app
pnpm dlx @nestjs/cli new project

🔧 工作区（Workspace）

1. 创建工作区

bash 复制代码

# 项目结构
my-monorepo/
├── package.json
├── pnpm-workspace.yaml
├── packages/
│   ├── ui/
│   ├── utils/
│   └── app/
└── apps/
    ├── web/
    └── mobile/

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

2. 工作区命令

bash 复制代码

# 为所有包安装依赖
pnpm install

# 为特定包安装依赖
pnpm --filter <package-name> add <dependency>
pnpm --filter ui add react

# 运行所有包的脚本
pnpm -r run build

# 运行特定包的脚本
pnpm --filter ui run test

# 在工作区中添加内部依赖
pnpm --filter app add ui@workspace:*

🚀 高级功能

1. 缓存管理

bash 复制代码

# 查看存储状态
pnpm store status

# 清理未使用的包
pnpm store prune

# 强制清理存储
pnpm store cleanup

2. 性能优化

bash 复制代码

# 使用离线模式（如果已缓存）
pnpm install --offline

# 跳过锁文件生成（用于 CI/CD）
pnpm install --no-lockfile

# 预安装（下载但不链接）
pnpm fetch

3. 安全检查

bash 复制代码

# 审计依赖漏洞
pnpm audit

# 修复漏洞
pnpm audit fix

# 检查许可证
pnpm licenses list

📊 与 npm/yarn 命令对比

功能	npm	yarn	pnpm
初始化项目	`npm init`	`yarn init`	`pnpm init`
安装依赖	`npm install`	`yarn`	`pnpm install`
添加包	`npm install <pkg>`	`yarn add <pkg>`	`pnpm add <pkg>`
添加开发依赖	`npm install -D <pkg>`	`yarn add -D <pkg>`	`pnpm add -D <pkg>`
删除包	`npm uninstall <pkg>`	`yarn remove <pkg>`	`pnpm remove <pkg>`
更新包	`npm update <pkg>`	`yarn upgrade <pkg>`	`pnpm update <pkg>`
运行脚本	`npm run <script>`	`yarn <script>`	`pnpm run <script>`
全局安装	`npm install -g <pkg>`	`yarn global add <pkg>`	`pnpm add -g <pkg>`

🎯 最佳实践

1. 项目设置

bash 复制代码

# 1. 使用 pnpm init 创建项目
pnpm init

# 2. 设置 Node.js 版本约束
echo "node": ">=16.0.0" >> package.json

# 3. 使用 engines 字段
{
  "engines": {
    "node": ">=16.0.0",
    "pnpm": ">=7.0.0"
  }
}

2. 依赖管理

bash 复制代码

# 使用精确版本（避免意外更新）
pnpm add react@18.2.0

# 定期更新依赖
pnpm update
pnpm outdated

# 使用 pnpm audit 检查安全漏洞
pnpm audit

3. CI/CD 配置

bash 复制代码

# .github/workflows/ci.yml 示例
- name: Setup PNPM
  uses: pnpm/action-setup@v2
  with:
    version: 8

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

- name: Run tests
  run: pnpm test

4. 性能优化

bash 复制代码

# 使用 .npmrc 配置
# ~/.npmrc 或项目根目录 .npmrc
shamefully-hoist=true
strict-peer-dependencies=false
auto-install-peers=true

🔍 故障排除

1. 常见问题

bash 复制代码

# 1. 权限问题
sudo chown -R $(whoami) ~/.pnpm-store

# 2. 清理缓存
pnpm store prune

# 3. 重新安装
rm -rf node_modules
rm pnpm-lock.yaml
pnpm install

# 4. 检查网络
pnpm config get registry
ping registry.npmjs.org

2. 调试命令

bash 复制代码

# 查看详细日志
pnpm install --loglevel verbose

# 查看存储路径
pnpm store path

# 检查包是否已安装
pnpm list <package-name> --depth=0

3. 环境检查

bash 复制代码

# 检查 pnpm 环境
echo "pnpm version: $(pnpm --version)"
echo "node version: $(node --version)"
echo "pnpm home: $PNPM_HOME"
echo "store path: $(pnpm store path)"

📚 资源链接

官方网站 : https://pnpm.io/
GitHub : https://github.com/pnpm/pnpm
文档 : https://pnpm.io/zh/motivation
中文文档 : https://pnpm.io/zh/
迁移指南 : https://pnpm.io/zh/migration

🎉 总结

pnpm 的主要优势：

快速安装：使用硬链接，安装速度比 npm/yarn 快 2 倍
节省磁盘：相同的包只存储一次，节省大量磁盘空间
严格隔离：避免 phantom dependencies 问题
Monorepo 友好：优秀的工作区支持
兼容性好：完全兼容 npm 和 yarn 的工作流

从 npm/yarn 迁移到 pnpm 非常简单，大多数情况下只需要替换命令前缀即可。