2026年 pnpm 安装与使用教程:从环境配置到项目依赖管理
2026年 pnpm 安装与使用教程:从环境配置到项目依赖管理
SEO关键词: pnpm安装教程、pnpm怎么安装、Windows安装pnpm、Node.js安装pnpm、pnpm使用方法、pnpm替代npm、pnpm配置国内镜像
文章摘要: pnpm 是一款高性能的 Node.js 包管理工具,具有安装速度快、磁盘占用低、依赖管理严格等特点。本文介绍 2026 年 pnpm 的安装方法,涵盖 Node.js 环境配置、Windows 安装、PowerShell 命令、镜像源配置、项目依赖安装以及常见问题解决,帮助开发者快速搭建 pnpm 开发环境。
一、什么是 pnpm?
pnpm(Performant npm)是一款面向 Node.js 项目的现代化包管理工具,主要用于安装、管理和维护项目依赖。
在传统前端开发中,开发者通常使用 npm 或 Yarn 管理依赖包。但随着项目规模不断扩大,依赖数量越来越多,传统包管理方式在磁盘占用和安装效率方面逐渐暴露出一些问题。
pnpm 通过独特的依赖存储机制解决了这些问题。
它的主要特点包括:
-
节省磁盘空间: 多个项目可以共享同一份依赖包内容,减少重复存储。
-
安装速度快: 通过内容寻址存储和硬链接等机制,提高依赖安装效率。
-
依赖管理严格: 默认情况下,项目只能访问正确声明的依赖,减少幽灵依赖问题。
-
兼容 npm 生态: 可以使用大部分 npm 包和常见 Node.js 开发工具。
-
支持 Monorepo: 可以在一个仓库中统一管理多个子项目。
对于 Vue、React、Vite、Nuxt 等前端项目,pnpm 都是比较成熟的选择。
二、安装 pnpm 前需要准备什么?
安装 pnpm 之前,需要先准备 Node.js 运行环境。
Node.js 是 JavaScript 的服务端运行环境,而 npm 通常会随着 Node.js 一起安装。
打开 Windows PowerShell,执行:
node -v
npm -v
如果能够正常显示版本号,说明 Node.js 和 npm 已经安装成功。
例如:
v22.18.0
10.9.3
如果提示找不到 node 命令,说明当前系统尚未正确安装 Node.js,或者环境变量没有配置。
建议优先使用 Node.js LTS 版本,避免使用过旧的运行环境导致依赖兼容性问题。
三、Windows 安装 pnpm 的方法
Windows 用户可以通过多种方式安装 pnpm,下面介绍几种常见方法。
1. 使用 npm 安装 pnpm
这是比较直接的安装方式。
打开 PowerShell,执行:
npm install -g pnpm
其中:
-
npm install:安装依赖包。 -
-g:表示全局安装。 -
pnpm:需要安装的包管理工具。
等待安装完成后,执行:
pnpm -v
如果能够显示版本号,就说明安装成功。
2. 使用 Corepack 安装 pnpm
Corepack 是 Node.js 提供的包管理器版本管理工具,可以帮助开发者管理 pnpm、Yarn 等工具的版本。
在支持 Corepack 的 Node.js 环境中,可以执行:
corepack enable
然后启用 pnpm:
corepack prepare pnpm@latest --activate
最后检查版本:
pnpm -v
需要注意,不同 Node.js 版本内置的 Corepack 情况有所不同。较新的 Node.js 版本可能需要单独安装 Corepack,具体取决于发行版本。
3. 使用独立安装脚本
pnpm 也提供独立安装方式,可以通过官方安装脚本或 Windows 对应的安装工具完成配置。
对于普通 Windows 开发环境,使用 npm 全局安装通常已经足够。
四、解决 pnpm 命令无法识别的问题
部分 Windows 用户在安装 pnpm 后,执行:
pnpm -v
可能会出现类似错误:
pnpm : The term 'pnpm' is not recognized as the name of a cmdlet
这通常意味着 pnpm 没有正确安装,或者系统无法通过 PATH 环境变量找到 pnpm。
可以按照以下步骤排查。
1. 检查 pnpm 是否安装成功
执行:
npm list -g --depth=0
查看全局依赖列表中是否存在 pnpm。
如果没有,可以重新安装:
npm install -g pnpm
2. 查看 npm 全局安装目录
执行:
npm config get prefix
Windows 常见的 npm 全局安装目录类似:
C:\Users\用户名\AppData\Roaming\npm
检查这个目录是否存在。
3. 检查环境变量
在 Windows 搜索框中输入:
编辑系统环境变量
进入环境变量配置页面,找到用户变量中的 Path。
确认 npm 全局安装目录已经添加进去。
如果没有,可以手动添加:
C:\Users\用户名\AppData\Roaming\npm
保存后重新打开 PowerShell,再执行:
pnpm -v
注意:修改环境变量后,已经打开的终端通常不会自动获取最新配置,需要重新启动终端。
五、配置 pnpm 国内镜像源
在国内开发环境中,如果直接从默认 npm 仓库下载依赖,可能会遇到下载速度较慢、连接超时等问题。
可以将 pnpm 的 registry 修改为国内镜像源。
执行:
pnpm config set registry https://registry.npmmirror.com
查看当前配置:
pnpm config get registry
如果返回:
https://registry.npmmirror.com
说明配置成功。
如果后续需要恢复默认仓库,可以执行:
pnpm config set registry https://registry.npmjs.org/
需要注意,镜像源可能存在同步延迟。如果遇到某个依赖无法下载,可以检查包是否已经同步,或者临时切换回官方仓库。
六、pnpm 常用命令
安装 pnpm 后,就可以在 Node.js 项目中使用它管理依赖。
下面整理了一些日常开发中比较常用的命令。
|
命令 |
作用 |
|---|---|
|
|
初始化项目 |
|
|
安装项目全部依赖 |
|
|
安装项目依赖 |
|
|
安装生产依赖 |
|
|
安装开发依赖 |
|
|
删除依赖 |
|
|
更新依赖 |
|
|
查看依赖列表 |
|
|
查看依赖存储目录 |
|
|
运行开发脚本 |
|
|
执行项目构建 |
1. 安装项目依赖
进入项目目录:
cd F:\code\my-project
执行:
pnpm install
pnpm 会读取项目中的 package.json 和锁定文件,安装对应的依赖。
如果项目中存在 pnpm-lock.yaml,pnpm 会优先按照锁定文件安装依赖版本。
2. 安装单个依赖
例如安装 axios:
pnpm add axios
安装开发依赖:
pnpm add -D typescript
这两种方式的区别在于:
-
pnpm add:添加到项目的 dependencies。 -
pnpm add -D:添加到项目的 devDependencies。
3. 删除依赖
如果项目不再使用某个依赖,可以执行:
pnpm remove axios
pnpm 会同步更新项目依赖配置和锁定文件。
4. 运行项目
假设项目的 package.json 中配置了:
{
"scripts": {
"dev": "vite --host 0.0.0.0",
"build": "vite build"
}
}
启动开发环境:
pnpm dev
执行生产构建:
pnpm build
pnpm 支持直接运行项目中定义的脚本,不需要每次都输入完整的 pnpm run。
七、pnpm、npm 和 Yarn 有什么区别?
npm、Yarn 和 pnpm 都属于 Node.js 生态中的包管理工具,但它们在依赖存储和管理方式上存在明显区别。
|
对比项目 |
npm |
Yarn |
pnpm |
|---|---|---|---|
|
安装速度 |
较快 |
较快 |
较快 |
|
磁盘占用 |
相对较高 |
视版本和配置而定 |
通常较低 |
|
依赖管理 |
支持 |
支持 |
更严格 |
|
锁定文件 |
package-lock.json |
yarn.lock |
pnpm-lock.yaml |
|
Monorepo |
支持 |
支持 |
原生支持 |
|
依赖共享 |
有缓存机制 |
有缓存机制 |
内容寻址存储 |
pnpm 最大的特点是依赖存储机制。
传统项目可能会在每个项目的 node_modules 中保存大量重复依赖。
而 pnpm 默认使用全局内容寻址存储,将相同内容的依赖文件集中存储,再通过硬链接和符号链接等方式组织项目依赖。
例如:
项目A
└── node_modules
└── vue
项目B
└── node_modules
└── vue
项目C
└── node_modules
└── vue
如果三个项目使用相同版本的 Vue,pnpm 可以复用底层存储的文件,减少重复占用。
这对于同时维护多个 Vue、React 或 Node.js 项目的开发者比较有价值。
八、pnpm 如何管理 Monorepo 项目?
Monorepo 是一种代码仓库管理模式,可以将多个项目或业务模块放在同一个代码仓库中统一管理。
例如:
my-workspace
├── apps
│ ├── admin
│ ├── mobile
│ └── web
├── packages
│ ├── ui
│ ├── utils
│ └── config
├── package.json
└── pnpm-workspace.yaml
在根目录创建 pnpm-workspace.yaml:
packages:
- 'apps/*'
- 'packages/*'
然后在根目录执行:
pnpm install
pnpm 就可以统一管理仓库中不同子项目的依赖。
如果 admin 项目需要使用内部的 utils 包,可以通过 workspace 协议声明:
{
"dependencies": {
"utils": "workspace:*"
}
}
这种方式可以让多个子项目共享内部组件和工具库,减少重复开发。
对于大型前端项目、组件库以及多端业务系统,Monorepo 是一种值得考虑的工程组织方式。
九、pnpm 常见问题
1. pnpm install 安装失败怎么办?
可以按照以下顺序排查:
-
检查 Node.js 版本是否满足项目要求。
-
检查网络连接和 registry 配置。
-
删除异常的安装目录后重新安装。
-
检查 package.json 是否存在格式错误。
-
检查 pnpm-lock.yaml 是否与当前项目配置兼容。
可以尝试:
pnpm install --force
该命令会强制重新安装依赖,但不建议在没有排查原因的情况下频繁使用。
2. 如何清理 pnpm 缓存?
查看 pnpm 存储目录:
pnpm store path
检查存储空间:
pnpm store status
清理未被项目引用的存储内容:
pnpm store prune
需要注意,清理后如果项目再次需要这些依赖,可能需要重新下载。
3. npm 项目可以直接使用 pnpm 吗?
大部分情况下可以。
如果项目原本使用 npm,可以进入项目目录执行:
pnpm import
pnpm 可以根据现有的 package-lock.json 或 yarn.lock 生成 pnpm-lock.yaml。
之后执行:
pnpm install
建议团队统一使用一种包管理工具,避免 npm、Yarn 和 pnpm 混用造成锁定文件不一致。
4. pnpm 是否支持 Windows?
支持。
pnpm 可以在 Windows、Linux 和 macOS 上运行。
Windows 用户可以在 PowerShell、CMD、Windows Terminal 等终端中使用 pnpm。
不过,在 Windows 上需要注意文件系统、符号链接权限以及杀毒软件对文件操作的影响。如果项目安装依赖时出现链接相关错误,可以检查当前用户权限和项目所在磁盘的文件系统。
十、总结
pnpm 是目前 Node.js 和前端工程化开发中值得使用的包管理工具。
相比传统 npm,pnpm 在依赖存储、磁盘空间利用和依赖隔离方面具有明显特点。对于需要同时维护多个前端项目的开发者来说,pnpm 可以减少重复依赖存储,也能够通过统一的锁定文件提高团队开发环境的一致性。
对于 Vue、React、Vite、TypeScript 等项目,可以优先考虑使用 pnpm。
如果是新项目,建议直接使用 pnpm 初始化和管理依赖;如果是已有项目,则需要先检查依赖配置和锁定文件,再进行迁移。
最终建议: 普通前端项目使用 pnpm 完全足够,大型项目可以结合 pnpm Workspace 管理 Monorepo。安装工具本身并不复杂,真正需要重视的是依赖版本管理、团队开发规范以及持续集成环境的一致性。
- 点赞
- 收藏
- 关注作者
评论(0)