SuperAPI AI 工具集

pnpm

编程与开发

查看项目

更新于 10-16 15:51

技能介绍

pnpm 是一个针对使用 pnpm 工作区(workspaces)的项目进行依赖管理和问题排查的包管理器技能,重点在于解决 node_modules 中重复依赖引发的问题。

用途 当 TypeScript 类型检查失败,或打包器出现报错、重复依赖等情况时,该技能可用于排查某个包在 pnpm 工作区 node_modules 中为何出现重复依赖。重复通常发生在同一个包被两处不同位置使用,且其 peer 依赖版本不一致时,例如 better-auth 依赖 zod 作为 peer 依赖,而 zod 在两个依赖子树中版本不同(如 3.x 与 4.x)。

主要能力

  • 识别重复包:在 pnpm-lock.yaml 中搜索带空格的字符串“ packagename@”,若返回多个带不同 peer 依赖集合(圆括号内内容不同)的实例,说明该包被重复。
  • 初步去重:先尝试运行 pnpm dedupe <packagename>。
  • 查找原因:运行 pnpm -r why zod@3.25.76(以 zod 为例)查看旧版本被安装的原因。
  • 修复去重:不使用 overrides,而是更新强制旧版本的依赖,运行 pnpm update -r --latest <packages>;若某个包已包含较新版本依赖,则 zod 会被自动去重。
  • 处理新发布包不安装的问题:pnpm 默认将新发布版本延迟 1 天(minimumReleaseAge: 1440)作为供应链安全措施,可通过全局脚本将其加入排除列表。

使用方式 该技能针对 pnpm 工作区项目给出以下操作规范:

  • 尽量在正在处理的包目录内运行命令,不要在工作区根目录运行 pnpm test 等命令。
  • 安装包始终使用 pnpm。
  • 始终通过 pnpm run <script> 显式调用包脚本;这对 deploy 尤其重要,因为 pnpm deploy 是 pnpm 内置部署命令,而 pnpm run deploy 执行项目自身的 deploy 脚本。
  • 不要在 package.json 中直接添加包,而应在正确的工作区目录内运行 pnpm install <package>;绝不手动修改 package.json 添加包。
  • 更新包时始终运行 pnpm update -r <packagename>,需要最新版时加 --latest;不要用 pnpm add 更新包(仅用于添加缺失的包),否则其他包的版本会不同步;绝不要使用 pnpm.overrides 或其他 package.json override 来更新、固定或对齐依赖版本。
  • 若某个包刚发布新版本却没有更新,可能是 minimumReleaseAge 配置拦截。用全局脚本加入排除列表:bun ~/.config/pnpm/update-minimum-release-age-exclude.ts package-name @some-scope/pkg。该脚本会拉取 npm 用户 xmorse 维护的所有包,把带作用域的包折叠为 @scope/* glob,并合并参数传入的额外包,写入 ~/.config/pnpm/config.yaml(pnpm 11)和 ~/.npmrc(pnpm 10)。~/.config/pnpm/ 是一个 git 仓库。

适用场景 适用于采用 pnpm 工作区管理依赖的项目,尤其是出现 TypeScript 类型检查失败、打包器报错、重复依赖,或需要规范化安装、更新、运行脚本与处理新发布包安装延迟等场景。

限制 资料未提供该技能的具体安装方式、收费模式、平台支持范围、版本兼容性细节或效果保证。若完成上述去重步骤后仍存在重复包,需向用户求助;可以尝试删除 node_modules 并重新开始流程,但该做法很少有帮助。