pnpm 软件包管理器速查指南：常用命令、Monorepo 工作区与高级用法详解-创锋一号

pnpm 软件包管理器速查指南：常用命令、Monorepo 工作区与高级用法详解

【免费下载链接】reference为开发人员分享快速参考备忘清单(速查表)项目地址: https://gitcode.com/jaywcjlove/reference

本指南基于开源参考仓库 jaywcjlove/reference 中的 docs/pnpm.md 备忘清单整理而成，系统讲解 pnpm 与 npm 的命令对应关系、依赖安装/更新/移除/缓存管理等核心操作，以及 Monorepo 工作区的创建与脚本编排、链接本地包等高级用法。读完本文，你将掌握一套可直接复制运行的 pnpm 命令清单，并理解--frozen-lockfile、--shamefully-hoist、--filter等高频参数的实际语义，能够在自己的前后端项目中平稳完成从 npm 到 pnpm 的迁移。

文档定位：面向开发者的命令速查表

本仓库（jaywcjlove/reference）是一个为开发人员整理的快速参考备忘清单集合，每个文档对应一门技术或一款工具。pnpm文档即其中一页，位于 docs/pnpm.md，README 的文档索引区（README.md）可以直接跳转到该页。它与其姊妹篇 docs/npm.md 形成对照，方便开发者在两套包管理器之间快速切换。

需要说明的是，本参考仓库自身的工程配置（见 package.json）使用的是 npm 脚本（如npm run build、npm run start、postinstall等），且仓库内不存在pnpm-lock.yaml或pnpm-workspace.yaml文件。因此本文的 pnpm 命令适用于你自己的项目——无论是从零初始化，还是将既有 npm 项目迁移到 pnpm，下面的内容都能直接上手。

入门：pnpm 与 npm 命令对照

pnpm 的设计目标是与 npm 保持命令级的兼容，绝大多数日常操作只需把npm替换为pnpm。下表是 pnpm 备忘清单给出的核心对照：

两个最容易踩坑的差异值得单独强调：

安装包的动词不同：npm 用install <package>，而 pnpm 统一使用add <package>。pnpm install只负责按package.json与锁文件安装全部依赖，不能直接跟包名。
全局安装用add -g：pnpm 没有npm install -g的对称写法，全局安装一律写作pnpm add -g <package>，全局卸载则是对应的pnpm remove -g <package>。

除上述高频命令外，npm 侧更完整的命令速查可参考本仓库的 docs/npm.md。

依赖管理核心命令与参数

pnpm install 及其选项

pnpm install用于按package.json和pnpm-lock.yaml安装项目全部依赖。备忘清单列出了以下常用选项：

这些选项在工程实践中各有明确用途：

--frozen-lockfile是 CI/CD 流水线的标配：它要求按锁文件原样安装，一旦pnpm-lock.yaml与package.json不一致就立即报错，从而保证每次构建的依赖树完全可复现。与之相对，日常开发中若想更新锁文件，应正常执行pnpm install或pnpm update。
--no-lockfile适用于临时验证场景，跳过锁文件生成，但生产项目不建议使用，否则会失去依赖可复现性。
--offline配合 pnpm 内容寻址的全局存储（store），可以在断网环境下复用本地缓存的包完成安装，非常适合离线开发或内网环境。
--shamefully-hoist让 pnpm 像 npm 那样把所有依赖提升到顶层node_modules，牺牲 pnpm 严格的隔离性来兼容某些依赖扁平布局的旧工具链。
--strict-peer-dependencies在 peer dependency 缺失或版本不匹配时直接报错（默认仅告警），适用于对依赖完整性要求苛刻的库开发场景。

pnpm add 及其选项

pnpm add负责向项目添加新依赖，常用选项如下：

要点解析：

--save是pnpm add的默认行为，等价于 npm 的--save-prod；--save-dev可简写为-D，将依赖写入devDependencies。
--exact会写入不带^或~前缀的精确版本号，适合对版本漂移零容忍的场景。
--global简写为-g，作用域从当前项目切换到全局环境，配合pnpm list -g可随时核查全局安装清单。

pnpm update：更新依赖

