@via-cli/pkg-manager

NPM 包管理器，用于在指定目录下载、更新和缓存 npm 包。

🎉 v2.0 重构更新

• ✨ 新增统一缓存管理：使用 cache-manager 模块提供的统一缓存目录
• 🚀 性能提升：多个项目共享同一包缓存，减少下载时间和磁盘空间
• 📦 元数据支持：支持读取包的元数据信息（metadata.json）
• 🔄 完全向后兼容：现有代码无需修改，平滑升级
• 🎯 三种运行模式：统一缓存模式、旧 storeDir 模式、自动选择

功能特性

• ✅ 包安装：在指定目录或缓存目录安装 npm 包
• ✅ 包更新：检查并更新包到最新版本
• ✅ 智能缓存：统一缓存目录，多项目共享
• ✅ 版本检测：判断包是否存在以及是否需要更新
• ✅ 路径获取：获取包的缓存路径和根文件路径
• ✅ 元数据读取：支持读取包的元数据文件
• ✅ 集成 npm-tools：使用 @via-cli/npm-tools 获取 npm 包信息
• ✅ 向后兼容：保留所有旧 API，支持旧的 storeDir 模式

安装

pnpm add @via-cli/pkg-manager

使用示例

🌟 推荐：统一缓存模式（新）

不设置 storeDir，使用统一缓存目录，多项目共享缓存：

import PackageManager from '@via-cli/pkg-manager';

// ✅ 统一缓存模式：不设置 storeDir
const pkgManager = new PackageManager({
  targetPath: '/path/to/myproject',
  packageName: 'lodash',
  packageVersion: '4.17.21'
  // ❌ 不设置 storeDir - 自动使用统一缓存
});

await pkgManager.install();

// 缓存位置: ~/.via-cli/npm-cache/lodash/4.17.21
// 优点: 多项目共享，节省空间和时间

场景 1: 基础使用

import PackageManager from '@via-cli/pkg-manager';

const pkgManager = new PackageManager({
  targetPath: '/path/to/myproject',
  packageName: 'lodash',
  packageVersion: '4.17.21'
});

// 检查包是否存在
const exists = await pkgManager.exists();
console.log('包已缓存:', exists);

// 安装包（如果不存在）
if (!exists) {
  await pkgManager.install();
}

// 获取包的入口文件路径
const rootFile = pkgManager.getRootFile();
console.log('包入口:', rootFile);
// 输出: C:/Users/username/.via-cli/npm-cache/lodash/4.17.21/node_modules/lodash/lodash.js

// 获取元数据（如果包提供）
const metadata = await pkgManager.getMetadata();
if (metadata) {
  console.log('包元数据:', metadata);
}

场景 2: 使用旧 storeDir 模式（兼容）

如果你需要自定义缓存目录，可以设置 storeDir（旧模式）：

import PackageManager from '@via-cli/pkg-manager';
import path from 'path';
import os from 'os';

// ⚠️ 旧 storeDir 模式：使用自定义缓存目录
const cacheDir = path.join(os.homedir(), '.my-cli');

const pkgManager = new PackageManager({
  targetPath: path.join(cacheDir, 'packages'),  // 项目目录
  storeDir: path.join(cacheDir, 'store'),       // ✅ 设置 storeDir 使用旧模式
  packageName: '@via-cli/template',
  packageVersion: 'latest'
});

await pkgManager.install();

// 结果:
// - 包缓存在: ~/.my-cli/store/_@[email protected]@@via-cli/template
// - 链接到: ~/.my-cli/packages/node_modules/@via-cli/template

场景 3: 完整的 CLI 工具示例

import PackageManager from '@via-cli/pkg-manager';

// 创建包管理器实例（使用统一缓存）
const pkgManager = new PackageManager({
  targetPath: '/path/to/install',
  packageName: 'lodash',
  packageVersion: 'latest',
  registry: 'https://registry.npmjs.org' // 可选
});

// 准备环境（会自动将 latest 转换为具体版本号）
await pkgManager.prepare();
console.log('实际版本:', pkgManager.packageVersion);

// 检查包是否存在
const exists = await pkgManager.exists();
console.log('包已缓存:', exists);

// 安装包（如果不存在）
if (!exists) {
  await pkgManager.install();
}

// 更新包到最新版本
await pkgManager.update();

// 获取包的入口文件路径
const rootFile = pkgManager.getRootFile();
console.log('包入口文件:', rootFile);

