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，讓你的項目開發更高效！🚀