pnpm安装与使用完整指南

未分类 9 小时前 0 1

pnpm安装与使用完整指南

一、pnpm简介

1.1 什么是pnpm？

pnpm（Performant npm）是一个高性能的Node.js包管理工具，由Zoltan Kochan开发并开源。相比于npm和yarn，pnpm具有更快的安装速度和更低的磁盘占用。

pnpm的核心特点：

节省磁盘空间：使用硬链接和符号链接共享依赖
安装速度快：比npm快2-10倍
严格模式：防止意外依赖
内容寻址存储：每个包只存储一份
支持monorepo：原生支持多包管理

1.2 pnpm vs npm vs yarn

特性	pnpm	npm	yarn
安装速度	最快	慢	中等
磁盘占用	最低	高	中等
node_modules结构	非扁平	扁平	扁平
锁定文件	pnpm-lock.yaml	package-lock.json	yarn.lock
monorepo支持	原生	需workspace	需workspace

二、安装pnpm

2.1 使用npm安装（推荐）


# 使用npm全局安装
npm install -g pnpm

# 验证安装
pnpm --version

# 查看帮助
pnpm --help

2.2 使用Corepack安装（Node.js 16.13+）


# 启用Corepack
corepack enable

# 安装pnpm
corepack prepare pnpm@latest --activate

# 验证安装
pnpm --version

2.3 使用Homebrew安装（macOS）


# 安装Homebrew（如果未安装）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装pnpm
brew install pnpm

# 验证安装
pnpm --version

2.4 使用Scoop安装（Windows）


# 安装Scoop（如果未安装）
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
irm get.scoop.sh | iex

# 安装pnpm
scoop install pnpm

# 验证安装
pnpm --version

2.5 使用Cargo安装（Rust）


# 安装Rust（如果未安装）
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# 安装pnpm
cargo install pnpm

# 验证安装
pnpm --version

2.6 使用Shell脚本安装（Linux/macOS）


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

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

# 添加到环境变量
export PNPM_HOME="$HOME/.local/share/pnpm"
export PATH="$PNPM_HOME:$PATH"

2.7 手动安装（手动下载）


# 下载pnpm二进制文件
wget https://github.com/pnpm/pnpm/releases/download/v8.10.0/pnpm-linux-x64 -O pnpm

# 添加执行权限
chmod +x pnpm

# 移动到系统路径
sudo mv pnpm /usr/local/bin/

# 或添加到个人路径
mkdir -p ~/.local/bin
mv pnpm ~/.local/bin/

# 添加到PATH（添加到~/.bashrc或~/.zshrc）
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# 验证安装
pnpm --version

三、配置pnpm

3.1 配置镜像源

国内访问pnpm官方源较慢，建议配置国内镜像。


# 查看当前配置
pnpm config get registry

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

# 查看所有配置
pnpm config list

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

3.2 配置其他选项


# 设置安装目录
pnpm config set pnpm-home ~/.local/pnpm

# 设置缓存目录
pnpm config set cache-dir ~/.pnpm-cache

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

# 设置包管理器
pnpm config set package-manager-strict false

3.3 创建.pnpmrc配置文件

在项目根目录创建 .pnpmrc 文件：


# pnpm配置文件示例

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

# 依赖安装目录
modules-dir=node_modules

# 缓存目录
cache-dir=.pnpm-cache

# peer dependencies自动安装
auto-install-peers=true

# 严格模式
strict-peer-dependencies=false

# 包管理器
package-manager=pnpm@8.10.0

# Shell脚本配置
prefer-offline=true

四、使用pnpm

4.1 初始化项目


# 初始化新项目
pnpm init

# 初始化并跳过交互式问答
pnpm init -y

# 使用特定配置初始化
pnpm init --yes --name my-project --description "My awesome project"

4.2 安装依赖


# 安装所有依赖
pnpm install

# 安装指定包
pnpm add package-name

# 安装开发依赖
pnpm add -D package-name
pnpm add --save-dev package-name

# 安装peer dependencies
pnpm add -P package-name
pnpm add --save-peer package-name

# 安装可选依赖
pnpm add -O package-name
pnpm add --save-optional package-name

# 安装全局包
pnpm add -g package-name

# 安装特定版本
pnpm add package@1.2.3
pnpm add package@^1.0.0

# 从package.json安装
pnpm install package-name

# 强制重新安装
pnpm install --force
pnpm install --no-frozen-lockfile

4.3 更新依赖


# 更新所有依赖
pnpm update

# 更新指定包
pnpm update package-name

# 更新到最新版本
pnpm up package-name

# 更新主版本
pnpm up --latest package-name

# 更新所有到最新版本
pnpm up --latest

# 检查可用的更新
pnpm outdated

4.4 移除依赖


# 移除指定包
pnpm remove package-name
pnpm rm package-name
pnpm uninstall package-name

# 移除开发依赖
pnpm remove -D package-name

# 移除全局包
pnpm remove -g package-name

# 移除未使用的包
pnpm prune

4.5 运行脚本


# 查看可用的scripts
pnpm run

# 运行特定脚本
pnpm run build
pnpm run dev
pnpm run start

