pnpm 进阶指南

node_modules/
├── express/
│   └── node_modules/
│       ├── accepts/
│       │   └── node_modules/
│       │       └── mime-types/  # 重复
│       └── body-parser/
│           └── node_modules/
│               └── mime-types/  # 重复
└── koa/
    └── node_modules/
        └── mime-types/          # 第三次重复

// package.json
{
  "dependencies": {
    "express": "^4.18.0"  // express 依赖 debug
  }
}

// 代码中可以直接使用 debug，但它并未被显式声明
const debug = require('debug');  // ✅ 可以运行，但这是幽灵依赖！

// 当 express 更新不再依赖 debug 时，代码会突然崩溃

# 创建一个文件
echo "hello world" > source.txt

# 创建一个指向 source.txt 的硬链接
ln source.txt hard-link.txt

# 查看文件信息
ls -li
# 123456 -rw-r--r--  2 user group 12 Jan 1 10:00 hard-link.txt
# 123456 -rw-r--r--  2 user group 12 Jan 1 10:00 source.txt
# 注意：两个文件的 inode 号相同（123456），链接数为 2

# 验证内容一致
cat hard-link.txt  # 输出: hello world

# 修改硬链接会影响原文件
echo "modified" >> hard-link.txt
cat source.txt     # 输出: hello world\nmodified

# 创建一个指向 source.txt 的软链接
ln -s source.txt soft-link.txt

# 查看文件信息
ls -li
# 123457 lrwxr-xr-x  1 user group 10 Jan 1 10:00 soft-link.txt -> source.txt
# 注意：软链接有独立的 inode（123457），类型为 l

# 通过软链接访问内容
cat soft-link.txt  # 输出: hello world

# 删除源文件后，软链接失效
rm source.txt
cat soft-link.txt  # 错误: No such file or directory

┌─────────────────────────────────────────────────────────────┐
│                      全局存储 (Store)                        │
│                    ~/.pnpm-store/v3                         │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │
│  │ lodash@4.17 │  │ express@4.18│  │ react@18.2  │        │
│  └─────────────┘  └─────────────┘  └─────────────┘        │
└─────────────────────┬───────────────────────────────────────┘
                      │ 硬链接
                      ▼
┌─────────────────────────────────────────────────────────────┐
│              项目 A: node_modules/.pnpm                      │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │
│  │ lodash@4.17 │  │ express@4.18│  │ react@18.2  │        │
│  └──────┬──────┘  └─────────────┘  └─────────────┘        │
└─────────┼───────────────────────────────────────────────────┘
          │ 软链接
          ▼
┌─────────────────────────────────────────────────────────────┐
│              项目 A: node_modules                            │
│  ┌─────────────┐  ┌─────────────┐                          │
│  │ lodash      │  │ express     │  (仅直接依赖)            │
│  └─────────────┘  └─────────────┘                          │
└─────────────────────────────────────────────────────────────┘

~/.pnpm-store/v3/
├── files/
│   └── 00/
│       ├── 00001a...  # 文件内容哈希
│       ├── 00002b...
│       └── ...
└── index-5.12.0.lock

# 查看存储路径
pnpm store path
# 输出: /Users/username/.pnpm-store/v3

# 查看存储状态
pnpm store status

# 清理未使用的包（释放空间）
pnpm store prune

# 查看存储统计信息
pnpm store usages

node_modules/
├── .pnpm/                    # 实际存储所有依赖的目录
│   ├── accepts@1.3.8/
│   ├── body-parser@1.20.1/
│   ├── express@4.18.2/
│   │   └── node_modules/     # express 的依赖通过软链接指向 .pnpm 中的对应包
│   │       ├── accepts -> ../../accepts@1.3.8/node_modules/accepts
│   │       └── body-parser -> ../../body-parser@1.20.1/node_modules/body-parser
│   └── ...
├── .modules.yaml             # pnpm 内部元数据
└── express -> .pnpm/express@4.18.2/node_modules/express  # 软链接

# 查看顶层依赖（仅直接依赖）
ls node_modules
# express  .pnpm  .modules.yaml

# 查看实际存储
ls node_modules/.pnpm
# accepts@1.3.8  body-parser@1.20.1  express@4.18.2  ...

# 查看是否为软链接
ls -la node_modules/express
# lrwxr-xr-x ... express -> .pnpm/express@4.18.2/node_modules/express

# 假设有 5 个项目，都依赖 lodash@4.17.21