# 更新所有包 pnpm update # 更新特定包 pnpm update <package> # 更新到最新版本（包括 major 版本） pnpm update --latest

不带参数时，pnpm update在package.json声明的版本范围内更新依赖；
指定包名则只更新该包及其传递依赖；
默认行为不会跨过 major 版本（如^1.2.0不会升到2.x），需要跨大版本升级时使用--latest，它会无视版本范围约束直接取最新版。

pnpm remove：移除依赖

# 从依赖中删除包 pnpm remove <package> # 删除全局依赖包 pnpm remove -g create-react-app # 删除特定版本的依赖包 pnpm remove lodash@4.17.21

pnpm remove在删除依赖的同时会同步更新package.json与pnpm-lock.yaml，并清理该包在node_modules中不再被引用的孤立文件。指定版本号（如lodash@4.17.21）时，仅移除该精确版本条目。

pnpm list / outdated / why：查看依赖

# 列出所有已安装的包 pnpm list # 列出全局安装的包 pnpm list -g # 查找过时的包 pnpm outdated

pnpm list以树形结构输出当前项目的依赖（含传递依赖），pnpm list -g查看全局安装的包；
pnpm outdated扫描已安装依赖与最新版本之间的差距，输出存在新版本的包列表；
pnpm why <package>用于回答“为什么这个包被安装了”——它会沿依赖图回溯，展示究竟是哪个顶层依赖把它间接引入，这对排查重复依赖、幽灵依赖问题非常关键。

pnpm prune：清理未使用依赖

# 清理 node_modules 并删除不必要的文件 pnpm prune

pnpm prune会移除package.json中不再声明的包，清理node_modules中多余的文件，适合在切换分支、删改依赖后让本地环境与清单重新对齐。

pnpm cache：缓存管理

# 清理 pnpm 缓存 pnpm cache clean # 查看缓存中所有的包 pnpm cache list

pnpm 使用全局内容寻址存储（store）缓存所有下载过的包，跨项目共享，因此磁盘占用更小、安装更快。pnpm cache list列出 store 中缓存的全部包；pnpm cache clean清空缓存。此外，您还可以指定一个或多个包名进行定向清理，避免全量清空导致后续安装需要重新下载。

实战示例：安装、移除、查看与清理

以下示例组合可直接粘贴到终端使用。

安装包

# 将包添加到“dependencies” pnpm add <package> # 将包添加到“devDependencies” pnpm add -D <package> # 将包作为精确版本添加 pnpm add --exact <package> # 在全局范围内安装包 pnpm add -g <package> # 安装特定版本的包 pnpm add <package>@<version>

移除包

pnpm remove <package> # 删除多个依赖包 pnpm remove lodash express # 删除全局依赖包 pnpm remove -g create-react-app # 删除特定版本的依赖包 pnpm remove lodash@4.17.21

查看包

# 列出已安装的包 pnpm list # 列出顶级安装的包 pnpm list --depth 0 # 列出全局安装的包 pnpm list -g # 根据模式和深度列出包 pnpm list --pattern "lodash" --depth 1

--depth控制依赖树的展开层级：--depth 0只显示package.json直接声明的顶层依赖；--pattern按名称模式过滤，--depth 1则额外展开一层传递依赖，便于快速定位某个包被谁直接引用。

清除

# 清理 node_modules 并删除不必要的文件 pnpm prune # 检查过时的包 pnpm outdated

信息

# 显示关于安装包的原因的信息 pnpm why <package>

清理缓存

# 清除 pnpm 的全局缓存 pnpm cache clean

Monorepo 工作区：从初始化到脚本编排

pnpm 对 Monorepo 的原生支持是其最受欢迎的特性之一。通过pnpm-workspace.yaml声明工作区，即可用一个仓库管理多个互相引用的包，并且 pnpm 会为工作区内的包自动建立符号链接。

创建 Monorepo 工作区

创建一个新的 pnpm 工作区：
```
pnpm init -w
```
该命令会在项目的根目录中创建一个pnpm-workspace.yaml文件，内容如下：
```
packages: - 'packages/**' - 'apps/**'
```
在pnpm-workspace.yaml中定义您的工作区结构：
```
packages: - 'packages/*' - 'apps/*'
```

