pnpm 命令使用文档

1. 核心特性

pnpm 是新一代Node包管理工具，核心优势：

🚀 高效存储：基于内容寻址存储，节约90%+磁盘空间
🔒 严格依赖：通过符号链接实现精准的node_modules结构
📦 依赖隔离：避免幽灵依赖(Phantom dependencies)
🌐 多包管理：原生支持Monorepo工作流
🔐 安全增强：自动阻止非法依赖访问

2. 安装与迁移

2.1 安装方法

bash 复制代码

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

# 通过npm安装
npm install -g pnpm

# 验证安装
pnpm --version

2.2 项目迁移

bash 复制代码

# 从现有项目迁移
rm -rf node_modules
pnpm import       # 从package-lock.json/yarn.lock转换
pnpm install

3. 基础命令

3.1 包安装

bash 复制代码

pnpm add lodash                  # 生产依赖
pnpm add -D typescript           # 开发依赖
pnpm add -g pnpm                 # 全局安装
pnpm add react@18.2.0            # 指定版本
pnpm add file:../local-pkg       # 本地包

3.2 依赖管理

bash 复制代码

pnpm remove vue                  # 移除依赖
pnpm update                      # 更新所有依赖
pnpm outdated                    # 检测过时依赖
pnpm list                        # 显示依赖树
pnpm why zod                     # 查看依赖来源

4. 依赖管理

4.1 依赖类型

json 复制代码

{
  "dependencies": {
    "react": "18.2.0"          // 标准依赖
  },
  "devDependencies": {
    "vite": "^4.0.0"           // 开发依赖
  },
  "peerDependencies": {
    "react-dom": "18.x"        // 对等依赖
  },
  "optionalDependencies": {
    "fsevents": "2.3.2"        // 可选依赖
  }
}

4.2 依赖解析策略

bash 复制代码

pnpm add --save-exact          # 精确版本锁定
pnpm add --save-optional       # 标记可选依赖
pnpm add --ignore-workspace    # 忽略workspace约束

5. Workspace管理

5.1 初始化Workspace

bash 复制代码

pnpm init -w                    # 初始化Monorepo

5.2 目录结构

复制代码

├── package.json
├── pnpm-workspace.yaml
├── packages/
│   ├── core/
│   └── utils/

5.3 工作区命令

bash 复制代码

pnpm --filter <package> add lodash  # 指定包安装
pnpm -r run build                   # 所有包执行build
pnpm --parallel test               # 并行执行命令

6. 存储管理

6.1 存储路径

bash 复制代码

pnpm store path                    # 显示存储位置
pnpm store prune                  # 清理未用包
pnpm store status                 # 查看存储状态

6.2 离线模式

bash 复制代码

pnpm install --offline            # 强制离线安装
pnpm config set store-dir ~/.pnpm-store  # 自定义存储路径

7. 高级功能

7.1 补丁系统

bash 复制代码

pnpm patch react@18.2.0         # 创建补丁
pnpm patch-commit <patch_dir>   # 提交补丁

7.2 依赖覆盖

bash 复制代码

# package.json
{
  "pnpm": {
    "overrides": {
      "lodash@4.17.0": "4.17.21"
    }
  }
}

8. 配置体系

8.1 配置文件

复制代码

.npmrc
.pnpmfile.cjs (hook文件)
pnpm-workspace.yaml

8.2 关键配置

bash 复制代码

pnpm config set auto-install-peers true    # 自动安装peer依赖
pnpm config set shamefully-hoist true      # 提升依赖
pnpm config set strict-peer-dependencies false  # 关闭peer检查

9. 安全控制

9.1 审计系统

bash 复制代码

pnpm audit                     # 安全审计
pnpm audit --fix               # 自动修复
pnpm licenses list             # 许可证检查

9.2 权限管理

bash 复制代码

pnpm rebuild                   # 重编译二进制
pnpm exec -- node index.js     # 安全执行

10. 最佳实践

优先使用 pnpm-lock.yaml 提交到版本控制
Monorepo项目使用 workspace: 协议
使用 pnpm dlx 代替 npx
定期执行 pnpm store prune
生产环境使用 --frozen-lockfile
通过 overrides 统一依赖版本
使用 pnpm why 分析依赖关系
优先选择非提升模式(shamefully-hoist=false)

11. 常见问题

Q1: 幽灵依赖解决方案

bash 复制代码

# 现象：无法找到未声明的依赖
# 方案：
pnpm add missing-pkg -D      # 明确声明依赖
# 或配置 .npmrc：
public-hoist-pattern[]=*eslint*

Q2: 提升安装速度

bash 复制代码

pnpm install --prefer-offline    # 优先使用缓存
pnpm config set network-concurrency 1  # 限制网络并发

Q3: 处理Peer依赖冲突

bash 复制代码

pnpm add --force               # 强制安装
# 或使用overrides统一版本

转载吱一声~