# npm/Yarn：每个项目独立存储
# 总占用：5 × 1.4MB = 7MB

# pnpm：全局只存一份
# 总占用：1.4MB（节省 80%）

// package.json 中只声明了 express
{
  "dependencies": {
    "express": "^4.18.0"
  }
}

// 尝试使用未声明的 debug 包

// npm/Yarn：✅ 可以访问（幽灵依赖）
const debug = require('debug');  // 成功

// pnpm：❌ 无法访问（严格依赖）
const debug = require('debug');  // Error: Cannot find module 'debug'

# macOS/Linux (使用安装脚本)
curl -fsSL https://get.pnpm.io/install.sh | sh -

# 或使用 wget
wget -qO- https://get.pnpm.io/install.sh | sh -

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

# 使用 npm 安装
npm install -g pnpm

# 使用 Homebrew (macOS)
brew install pnpm

# 使用 Scoop (Windows)
scoop install pnpm

# 使用 Corepack (Node.js 16.13+)
corepack enable
corepack prepare pnpm@latest --activate

# 安装所有依赖
pnpm install          # 根据 package.json 安装
pnpm i                # 简写

# 添加依赖
pnpm add <package>              # 生产依赖
pnpm add -D <package>           # 开发依赖
pnpm add -O <package>           # 可选依赖
pnpm add -g <package>           # 全局安装

# 安装特定版本
pnpm add lodash@4.17.21
pnpm add express@latest
pnpm add react@next             # 安装 next 标签的版本

# 移除依赖
pnpm remove <package>           # 从 dependencies 移除
pnpm remove -D <package>        # 从 devDependencies 移除
pnpm remove -g <package>        # 移除全局包

# 更新依赖
pnpm update                     # 更新所有依赖（遵循 semver）
pnpm update --latest            # 更新到最新版本（忽略 semver）
pnpm update <package>           # 更新特定包
pnpm up <package>               # 简写

# 查看依赖信息
pnpm list                       # 查看已安装的依赖
pnpm list --depth=1             # 显示深度为 1 的依赖树
pnpm list -g                    # 查看全局安装的包
pnpm why <package>              # 查看某个包为何被安装

# 运行 package.json 中的脚本
pnpm run <script>
pnpm <script>           # run 可以省略

# 示例
pnpm run dev
pnpm test
pnpm build

# 使用 npx 等效功能
pnpm dlx <package>      # 执行包而不安装（类似 npx）
pnpm dlx create-vite    # 创建 Vite 项目
pnpm dlx prettier --write .

# 创建新的 package.json
pnpm init

# 快速初始化（使用默认值）
pnpm init -y

# 导入已有项目的 lock 文件
pnpm import             # 从 package-lock.json/yarn.lock 导入

# 1. 删除旧的依赖和 lock 文件
rm -rf node_modules package-lock.json yarn.lock

# 2. 使用 pnpm 安装（会自动生成 pnpm-lock.yaml）
pnpm install

# 3. 更新项目文档，提示团队使用 pnpm

{
  "packageManager": "pnpm@8.15.0",
  "engines": {
    "node": ">=18.0.0",
    "pnpm": ">=8.0.0"
  },
  "scripts": {
    "preinstall": "npx only-allow pnpm"
  }
}

# .npmrc

# ========== 镜像源配置 ==========
registry=https://registry.npmmirror.com

# 特定 scope 使用不同的源
@mycompany:registry=https://npm.mycompany.com

# ========== 依赖提升配置 ==========
# 提升所有依赖（模拟扁平化结构，不推荐）
shamefully-hoist=true

# 只提升特定包
public-hoist-pattern[]=*eslint*
public-hoist-pattern[]=*prettier*

# ========== 安装行为配置 ==========
# 自动安装 peer dependencies
auto-install-peers=true

# 严格 peer dependencies 检查
strict-peer-dependencies=true

# 保存时的前缀（默认 ^）
save-prefix=~

# ========== 存储配置 ==========
# 自定义全局存储路径
store-dir=/path/to/pnpm-store

# ========== 其他配置 ==========
# 忽略特定依赖的脚本
ignore-scripts=true

# 模块目录名称
modules-dir=node_modules

# 侧缓存模式（适用于 CI）
side-effects-cache=true

# .npmrc

# 方式 1：完全提升（不推荐，会引入幽灵依赖）
shamefully-hoist=true

# 方式 2：只提升特定包（推荐）
public-hoist-pattern[]=*react-native*
public-hoist-pattern[]=*webpack*