pnpm init -w中的-w表示在工作区根目录执行初始化，它同时会在根目录生成package.json与pnpm-workspace.yaml。packages列表中的 glob 模式决定了哪些目录会被视为独立包，既可以用packages/**递归匹配任意层级，也可以用packages/*只匹配一级子目录，按实际目录深度灵活选择。

添加包到 Monorepo 工作区

pnpm add <package> -w # 在工作区中添加包

-w把依赖安装到工作区根目录，使其对所有子包可见。若要添加开发依赖到根目录，使用pnpm add -D <package> -w。

运行脚本

# 在所有包中运行脚本 pnpm -r run <script> # 仅在某个包中运行脚本 pnpm --filter <package> run <script> # 在某个包及其依赖中运行脚本 pnpm --filter <package>... run <script>

-r（recursive）遍历工作区中所有包含该脚本的包依次执行；
--filter <package>把执行范围限定到指定包；
--filter <package>...是 filter 的一个常用变体，尾部的省略号表示连同该包的所有依赖包一起执行，适合“先构建依赖、再构建自身”的场景，例如在根目录跑pnpm --filter @my/app... run build时，会先构建@my/app依赖的各个子包。

创建新的包

在packages目录中创建新的包，例如：

mkdir packages/new-package cd packages/new-package pnpm init

先mkdir建目录、cd进入后执行pnpm init生成该包的package.json。因为目录已处于工作区声明的packages/**模式之内，pnpm 会自动将其识别为工作区成员。

链接本地包

# 将本地包链接到当前工作区 pnpm link <local-package-path> # 链接工作区中的包 pnpm add <local-package-name> --workspace

pnpm link <local-package-path>以目录路径为参数，把本地开发中的包软链接进当前项目；而pnpm add <local-package-name> --workspace则按包名把工作区内的另一个成员作为依赖安装，pnpm 会自动解析为本地链接而非远端 registry 版本——这正是 Monorepo 内部包互相引用的标准做法。

高级用法：工作区、链接与脚本

工作区

# 创建工作区 pnpm init -w # 在工作区中添加包 pnpm add <package> -w

这两条命令是高频组合：先用pnpm init -w在根目录建立工作区骨架，再通过-w向根目录注入共享依赖。

链接

# 链接一个全局包到当前项目 pnpm link <package> # 链接本地包到全局 pnpm link --global <package>

pnpm link <package>把全局已安装的包链接到当前项目，用于在本地开发时替换远端版本；
pnpm link --global <package>（简写-g）方向相反，把当前目录的包链接到全局，便于在其他项目中直接pnpm link引用仍在开发的本地包。

运行脚本

# 运行 package.json 中的脚本 pnpm run <script> # 运行根目录中的包的脚本 pnpm run -w <script>

pnpm run <script>与 npm 行为一致，执行当前目录package.json中scripts里定义的命令；-w则将执行位置锁定到工作区根目录，配合pnpm -r run <script>可在整个工作区批量执行。

在参考仓库中的延伸阅读

备忘清单正文：docs/pnpm.md 是本文的原始依据，包含上述全部命令与参数的精简表格，适合日常速查；
npm 对照条目：docs/npm.md 提供 npm 侧的完整命令清单，可与本文对照学习两套包管理器的异同；
仓库工程配置：package.json 展示了本参考仓库自身的脚本组织方式（build、start、cpy、prettier、markdownlint），可作为pnpm run/pnpm -r run脚本编排的实际参照；
索引入口：README.md 在文档索引中收录了 pnpm 条目，可以从仓库首页直接跳转到本备忘清单。

在动手迁移前，建议先用pnpm --version确认本机 pnpm 已安装；迁移既有项目时，先删除node_modules与package-lock.json，再执行pnpm install生成pnpm-lock.yaml。pnpm 官方的文档与常见问题解答（FAQ）对动机、存储布局与迁移细节有更系统的说明，可作为深入学习时的补充资料。

【免费下载链接】reference为开发人员分享快速参考备忘清单(速查表)项目地址: https://gitcode.com/jaywcjlove/reference

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析