npnpm - 跨 Node 版本的 pnpm 多版本管理器

一个与 nvm 完美共存的 pnpm 版本管理工具。安装一次，无论 nvm 切换到哪个 node 版本，pn / pnpm 命令都正常可用——就像 nvm 管理 node 版本一样管理 pnpm 版本。

⚠️ 平台支持：目前仅支持 macOS / Linux / Unix，暂不支持 Windows。 命令 shim 基于 bash 实现，Windows（cmd/PowerShell）无法执行；Windows 支持在后续版本规划中。

为什么需要 npnpm？

• 直接 npm i -g pnpm 安装的 pnpm 绑定在当前 node 版本的全局目录里：nvm 切换 node 版本后 pnpm 就"消失"了，每个 node 版本都得单独装一遍
• npnpm 的运行时自部署在 ~/.npnpm，与 npm 全局目录彻底解耦：nvm 任意切换、甚至卸载当初安装 npnpm 的 node 版本，pn / pnpm 照常工作
• pnpm 运行时自动使用 PATH 中当前活动的 node（nvm 切到哪跟到哪），并支持多版本 pnpm 共存与一键切换

特性

• nvm 无关 - 运行时自部署到 ~/.npnpm，node 用当前活动版本，nvm 切换零影响
• 找不到 node 也不怕 - PATH 里没有 node 时自动回退 ~/.nvm 下最新版本（cron / 非交互 shell 可用）
• 版本隔离 - 每个版本独立安装，互不干扰，current 指针切换
• 项目级版本固定 - pn pin 把某个项目绑定到指定版本，项目内零文件写入（比 .nvmrc 更干净）
• 让位机制 - pn off 一键让位给其他方式安装的 pnpm，pn on 恢复
• 交互式选择 - 直接运行 pn 通过菜单切换版本
• 智能权限处理 - 自动处理 sudo 环境下的用户目录，避免写入 /var/root

安装

npm install -g @xiaopangshushu/npnpm

安装时自动把运行时部署到 ~/.npnpm（此后 npm 全局包删掉都不影响使用）。

然后执行一次（幂等，可重复运行）：

pn init

它会自动把下面这行写入你的 shell 配置（默认 ~/.zshrc，可用 --rc <file> 指定其他文件）：

export PATH="$HOME/.npnpm/bin:$PATH"

重开终端或 source ~/.zshrc 后即可使用。

从 pnpm-v-control 旧版迁移？你 .zshrc 里被注释掉的旧 PATH 配置，pn init 会自动识别并启用。

使用方法

# 交互式选择并切换版本
pn

# 列出所有已安装的版本
pn ls

# 安装指定版本（简写 pn i）
pn install 10.17.1

# 安装最新版本并自动切换
pn latest

# 切换到指定版本
pn use 10.17.1

# 卸载指定版本
pn uninstall 8.15.9

# 将当前项目固定到指定版本（一次即可，项目内零文件写入）
pn pin 8.15.9
pn unpin              # 移除固定

# 查看安装/部署/PATH 状态
pn status

# 停用/恢复 npnpm 的 pnpm 命令（让位给其他 pnpm）
pn off
pn on

# 升级 npnpm 自身
pn self-update

# 配置 PATH（幂等）
pn init [--rc <file>]

# 显示帮助 / 版本
pn --help
pn -v

快速开始

pn install 10.17.1   # 安装
pn use 10.17.1       # 切换（或直接运行 pn 菜单选择）
pnpm -v              # → 10.17.1

与 nvm 的配合

pnpm 命令通过 PATH 中当前活动的 node 运行，nvm 切到哪个 node 版本，pnpm 就用哪个：

nvm use 22
pnpm -v    # pnpm 10.17.1（由 node 22 运行）

nvm use 18
pnpm -v    # pnpm 10.17.1（由 node 18 运行）

注意：pnpm 自身对 node 版本有最低要求（如 pnpm 10 需要 node ≥ 18.12）。如果切到较旧的 node，请同时切换到兼容的 pnpm 版本（如 pnpm 8 支持 node ≥ 16.13）：

nvm use 16
pn install 8.15.9
pn use 8.15.9
pnpm -v    # 8.15.9（由 node 16 运行）

项目级版本固定

不同项目需要不同 pnpm 版本？在项目根目录执行一次：

cd /path/to/projectA
pn pin 8.15.9      # 项目 A 固定使用 pnpm 8.15.9

之后的效果：

• 在项目 A 内（含任意子目录）运行 pnpm，自动使用 8.15.9
• 其他项目/目录继续使用全局版本（pn use 设置的那个）
• 支持多级固定：内外层都固定时，离当前目录最近的层级生效（类似 .nvmrc 的向上查找）
• 对项目零侵入：映射关系保存在 ~/.npnpm/projects/，项目目录里不会写入任何文件或配置

移除固定：

cd /path/to/projectA
pn unpin

想用其他方式安装的 pnpm？

~/.npnpm/bin 在 PATH 前面时，npnpm 管理的 pnpm 优先。想临时让位给别的 pnpm（比如某个 node 版本全局安装的、或 corepack 管理的）：