# 运行脚本（可省略run）
pnpm build
pnpm dev
pnpm start

# 带参数运行
pnpm run build -- --production

4.6 其他常用命令


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

# 查看全局包
pnpm list -g

# 查看包信息
pnpm info package-name

# 查看包的所有版本
pnpm view package-name versions

# 查看特定版本信息
pnpm view package-name@1.2.3

# 搜索包
pnpm search package-name
pnpm se package-name

# 查看包的依赖树
pnpm why package-name

# 清理缓存
pnpm store prune

# 清理node_modules
pnpm clear

五、pnpm workspace

5.1 创建monorepo


# 创建项目目录
mkdir my-monorepo
cd my-monorepo

# 初始化pnpm workspace
pnpm init

# 创建workspace配置文件
touch pnpm-workspace.yaml

5.2 配置pnpm-workspace.yaml


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

# 可选配置
onlyBuiltDependencies:
  - '@babel/core'
  - 'node-gyp'

# 设置共享的依赖
sharedWorkspaceDependencies: true

5.3 在workspace中使用


# 在workspace根目录安装
pnpm install

# 在子包中安装
cd packages/my-lib
pnpm add some-package

# 在根目录为所有包安装依赖
pnpm add -r some-package

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

# 过滤特定包运行
pnpm --filter "my-app" run dev

5.4 workspace常用命令


# 添加依赖到特定包
pnpm --filter my-app add react

# 为所有包添加依赖
pnpm -r add typescript

# 运行所有包的命令
pnpm -r run test

# 构建所有包
pnpm -r run build

# 发布所有包（需要配置）
pnpm -r publish

六、常见问题解决

6.1 权限问题

问题现象： Permission denied

解决方法：


# 方法1：修改npm配置
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin' >> ~/.bashrc
source ~/.bashrc

# 方法2：使用pnpm的全局安装
pnpm config set global-bin-dir ~/.local/bin

# 方法3：修复node_modules权限
sudo chown -R $(whoami) ~/.pnpm-store

6.2 网络问题

问题现象： 下载超时或失败

解决方法：


# 配置国内镜像
pnpm config set registry https://registry.npmmirror.com

# 清理缓存后重试
pnpm store prune
pnpm install

# 使用其他镜像源
pnpm config set registry https://registry.npmmirror.com

6.3 依赖版本冲突

问题现象： 依赖版本不兼容

解决方法：


# 查看依赖冲突
pnpm why package-name

# 强制更新
pnpm up --latest

# 使用overrides覆盖版本
# 在package.json中添加
{
  "pnpm": {
    "overrides": {
      "react": "^18.0.0"
    }
  }
}

6.4 缓存问题

问题现象： 安装旧版本失败或缓存错误

解决方法：


# 清理store缓存
pnpm store prune

# 强制重新下载
pnpm install --force

# 清理node_modules
rm -rf node_modules
pnpm install

6.5 幽灵依赖问题

问题现象： 意外访问了未声明的依赖

解决方法：


# 启用严格模式
pnpm config set strict-peer-dependencies true

# 使用hoist=false（workspace默认）
# 在pnpm-workspace.yaml中
packageExtensions:
  react-v18:
    peerDependencies:
      react: ^18.0.0

七、pnpm脚本配置示例

7.1 package.json示例


{
  "name": "my-project",
  "version": "1.0.0",
  "description": "My awesome project",
  "main": "index.js",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview",
    "lint": "eslint src --ext .vue,.js,.ts,.jsx,.tsx",
    "format": "prettier --write src/",
    "test": "vitest",
    "test:coverage": "vitest --coverage"
  },
  "keywords": [
    "vue",
    "vite",
    "pnpm"
  ],
  "author": "Your Name",
  "license": "MIT",
  "devDependencies": {
    "@vitejs/plugin-vue": "^4.0.0",
    "vite": "^5.0.0",
    "vitest": "^1.0.0",
    "eslint": "^8.0.0",
    "prettier": "^3.0.0"
  },
  "dependencies": {
    "vue": "^3.0.0"
  },
  "pnpm": {
    "overrides": {
      "vue": "^3.0.0"
    }
  }
}

7.2 .npmrc配置示例


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

# 开发环境配置
save-exact=false
save-prefix=^

# 性能配置
modules-dir=node_modules
cache-dir=.pnpm-cache

# peer dependencies
auto-install-peers=true
strict-peer-dependencies=false

# 包管理器
package-manager=pnpm@8.10.0

# 其他配置
prefer-offline=false
no-strict-peer-dependencies=false

八、pnpm最佳实践

8.1 项目结构推荐


my-project/
├── pnpm-workspace.yaml          # workspace配置
├── pnpm-lock.yaml              # 锁定文件（提交到Git）
├── .npmrc                      # pnpm配置
├── .pnpmfile.cjs              # pnpm脚本
├── package.json               # 根目录package.json（可选）
├── apps/
│   ├── web/                  # Web应用
│   │   ├── package.json
│   │   ├── pnpm-workspace.yaml
│   │   ├── vite.config.ts
│   │   └── src/
│   └── admin/                # 管理后台
│       └── package.json
├── packages/
│   ├── shared/               # 共享包
│   │   ├── package.json
│   │   └── src/
│   ├── ui/                   # UI组件库
│   │   ├── package.json
│   │   └── src/
│   └── utils/                # 工具函数
│       └── package.json
├── tools/
│   └── eslint-config/       # ESLint配置
│       └── package.json
├── docs/                      # 文档
├── README.md
└── .gitignore