# shamefully-hoist=true
node_modules/
├── .pnpm/
├── express/
├── accepts/      # 被提升上来了
├── debug/        # 被提升上来了
└── ...

# public-hoist-pattern（部分提升）
node_modules/
├── .pnpm/
├── express/      # 直接依赖
├── webpack/      # 匹配 pattern 被提升
└── ...

{
  "name": "my-project",
  "version": "1.0.0",
  
  "dependencies": {
    "express": "^4.18.0"
  },
  
  "devDependencies": {
    "typescript": "^5.0.0"
  },
  
  "pnpm": {
    "overrides": {
      "lodash": "4.17.21"          // 强制所有依赖使用此版本
    },
    "patchedDependencies": {
      "express@4.18.0": "patches/express@4.18.0.patch"
    },
    "peerDependencyRules": {
      "ignoreMissing": ["react"],   // 忽略缺失的 peer dependency
      "allowedVersions": {
        "react": "17"               // 允许 React 17
      }
    }
  }
}

my-monorepo/
├── pnpm-workspace.yaml    # workspace 配置文件
├── package.json           # 根项目配置
├── pnpm-lock.yaml
├── packages/              # 存放各个子项目
│   ├── core/
│   │   ├── package.json
│   │   └── src/
│   ├── utils/
│   │   ├── package.json
│   │   └── src/
│   └── web/
│       ├── package.json
│       └── src/
└── .npmrc

# pnpm-workspace.yaml
packages:
  - 'packages/*'           # packages 下的所有目录
  - 'apps/*'               # apps 下的所有目录
  - '!**/test/**'          # 排除 test 目录

// packages/web/package.json
{
  "name": "@my-org/web",
  "dependencies": {
    "@my-org/core": "workspace:*",     # 使用最新版本
    "@my-org/utils": "workspace:^1.0.0"  # 使用兼容版本
  }
}

# 在根目录执行递归命令
pnpm -r <command>                # 在所有子项目中执行命令
pnpm -r --filter <package> <cmd> # 在特定子项目中执行

# 示例
pnpm -r install                  # 安装所有子项目的依赖
pnpm -r run build                # 构建所有子项目
pnpm -r run test                 # 测试所有子项目

# 过滤执行
pnpm --filter web run dev        # 只在 web 项目运行 dev
pnpm --filter "@my-org/*" run build  # 在所有 @my-org 包中运行

# 按依赖顺序执行
pnpm -r run --sort build         # 按依赖顺序构建

# 并行执行
pnpm -r run --parallel dev       # 并行启动开发服务器

# 查看项目依赖图
pnpm list --depth=0 -r

# 只更新 workspace 内的包
pnpm update --workspace

my-ui-library/
├── pnpm-workspace.yaml
├── package.json
├── packages/
│   ├── components/          # 组件库
│   │   ├── package.json
│   │   └── src/
│   ├── theme/               # 主题包
│   │   ├── package.json
│   │   └── src/
│   └── utils/               # 工具函数
│       ├── package.json
│       └── src/
└── apps/
    ├── docs/                # 文档站点
    │   ├── package.json
    │   └── src/
    └── playground/          # 示例项目
        ├── package.json
        └── src/

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

// package.json（根目录）
{
  "name": "my-ui-library",
  "private": true,
  "scripts": {
    "build": "pnpm -r run build",
    "test": "pnpm -r run test",
    "dev": "pnpm --filter playground run dev"
  },
  "devDependencies": {
    "typescript": "^5.0.0"
  }
}

// packages/components/package.json
{
  "name": "@my-ui/components",
  "version": "1.0.0",
  "main": "dist/index.js",
  "dependencies": {
    "@my-ui/theme": "workspace:*",
    "@my-ui/utils": "workspace:*"
  }
}

// apps/docs/package.json
{
  "name": "@my-ui/docs",
  "dependencies": {
    "@my-ui/components": "workspace:*",
    "vitepress": "^1.0.0"
  }
}

# 自动安装 peer dependencies
pnpm config set auto-install-peers true

# 严格检查 peer dependencies（默认）
pnpm config set strict-peer-dependencies true

// package.json
{
  "pnpm": {
    "peerDependencyRules": {
      "ignoreMissing": ["react", "vue"],  // 忽略缺失
      "allowedVersions": {
        "react": "17 || 18",              // 允许的版本
        "typescript": "5"                 // 强制使用 TS 5
      }
    }
  }
}