pn off     # 停用 npnpm 的 pnpm 命令，pnpm 解析到其他安装
pnpm -v    # → 你自己安装的那个 pnpm
pn on      # 恢复

工作原理

核心思路是两层设计，彻底解耦：

1. npm 全局包的通病：npm i -g 安装的命令绑定在当前 node 版本的全局目录里（如 ~/.nvm/versions/node/v18.16.0/bin/），nvm 切换 node 版本后命令就"消失"了——每个 node 版本都得单独装一遍
2. npm 包只是安装器：npm i -g @xiaopangshushu/npnpm 只负责首次安装和升级通道，真正可用的 pn / pnpm 命令自部署在 ~/.npnpm/bin/
3. PATH 一次配置，永久生效：pn init 把 ~/.npnpm/bin 写进 shell rc 后，命令与 node 版本彻底解耦——nvm 随便切、甚至卸载当初安装用的 node 版本，pn / pnpm 照常工作（shim 每次执行时动态解析当前活动的 node）

目录结构

~/.npnpm/
├── lib/
│   ├── pn.mjs            # npnpm 自身运行时（自部署的单文件 bundle，与 npm 全局解耦）
│   └── version           # 已部署运行时的版本号
├── bin/
│   ├── pn                # npnpm 命令 shim
│   └── pnpm              # pnpm 命令 shim，转发到 current 指向的版本
├── versions/
│   ├── 8.15.9/
│   │   ├── bin/pnpm      # 版本 wrapper
│   │   └── pkg/          # 从 npm registry 解包的 pnpm 包内容
│   └── 10.17.1/
└── current               # 指向当前版本（符号链接，不支持时退化为文本文件）

调用链路

pnpm (PATH)
 └─> ~/.npnpm/bin/pnpm          # bash shim：解析 current -> 版本号
      └─> versions/<v>/bin/pnpm # wrapper：执行解包出的 pnpm 入口
           └─> node pkg/package/bin/pnpm.cjs   # node 取自 PATH 活动版本

shim 内置两条保障：

1. sudo 场景：通过 SUDO_USER 解析真实用户主目录，数据始终落在真实用户的 ~/.npnpm
2. node 解析：优先 PATH 中活动的 node（nvm 切换自动跟随）；找不到时回退 ~/.nvm/versions/node/ 下最新版本

自部署与升级

• npm i -g @xiaopangshushu/npnpm 时 postinstall 自动部署运行时到 ~/.npnpm
• 每次运行 pn 会比对版本，npm 包升级后自动重新部署（不降级）
• pn self-update 一键升级
• 之后 npm uninstall -g @xiaopangshushu/npnpm 也不影响日常使用（仅失去升级通道）

常见问题

Q: 运行 pnpm 提示 "未设置当前 pnpm 版本"？

A: 还没选择版本，运行 pn ls 查看已安装版本，pn use <version> 切换；或 pn install <version> 先安装。

Q: 权限问题（之前用 sudo 装过）？

sudo chown -R "$USER":staff "$HOME/.npnpm"

Q: 如何完全卸载 npnpm？

npm uninstall -g @xiaopangshushu/npnpm   # 卸载 npm 包（如有）
rm -rf ~/.npnpm          # 删除数据目录
# 并从 ~/.zshrc 中删除 export PATH="$HOME/.npnpm/bin:$PATH" 一行

Q: 从 pnpm-v-control 旧版迁移？

数据目录 ~/.npnpm/versions 格式兼容，已安装的 pnpm 版本可直接使用。建议卸载旧全局包避免 pn 命令冲突：

npm uninstall -g pnpm-v-control
npm install -g @xiaopangshushu/npnpm
pn init

系统要求

• Node.js: >= 16.14（pnpm 各版本另有自身要求，见上文）
• 操作系统: macOS / Linux / Unix —— 不支持 Windows（shim 为 bash 脚本，Windows 支持规划中）
• 可选: nvm（配合使用体验最佳，但没有 nvm 也正常工作）

开发

npm install
npm run build      # tsc 编译 + esbuild 打包 dist/pn.mjs
npm link           # 全局可用并自动部署
pn status          # 验证

项目架构

src/
├── index.ts          # CLI 入口，命令解析、init/status/off/on/self-update
└── lib/
    ├── paths.ts      # ~/.npnpm 路径解析
    ├── shims.ts      # 三个 bash shim/wrapper 模板（HOME + node 解析策略）
    ├── deploy.ts     # 自部署：bundle 复制、shim 生成、版本比对
    ├── core.ts       # 版本管理：安装/切换/卸载
    └── version.ts    # 版本号（esbuild define 注入）
scripts/
├── build.mjs         # esbuild 打包单文件 bundle
└── postinstall.js    # npm 安装后自动部署

许可证

MIT

致谢

• 本项目基于 yook-w 的 pnpm-v-control （npm pack pnpm-v-control）重构而来（原代码仓库地址已失效），在此致谢原作者
• 灵感来自 nvm 与 n

如果这个项目对你有帮助，请给个 ⭐️ Star！