ptar

一个用于批量下载 pnpm/yarn 项目依赖包 tarball 的命令行工具，支持离线缓存和并发下载。

特性

• 🚀 快速并发下载 - 支持自定义并发数，默认 10 个任务同时下载
• 📦 智能依赖扫描 - 自动分析 pnpm/yarn 项目完整依赖树
• 💾 离线缓存 - 已下载的包会自动跳过，避免重复下载
• 🎯 灵活配置 - 支持自定义输出目录、registry 源、是否包含开发依赖等
• 🔍 Dry Run 模式 - 支持预演模式，仅列出依赖不实际下载
• ✨ 详细日志 - 支持 verbose 模式，实时查看下载进度和详情
• 🔄 自动重试 - 下载失败自动重试，最多尝试 3 次
• 🌐 多包管理器支持 - 支持 pnpm 和 yarn 两种包管理器

安装

npm install -g ptar

或使用 pnpm：

pnpm add -g ptar

使用方法

基本用法

ptar [目标文件夹路径]

不指定参数时，默认在当前目录执行：

ptar

指定目标项目路径：

ptar /path/to/your/project

命令行选项

| 选项 | 简写 | 说明 | 默认值 | | ------------------------- | ---- | -------------------- | --------------------------------- | | --version | -v | 显示版本号 | - | | --out <dir> | -o | 输出目录 | tarballs | | --concurrency <n> | -c | 并发下载数 | 10 | | --dev | - | 包含 devDependencies | true | | --dry-run | - | 仅列出依赖，不下载 | - | | --registry <url> | - | 自定义 registry 基址 | https://registry.npmmirror.com/ | | --verbose | -V | 显示详细日志 | - | | --package-manager <type>| -p | 包管理器类型 | 自动检测 (pnpm|yarn) |

使用示例

1. 默认下载（当前目录）

ptar

将所有依赖下载到当前目录下的 tarballs 文件夹。

2. 指定项目路径和输出目录

ptar /path/to/project -o ./my-tarballs

3. 限制并发数为 5

ptar -c 5

4. 仅预览不下载（Dry Run）

ptar --dry-run

查看将要下载的依赖列表，但不实际执行下载。

5. 查看版本号

ptar -v
# 或
ptar --version

显示当前工具的版本信息。

6. 使用详细日志模式

ptar -V

显示每个包的下载进度和详细信息。

7. 自定义 registry 源

ptar --registry https://registry.npmjs.org/

8. 排除开发依赖

ptar --dev false

9. 指定包管理器类型

# 强制使用 yarn
ptar --package-manager yarn

# 强制使用 pnpm
ptar --package-manager pnpm

如果不指定，工具会自动检测项目中的 lock 文件来确定包管理器类型。

输出结构

执行后会在目标目录生成如下结构：

project/
├── tarballs/           # 默认的 tarball 输出目录
│   ├── [email protected]
│   ├── [email protected]
│   └── ...
└── ...

文件名格式：包名 @版本.tgz（特殊字符会被替换以确保兼容性）

工作流程

1. 检测包管理器 - 自动检测项目使用的是 pnpm 还是 yarn，或通过 --package-manager 参数指定
2. 扫描依赖 -
   • pnpm: 通过 pnpm list --json --depth=Infinity 获取完整依赖树
   • yarn: 使用 @yarnpkg/lockfile 解析 yarn.lock 文件获取所有依赖信息
3. 解析 tarball URL - 从依赖信息中提取每个包的下载地址
4. 并发下载 - 使用可配置的并发数批量下载所有依赖
5. 智能跳过 - 已存在的文件会自动跳过
6. 错误处理 - 失败的下载会自动重试，最终生成失败列表

注意事项

• 需要 Node.js >= 18
• 目标项目必须是 pnpm 或 yarn 项目（包含 pnpm-lock.yaml 或 yarn.lock）
• 确保已安装相应的包管理器：
  • pnpm: npm install -g pnpm
  • yarn: npm install -g yarn 或使用 npx yarn
• 下载的文件可用于离线安装或备份

开发

# 克隆项目
git clone [email protected]:JiQingYun/ptar.git

# 安装依赖
pnpm install

# 构建
pnpm build

# 本地测试
node dist/index.js --help

License

ISC