// 获取缓存路径
const cachePath = pkgManager.cacheFilePath;
console.log('缓存路径:', cachePath);

// 获取元数据（新功能）
const metadata = await pkgManager.getMetadata();
if (metadata) {
  console.log('包元数据:', metadata);
}

// 获取元数据文件路径（新功能）
const metadataPath = await pkgManager.getMetadataPath();
console.log('元数据文件:', metadataPath);

场景 4: 自定义注册表

import PackageManager from '@via-cli/pkg-manager';

// 使用自定义注册表
const pkgManager = new PackageManager({
  targetPath: process.cwd(),
  packageName: '@via-cli/core',
  packageVersion: '1.0.0',
  registry: 'https://registry.npmmirror.com'
});

// 准备并检查
await pkgManager.prepare();

// 获取特定版本的缓存路径
const specificPath = pkgManager.getSpecificCacheFilePath('2.0.0');

// 检查包是否需要更新
const exists = await pkgManager.exists();
if (exists) {
  await pkgManager.update(); // 如果有新版本会自动更新
}

💡 storeDir 使用说明

什么时候需要 storeDir？

| 场景 | 是否需要 storeDir | 说明 | |------|------------------|------| | 临时安装测试 | ❌ 不需要 | 直接安装到目标目录即可 | | CLI 工具 | ✅ 推荐 | 缓存包，提升安装速度 | | 多项目复用 | ✅ 推荐 | 多个项目共享同一个包 | | 一次性使用 | ❌ 不需要 | 用完即删，无需缓存 |

storeDir 的工作原理

不使用 storeDir（简单模式）

new PackageManager({
  targetPath: '/project',
  packageName: 'lodash',
  packageVersion: '4.17.21'
})

结果：

/project/
  └── node_modules/
      └── lodash/           ← 包直接安装在这里
          ├── package.json
          └── ...

使用 storeDir（缓存模式）

new PackageManager({
  targetPath: '/project',
  storeDir: '/cache/store',
  packageName: 'lodash',
  packageVersion: '4.17.21'
})

结果：

/cache/store/                          ← 缓存目录
  └── [email protected]@lodash/         ← 真实的包文件
      ├── package.json
      └── ...

/project/
  └── node_modules/
      └── lodash/                      ← 软链接到缓存
          -> /cache/store/[email protected]@lodash/

优点：

• ✅ 包只下载一次
• ✅ 多个项目可以共享
• ✅ 节省磁盘空间
• ✅ 第二次安装速度快

更多使用场景请查看 USAGE_SCENARIOS.md

API

Constructor

new PackageManager(options: PackageManagerOptions)

PackageManagerOptions

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | targetPath | string | ✅ | 包安装的目标路径 | | storeDir | string | ❌ | 可选的缓存存储目录 | | packageName | string | ✅ | npm包名称 | | packageVersion | string | ✅ | npm包版本（支持 'latest'） | | registry | string | ❌ | npm注册表地址，默认 'https://registry.npmjs.org' |

方法

prepare(): Promise<void>

准备包管理器环境：

• 创建缓存目录（如果不存在）
• 将 'latest' 版本号解析为实际版本号

exists(): Promise<boolean>

检查包是否已存在（在缓存目录或目标目录）

install(): Promise<void>

安装包到目标路径或缓存目录

update(): Promise<void>

更新包到最新版本：

• 获取最新版本号
• 检查是否已缓存
• 如果未缓存则安装最新版本

getRootFile(): string | null

获取包的根文件路径（package.json 中 main 字段指向的文件）

getSpecificCacheFilePath(version: string): string

获取指定版本的缓存路径

getCacheFilePath(): string (deprecated)

获取当前版本的缓存路径（已弃用，请使用 cacheFilePath 属性）

属性

cacheFilePath: string

当前包版本的缓存路径（getter）

targetPath: string

包安装的目标路径

storeDir?: string

缓存存储目录

packageName: string

npm包名称

packageVersion: string

npm包版本

registry: string

npm注册表地址

缓存路径规则

缓存路径格式：{storeDir}/_{包名前缀}@{版本}@{包名}

示例：

• 包名：@via-cli/core
• 版本：1.0.0
• 缓存路径：/cache/_@[email protected]@@via-cli/core

依赖说明

本包使用以下工具：

• @via-cli/npm-tools - 获取 npm 包信息和版本
• @via-cli/type-tools - 类型检查工具
• @via-cli/path-utils - 路径格式化工具
• npminstall - npm 包安装工具

License

ISC