pnpm-v-control - pnpm 版本管理器

一个简单易用的 pnpm 版本管理工具，灵感来自 Node.js 的 n 版本管理器。通过 pn 命令，轻松在本地管理和切换多个 pnpm 版本。

特性

• 零系统侵入 - 不修改系统配置或 shell rc 文件
• 交互式选择 - 通过直观的命令行界面选择版本
• 快速切换 - 在不同项目间快速切换 pnpm 版本
• 智能权限处理 - 自动处理 sudo 环境下的用户目录
• 版本隔离 - 每个版本独立安装，互不干扰

安装

全局安装

npm install -g pnpm-v-control

手动安装（开发版本）

git clone https://github.com/yook-w/pnpm-v-control.git
cd pnpm-v-control
npm install
npm run build
npm link

使用方法

基础命令

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

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

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

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

# 切换到指定版本
pn use 10.17.1

# 卸载指定版本
pn uninstall 10.17.1

# 显示帮助信息
pn --help

快速开始

1. 首次使用 - 安装一个版本

# 方式一：安装最新版本（推荐）
pn latest

# 方式二：交互式安装
pn

# 方式三：安装指定版本
pn install 10.17.1

2. 切换版本

# 交互式选择
pn

# 或直接切换
pn use 10.17.1

3. 查看已安装的版本

pn ls

输出示例：

已安装的 pnpm 版本 (共 3 个):

  8.7.6
  10.16.1
  10.17.1 ✓ (当前使用)

4. 管理版本

# 安装最新版本
pn latest

# 安装指定版本
pn install 9.0.0

# 卸载不需要的版本
pn uninstall 8.7.6

工作原理

目录结构

npnpm 将所有 pnpm 版本管理在 ~/.npnpm/ 目录中：

~/.npnpm/
├── versions/           # 存储所有已安装的版本
│   ├── 8.7.6/
│   ├── 10.16.1/
│   └── 10.17.1/
├── current             # 指向当前活动版本（符号链接或文本文件）
└── bin/
    └── pnpm            # pnpm shim，转发到当前版本

版本切换机制

1. 每个版本独立存储在 versions/<version>/ 目录
2. current 文件（符号链接或文本）指向当前使用的版本
3. ~/.npnpm/bin/pnpm 作为 shim，根据 current 转发到对应版本

智能权限处理

npnpm 会自动检测 sudo 环境，避免在使用 sudo 时将文件写入 /var/root：

• 检测 SUDO_USER 环境变量
• 自动解析实际用户的 HOME 目录（macOS: /Users/<user>，Linux: /home/<user>）
• 始终将版本安装到实际用户的 ~/.npnpm 目录

高级功能

版本格式验证

npnpm 支持标准的 semver 版本格式：

pn install 10.17.1           # ✓ 标准版本
pn install 10.17.1-beta.0    # ✓ 预发布版本
pn install invalid           # ✗ 无效格式

智能错误提示

当操作失败时，npnpm 会提供友好的错误提示和解决建议：

# 尝试切换到未安装的版本
$ pn use 9.0.0
错误：版本 9.0.0 未安装
可用版本：8.7.6, 10.16.1, 10.17.1

请先运行：pn install 9.0.0

权限问题修复

如果遇到权限问题（通常是因为之前使用 sudo 安装），可以运行：

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

常见问题

Q: 为什么我运行 pnpm 命令时没有使用 npnpm 管理的版本？

A: 你需要确保 ~/.npnpm/bin 在你的 PATH 中，并且优先级高于系统 pnpm。

添加到 ~/.zshrc 或 ~/.bashrc：

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

然后重新加载配置：

source ~/.zshrc  # 或 source ~/.bashrc

Q: 如何查看当前使用的 pnpm 版本？

A: 运行 pn ls 可以查看所有版本，当前使用的版本会标记 ✓

或者直接运行：

pnpm --version

Q: 可以安装任意版本的 pnpm 吗？

A: 是的，npnpm 会从 npm registry 下载指定版本。如果版本不存在，会提示错误。

你可以访问 pnpm releases 查看所有可用版本。

Q: 如何完全卸载 pnpm-v-control？

A: 运行以下命令：

# 卸载全局包
npm uninstall -g pnpm-v-control

# 删除数据目录（可选）
rm -rf ~/.npnpm

# 从 PATH 中移除（编辑 ~/.zshrc 或 ~/.bashrc）

Q: 为什么某些版本无法删除？

A: 可能是因为这些版本是用 sudo 安装的，属于 root 用户。解决方法：

# 修复所有权
sudo chown -R "$USER":staff "$HOME/.npnpm"

# 然后就可以正常删除了
pn uninstall <version>

系统要求

• Node.js: >= 16.14
• 操作系统: macOS / Linux / Unix
• 终端: 支持 ANSI 转义序列的现代终端

开发

构建

npm run build      # 编译 TypeScript
npm run clean      # 清理 dist 目录

本地测试

npm run build
npm link           # 使 pn 命令全局可用
pn                 # 测试功能

发布

npm version patch  # 或 minor / major
npm publish

技术栈

• TypeScript - 类型安全的开发体验
• execa - 优雅的进程执行
• prompts - 美观的交互式提示
• fs-extra - 增强的文件系统操作
• tar - tarball 解压

项目架构

src/
├── index.ts        # CLI 入口，命令解析和交互
└── lib/
    └── core.ts     # 核心逻辑：版本管理、安装、卸载

核心模块说明

• getPaths() - 解析用户目录和存储路径
• ensureStore() - 初始化存储目录和 pnpm shim
• listVersions() - 列出所有已安装的版本
• getCurrentVersion() - 获取当前激活的版本
• setCurrentVersion() - 切换到指定版本
• installVersion() - 从 npm registry 下载并安装版本
• uninstallVersion() - 卸载指定版本

贡献

欢迎提交 Issue 和 Pull Request！

贡献指南

1. Fork 本仓库
2. 创建你的特性分支 (git checkout -b feature/amazing-feature)
3. 提交你的更改 (git commit -m 'Add some amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 开启一个 Pull Request

许可证

MIT License

致谢

灵感来自 n - Node.js 版本管理器

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