global-pack-sync

v0.0.4

Published

8 months ago

CLI utility for syncing global npm/yarn/pnpm packages across Node.js versions.

Downloads

0High
0Medium
0Low

yangsonhung

global-pack-sync

🚀 Node.js 全局 npm 包迁移工具 - 轻松在不同 Node.js 版本间迁移全局安装的包

问题背景

在 Node.js 开发中，我们经常遇到这样的痛点：

🔄 Node.js 版本更新频繁，需要切换版本测试项目兼容性
📦 全局安装的 npm 包在切换 Node.js 版本后需要重新安装
⏰ 手动记住和重新安装几十个全局包既费时又容易遗漏
🔧 不同包管理器（npm/yarn/pnpm）的包无法便捷迁移

global-pack-sync 就是为了解决这个问题而生！

特性

✨ 智能版本管理

🆕 默认安装最新版本，避免安全漏洞
🔒 支持锁定到保存时的确切版本
📊 版本变更可视化展示

⚡ 高性能安装

🚀 并行安装，大幅提升迁移速度
🎯 智能跳过已安装的包
🔄 失败包自动生成重试脚本

🛠 多包管理器支持

📦 npm、yarn、pnpm 全支持
🔍 自动检测当前使用的包管理器
🔧 灵活指定包管理器

🎨 用户体验优化

🌈 彩色终端输出，清晰易读
📋 详细的进度和状态反馈
🔍 交互式选择性恢复
📊 配置差异对比功能

🛡 安全稳定

🔒 进程锁防止并发冲突
🚫 自动过滤系统包和工具本身
💾 配置文件自动备份

安装

# 全局安装
npm install -g global-pack-sync

# 或使用 yarn
yarn global add global-pack-sync

# 或使用 pnpm
pnpm add -g global-pack-sync

提示：所有命令也支持使用简写 gps。

快速开始

基本工作流程

# 1. 在当前 Node.js 版本保存全局包配置
global-pack-sync save

# 2. 切换到新的 Node.js 版本
nvm use 18.0.0  # 或 n 18.0.0

# 3. 恢复全局包到新环境（默认安装最新版本）
global-pack-sync restore

就是这么简单！🎉

命令详解

📥 保存配置

# 保存当前环境的全局包列表
global-pack-sync save

# 保存到指定配置名称
global-pack-sync save my-project-packages

# 保存时会显示详细信息
✓ 已保存配置文件 "node-v18.17.0-1693123456789"
  Node 版本: v18.17.0
  npm 版本: 9.6.7
  包管理器: npm
  包数量: 15
  保存位置: ~/.global-pack-sync/packages.json

📤 恢复配置

# 恢复最新保存的配置（使用最新版本）
global-pack-sync restore

# 恢复指定配置
global-pack-sync restore my-project-packages

# 使用保存时的确切版本
global-pack-sync restore --exact-version

# 指定包管理器和并发数
global-pack-sync restore --pm yarn --concurrency 5

🎯 选择性恢复

如果只想恢复部分工具，可以使用交互式选择：

global-pack-sync select

# 提示示例
使用 ↑/↓ 移动，space 切换选中状态，a 全选/全不选，Enter 确认，q 取消

> [x] @vue/[email protected]
  [ ] [email protected]
  [x] [email protected]
  [x] [email protected]
  [ ] [email protected]

↑/↓ 移动光标
space 切换当前条目的选中状态
a 在全选与全不选之间切换
Enter 安装当前选中的包（默认全选）
q 取消操作，不执行安装

也可以直接查看保存的配置文件，了解具体内容：

{
  "my-project-packages": {
    "nodeVersion": "v18.17.0",
    "npmVersion": "9.6.7",
    "packageManager": "npm",
    "packages": {
      "@vue/cli": "5.0.8",
      "typescript": "5.2.2"
    },
    "savedAt": "2025-08-27T10:30:56.789Z",
    "packagesCount": 15,
    "platform": "darwin",
    "arch": "x64"
  }
}

常见问题

Q: 为什么默认安装最新版本而不是保存时的版本？

A: 为了安全考虑。最新版本通常包含安全修复和 bug 修复。如果需要确切版本，可使用 --exact-version 参数。

Q: 哪些包会被自动过滤？

A: 工具会自动过滤以下包，避免冲突：

npm、npx - npm 核心工具
corepack - Node.js 内置包管理器
node-gyp - 通常会自动安装
global-pack-sync - 工具本身

Q: 安装失败的包怎么处理？

A: 工具会自动生成重试脚本 ~/.global-pack-sync/retry-failed.sh，您可以手动执行或修改后执行。

Q: 支持私有 npm 源吗？

A: 是的，工具使用当前环境的 npm 配置，包括私有源配置。

Q: 可以在不同操作系统间迁移吗？

A: 大部分包可以，但一些依赖原生模块的包可能需要重新编译。工具会保存平台信息供参考。

故障排查

权限问题

# macOS/Linux
sudo global-pack-sync restore

# 或者修复 npm 权限
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.profile

网络问题

# 设置 npm 源
npm config set registry https://registry.npmmirror.com

# 或临时使用
global-pack-sync restore --pm npm

清理和重置

# 清理配置文件
rm -rf ~/.global-pack-sync

# 重新开始
global-pack-sync save

贡献指南

欢迎贡献代码！请查看 CONTRIBUTING.md 了解详情。

开发环境搭建

# 克隆仓库
git clone https://github.com/YangsonHung/global-pack-sync.git
cd global-pack-sync

# 安装依赖
yarn install

# 构建一次（输出到 dist/）
yarn build

# 本地运行 CLI
node dist/cli.js --help

# 运行测试
yarn test

更新日志

v0.0.4 (最新)

新增 GitHub Actions 工作流，在推送版本标签时自动完成构建、测试与发布。
每次发布都会附带打包好的 dist/ 产物，方便直接下载。
更新中英文 README，说明自动化发布流程，便于快速上手。

v0.0.3

CLI 新增 gps 简写别名，所有命令通用。
select 命令改为交互式选择界面，并为非交互终端提供回退。
中英文文档补充了别名和选择器操作提示。

v0.0.2

修复发布的 CLI bin 路径并优化 npm 徽章信息。
精简发布脚本并新增仓库格式化工作流。

v0.0.1

首个版本发布，提供保存/恢复指令与配置存储。
添加构建、测试工具链和项目文档。

查看完整更新日志：CHANGELOG.md

许可证

链接

如果这个工具帮助到了您，请给我们一个 ⭐ Star！

快乐编码！ 🎉

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

global-pack-sync

问题背景

特性

安装

快速开始

基本工作流程

命令详解

📥 保存配置

📤 恢复配置

🎯 选择性恢复

常见问题

Q: 为什么默认安装最新版本而不是保存时的版本？

Q: 哪些包会被自动过滤？

Q: 安装失败的包怎么处理？

Q: 支持私有 npm 源吗？

Q: 可以在不同操作系统间迁移吗？

故障排查

权限问题

网络问题

清理和重置

贡献指南

开发环境搭建

更新日志

v0.0.4 (最新)

v0.0.3

v0.0.2

v0.0.1

许可证

链接