8.2 Git提交规范


# .gitignore配置
node_modules/
.pnpm-store/
dist/
build/
.env*.local

# 保留锁定文件
!pnpm-lock.yaml

8.3 CI/CD配置


# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

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'

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

      - name: Run lint
        run: pnpm run lint

      - name: Run build
        run: pnpm run build

九、卸载pnpm

9.1 卸载全局安装的pnpm


# 使用npm卸载
npm uninstall -g pnpm

# 使用Homebrew卸载
brew uninstall pnpm

# 手动删除
rm -rf ~/.local/share/pnpm
rm -rf ~/.pnpm-store
rm ~/.npmrc

# 从PATH中移除
# 编辑 ~/.bashrc 或 ~/.zshrc
# 删除以下行：
# export PNPM_HOME="$HOME/.local/share/pnpm"
# export PATH="$PNPM_HOME:$PATH"

9.2 清理项目


# 删除node_modules
rm -rf node_modules

# 删除缓存
rm -rf .pnpm-cache
rm -rf ~/.pnpm-store

# 删除锁定文件
rm pnpm-lock.yaml

十、总结

本文详细介绍了pnpm的安装、配置和使用方法，包括：

✅ pnpm简介 - 特点、优势、对比 ✅ 多种安装方式 - npm、Corepack、Homebrew、手动安装 ✅ 配置pnpm - 镜像源、配置文件 ✅ 基本使用 - 安装、更新、移除、运行脚本 ✅ workspace - monorepo配置和使用 ✅ 常见问题 - 权限、网络、依赖冲突 ✅ 最佳实践 - 项目结构、Git规范、CI/CD ✅ 卸载pnpm - 清理和卸载步骤

pnpm的核心优势：

1. 节省磁盘空间：硬链接共享依赖，减少重复存储 2. 安装速度快：比npm快2-10倍 3. 严格的依赖管理：防止意外依赖 4. 良好的monorepo支持：原生workspace支持 5. 内容寻址存储：每个包只存储一份

学习建议：

1. 从小项目开始使用pnpm 2. 熟悉pnpm和npm的差异 3. 学习pnpm workspace进行项目管理 4. 在团队中推广pnpm

下一步学习：

学习pnpm的高级配置
掌握pnpm workspace最佳实践
学习与Docker配合使用
探索pnpm插件系统

相关资源：

pnpm官网：https://pnpm.io/
pnpm GitHub：https://github.com/pnpm/pnpm
pnpm文档：https://pnpm.io/zh/motivation
npm镜像源：https://registry.npmmirror.com
awesome-pnpm：https://github.com/pnpm/awesome-pnpm

参考阅读：

[pnpm官方文档](https://pnpm.io/zh/)
[npm官方文档](https://docs.npmjs.com/)
[Node.js官方文档](https://nodejs.org/zh-cn/docs/)
[Vite官方文档](https://cn.vitejs.dev/)
[Monorepo最佳实践](https://pnpm.io/zh/workspaces)

声明：本站所有文章，如无特殊说明或标注，均为本站原创发布。任何个人或组织，在未征得本站同意时，禁止复制、盗用、采集、发布本站内容到任何网站、书籍等各类媒体平台。如若本站内容侵犯了原著者的合法权益，可联系我们进行处理。

pnpm安装与使用完整指南

一、pnpm简介

1.1 什么是pnpm？

1.2 pnpm vs npm vs yarn

二、安装pnpm

2.1 使用npm安装（推荐）

2.2 使用Corepack安装（Node.js 16.13+）

2.3 使用Homebrew安装（macOS）

2.4 使用Scoop安装（Windows）

2.5 使用Cargo安装（Rust）

2.6 使用Shell脚本安装（Linux/macOS）

2.7 手动安装（手动下载）

三、配置pnpm

3.1 配置镜像源

3.2 配置其他选项

3.3 创建.pnpmrc配置文件

四、使用pnpm

4.1 初始化项目

4.2 安装依赖

4.3 更新依赖

4.4 移除依赖

4.5 运行脚本

4.6 其他常用命令

五、pnpm workspace

5.1 创建monorepo

5.2 配置pnpm-workspace.yaml

5.3 在workspace中使用

5.4 workspace常用命令

六、常见问题解决

6.1 权限问题

6.2 网络问题

6.3 依赖版本冲突

6.4 缓存问题

6.5 幽灵依赖问题

七、pnpm脚本配置示例

7.1 package.json示例

7.2 .npmrc配置示例

八、pnpm最佳实践

8.1 项目结构推荐

8.2 Git提交规范

8.3 CI/CD配置

九、卸载pnpm

9.1 卸载全局安装的pnpm

9.2 清理项目

十、总结

相关文章

发表回复 取消回复

发表回复取消回复