// package.json
{
  "pnpm": {
    "overrides": {
      "lodash": "4.17.21",           // 所有 lodash 使用此版本
      "express@<4.18": "4.18.0",    // 指定版本范围
      "@types/node": "$types-node"   // 引用其他依赖
    }
  }
}

# 1. 创建补丁文件
pnpm patch express@4.18.0

# 输出: You can now edit the following folder: /tmp/abc123

# 2. 修改代码后提交补丁
pnpm patch-commit /tmp/abc123

// package.json
{
  "pnpm": {
    "patchedDependencies": {
      "express@4.18.0": "patches/express@4.18.0.patch"
    }
  }
}

diff --git a/lib/router/index.js b/lib/router/index.js
--- a/lib/router/index.js
+++ b/lib/router/index.js
@@ -10,7 +10,7 @@
 var parseUrl = require('parseurl');
 
 var proto = module.exports = function(options) {
-  var opts = options || {};
+  var opts = options || { mergeParams: true };
   ...

# 设置全局存储路径
PNPM_STORE_PATH=/path/to/store

# 设置缓存目录
PNPM_CACHE_DIR=/path/to/cache

# 设置配置文件路径
NPM_CONFIG_GLOBALCONFIG=/path/to/npmrc

# 使用 CI 模式
CI=true

# 设置并发数
npm_config_network_concurrency=16

# 查看
pnpm list                      # 列出依赖
pnpm list -g --depth=0         # 全局依赖
pnpm why <pkg>                 # 查看依赖原因
pnpm outdated                  # 检查过时的包
pnpm audit                     # 安全审计

# 清理
pnpm store prune               # 清理未使用的 store 包
pnpm store path                # 查看 store 路径

# 配置
pnpm config list               # 查看配置
pnpm config set <key> <value>  # 设置配置
pnpm config get <key>          # 获取配置

# 其他
pnpm pack                      # 打包项目
pnpm publish                   # 发布包
pnpm link                      # 创建软链接
pnpm unlink                    # 移除软链接

pnpm -r <cmd>                  # 递归执行
pnpm -r run build              # 构建所有
pnpm --filter <pkg> <cmd>      # 过滤执行
pnpm -r run --parallel dev     # 并行执行

# 方案 1：添加依赖声明
pnpm add <package>

# 方案 2：如果确实需要访问子依赖
pnpm add <package>

# 方案 3：临时使用提升模式（不推荐）
# .npmrc
shamefully-hoist=true

# .npmrc
# 提升特定包
public-hoist-pattern[]=*react-native*
public-hoist-pattern[]=*electron*
public-hoist-pattern[]=*webpack*

# 或完全提升（不推荐）
shamefully-hoist=true

// package.json
{
  "pnpm": {
    "peerDependencyRules": {
      "ignoreMissing": ["react"],
      "allowedVersions": {
        "react": "17 || 18"
      }
    }
  }
}

# 或自动安装 peer dependencies
pnpm config set auto-install-peers true

# .npmrc（CI 专用）
side-effects-cache=true
prefer-offline=true

# GitHub Actions 配置
- name: Setup pnpm
  uses: pnpm/action-setup@v2
  with:
    version: 8
    run_install: false

- name: Get pnpm store directory
  shell: bash
  run: |
    echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_OUTPUT
  id: pnpm-cache

- name: Setup pnpm cache
  uses: actions/cache@v3
  with:
    path: ${{ steps.pnpm-cache.outputs.STORE_PATH }}
    key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
    restore-keys: |
      ${{ runner.os }}-pnpm-store-

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

# 查看依赖关系
pnpm why lodash

# 输出示例
# lodash@4.17.21
#
# dependencies:
# express@4.18.2
# └── lodash@4.17.21

# 项目 A 和项目 B 都依赖 lodash@4.17.21
# 磁盘上只有一份实体文件

# 查看共享情况
pnpm store usages

# 导入其他包管理器的 lock 文件
pnpm import

# 支持导入：
# - package-lock.json (npm)
# - yarn.lock (Yarn)

FROM node:20-alpine

# 安装 pnpm
RUN corepack enable && corepack prepare pnpm@latest --activate

WORKDIR /app

# 复制依赖文件
COPY package.json pnpm-lock.yaml ./

# 安装依赖
RUN pnpm install --frozen-lockfile

# 复制代码
COPY . .

# 构建
RUN pnpm run build

CMD ["pnpm", "start"]