# npm-pack

**Repository Path**: shaker/npm-pack

## Basic Information

- **Project Name**: npm-pack
- **Description**: npm-pack是一个基于Rust的NPM包批量下载工具。支持并发下载、智能缓存和自动依赖解析，能够显著提升包管理效率。核心特性包括：利用 Tokio 异步运行时实现多包并行下载，内置 SQLite 数据库缓存避免重复查询，自动递归解析包依赖关系，以及文件完整性校验机制。支持命令行参数和交互式两种方式，适用于开发环境搭建、离线包管理等场景。项目采用 MIT 开源协议，代码结构清晰，易于扩展和维护。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-26
- **Last Updated**: 2026-02-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# NPM Package Downloader

一个高效的 NPM 包批量下载工具，支持并发下载、智能缓存和依赖解析。

## 🌟 特性

- **并发下载**：利用 Tokio 异步运行时实现多包并行下载
- **智能缓存**：内置 SQLite 数据库缓存，避免重复查询和下载
- **依赖解析**：自动解析并下载包的所有依赖项
- **图形界面**：友好的文件选择对话框
- **完整性校验**：下载完成后自动验证文件完整性
- **彩色输出**：清晰的状态信息和错误提示

## 🚀 快速开始

### 系统要求

- Rust 1.70+
- Node.js 和 npm
- Windows/macOS/Linux

### 安装

1. 克隆项目：
```bash
git clone <repository-url>
cd npm-pack
```

2. 构建项目：
```bash
cargo build --release
```

3. 配置 npm 路径：
复制 `config.example.json` 为 `config.json` 并配置你的 npm-cli.js 路径：
```json
{
  "npm_cli_path": "你的npm-cli.js路径"
}
```

### 使用方法

#### 方式一：命令行参数（推荐）
```bash
# 直接指定 package.json 文件路径
cargo run -- --package path/to/package.json

# 或使用短参数
cargo run -- -p path/to/package.json

# 指定npm镜像站
cargo run -- --package path/to/package.json --registry https://registry.npmmirror.com/

# 或使用短参数指定镜像站
cargo run -- -p path/to/package.json -r https://registry.npmmirror.com/

# 显示帮助信息
cargo run -- --help
```

#### 方式二：交互式文件选择
```bash
# 不指定参数，程序会显示文件选择对话框
cargo run
```

程序将自动：
   - 解析 dependencies 和 devDependencies
   - 并发下载所有依赖包
   - 自动解析并下载依赖项的子依赖
   - 验证下载文件的完整性

## 📁 项目结构

```
npm-pack/
├── src/
│   └── main.rs          # 主程序文件
├── Cargo.toml           # Rust 依赖配置
├── config.json          # 配置文件
├── cache.db            # SQLite 缓存数据库（运行时生成）
└── download/           # 下载的 .tgz 文件目录（运行时生成）
```

## 🔧 核心组件

### UnifiedCache 缓存系统
- 基于 SQLite 的持久化缓存
- 缓存包版本信息和依赖关系
- 24小时缓存有效期
- 支持版本和依赖两种数据类型

### 并发下载引擎
- 使用 Tokio 实现异步并发
- 每个任务拥有独立的缓存实例
- 全局去重避免重复下载

### 依赖解析器
- 递归解析包的所有依赖
- 自动处理循环依赖
- 支持语义化版本号解析

## ⚙️ 配置说明

### config.json
```json
{
  "npm_cli_path": "C:\\Users\\username\\AppData\\Roaming\\npm\\node_modules\\npm\\bin\\npm-cli.js",
  "registry": "https://registry.npmjs.org/"
}
```

- `npm_cli_path`：指向正确的 npm-cli.js 文件路径
- `registry`：npm镜像站地址（可选，默认为官方源）

## 📊 缓存机制

程序使用 SQLite 数据库存储缓存信息：

**缓存表结构：**
```sql
CREATE TABLE cache (
    package_key TEXT NOT NULL,
    data_type TEXT NOT NULL,
    data_value TEXT NOT NULL,
    created_at INTEGER DEFAULT (strftime('%s', 'now')),
    PRIMARY KEY (package_key, data_type)
);
```

**缓存策略：**
- 版本信息缓存：24小时有效期
- 依赖关系缓存：永久有效
- 自动清理过期缓存

## 🎨 输出示例

### 命令行帮助
```
$ cargo run -- --help
NPM Package Downloader 0.1.0

一个高效的 NPM 包批量下载工具，支持并发下载、智能缓存和依赖解析。

Usage: npm-pack.exe [OPTIONS]

Options:
  -p, --package <FILE>      package.json 文件路径（可选）
  -r, --registry <URL>      npm 镜像站地址（可选，默认使用官方源）
  -h, --help                显示帮助信息
  -V, --version             Print version
```

### 运行示例
```
# 使用命令行参数
$ cargo run -- --package ./package.json
使用命令行指定的文件: "./package.json"
使用配置文件中的npm镜像站: https://registry.npmjs.org/
开始并行下载 3 个包...
lodash: ^4.17.21
axios: ^1.6.0
typescript: ^5.0.0

# 指定镜像站
$ cargo run -- --package ./package.json --registry https://registry.npmmirror.com/
使用命令行指定的文件: "./package.json"
使用指定的npm镜像站: https://registry.npmmirror.com/
开始并行下载 3 个包...

# 交互式模式
$ cargo run
未指定 package.json 文件，显示文件选择对话框...
使用配置文件中的npm镜像站: https://registry.npmjs.org/
开始并行下载 3 个包...
```

### 缓存操作日志
```
缓存操作: 包 lodash@4.17.21 影响了 1 行数据
包 lodash@4.17.21 已经下载过，跳过下载
所有包下载完成
```

## 🛠️ 开发指南

### 添加新功能

1. **扩展缓存类型**：
```rust
pub enum CacheDataType {
    Version(String),
    Dependencies(Map<String, Value>),
    // 添加新的缓存类型
}
```

2. **自定义下载逻辑**：
修改 `download_npm_package` 函数实现特定的下载策略

### 调试技巧

- 使用 `println!` 宏输出调试信息
- 查看 `cache.db` 文件了解缓存状态
- 检查 `download/` 目录验证下载结果

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

### 开发环境设置
```bash
# 克隆项目
git clone <repository-url>
cd npm-pack

# 安装依赖
cargo build

# 运行测试
cargo test
```

## 📄 许可证

MIT License

## 🙏 致谢

- [Tokio](https://tokio.rs/) - 异步运行时
- [Serde](https://serde.rs/) - 序列化框架
- [Rusqlite](https://github.com/rusqlite/rusqlite) - SQLite 绑定
- [Native Dialog](https://crates.io/crates/native-dialog) - 原生对话框

---

**注意**：此工具仅供学习和开发使用，请遵守各包的许可证协议。