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.mdREADME 的文档索引区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 | pnpm | 说明 | | :- | :- | :- | |npm install|pnpm install| 安装依赖 | |npm init|pnpm init| 创建package.json文件 | |npm install package|pnpm add package| 安装包 | |npm install -g package|pnpm add -g package| 全局安装包 | |npm update|pnpm update| 更新包 | |npm cache clean|pnpm cache clean| 清理缓存 |两个最容易踩坑的差异值得单独强调安装包的动词不同npm 用install package而 pnpm 统一使用add package。pnpm install只负责按package.json与锁文件安装全部依赖不能直接跟包名。全局安装用add -gpnpm 没有npm install -g的对称写法全局安装一律写作pnpm add -g package全局卸载则是对应的pnpm remove -g package。除上述高频命令外npm 侧更完整的命令速查可参考本仓库的 docs/npm.md。依赖管理核心命令与参数pnpm install 及其选项pnpm install用于按package.json和pnpm-lock.yaml安装项目全部依赖。备忘清单列出了以下常用选项| pnpm | 说明 | | :- | :- | |--no-lockfile| 不生成 pnpm-lock.yaml 锁定文件 | |--force| 强制覆盖现有的 node_modules | |--frozen-lockfile| 忽略 pnpm-lock.yaml 中的更改 | |--offline| 离线模式不尝试从远程仓库安装包 | |--shamefully-hoist| 类似于 npm 的 hoist 行为 | |--strict-peer-dependencies| 严格检查 peer dependencies |这些选项在工程实践中各有明确用途--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负责向项目添加新依赖常用选项如下| pnpm | 说明 | | :- | :- | |--save| 将包添加到 dependencies | |--save-dev| 将包添加到 devDependencies | |--global| 全局安装包 | |--exact| 安装精确版本号的包 | |--shamefully-hoist| 类似于 npm 的 hoist 行为 | |--strict-peer-dependencies| 严格检查 peer dependencies |要点解析--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 lodash4.17.21pnpm remove在删除依赖的同时会同步更新package.json与pnpm-lock.yaml并清理该包在node_modules中不再被引用的孤立文件。指定版本号如lodash4.17.21时仅移除该精确版本条目。pnpm list / outdated / why查看依赖# 列出所有已安装的包 pnpm list # 列出全局安装的包 pnpm list -g # 查找过时的包 pnpm outdatedpnpm list以树形结构输出当前项目的依赖含传递依赖pnpm list -g查看全局安装的包pnpm outdated扫描已安装依赖与最新版本之间的差距输出存在新版本的包列表pnpm why package用于回答“为什么这个包被安装了”——它会沿依赖图回溯展示究竟是哪个顶层依赖把它间接引入这对排查重复依赖、幽灵依赖问题非常关键。pnpm prune清理未使用依赖# 清理 node_modules 并删除不必要的文件 pnpm prunepnpm prune会移除package.json中不再声明的包清理node_modules中多余的文件适合在切换分支、删改依赖后让本地环境与清单重新对齐。pnpm cache缓存管理# 清理 pnpm 缓存 pnpm cache clean # 查看缓存中所有的包 pnpm cache listpnpm 使用全局内容寻址存储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 packageversion移除包pnpm remove package # 删除多个依赖包 pnpm remove lodash express # 删除全局依赖包 pnpm remove -g create-react-app # 删除特定版本的依赖包 pnpm remove lodash4.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 cleanMonorepo 工作区从初始化到脚本编排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-rrecursive遍历工作区中所有包含该脚本的包依次执行--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 --workspacepnpm 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 packagepnpm link package把全局已安装的包链接到当前项目用于在本地开发时替换远端版本pnpm link --global package简写-g方向相反把当前目录的包链接到全局便于在其他项目中直接pnpm link引用仍在开发的本地包。运行脚本# 运行 package.json 中的脚本 pnpm run script # 运行根目录中的包的脚本 pnpm run -w scriptpnpm 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），仅供参考