TravelX Packager

TravelX 自定义应用程序发布工具的 Packager 组件，支持增量/全量打包和分片上传。

快速开始

查看 examples 目录 中的示例项目：

• test-console - C# 控制台应用示例
• test-iis-web - .NET Web 应用示例
• test-nextjs - Next.js 应用示例

详细说明请查看：examples/README.md

功能特性

• ✅ 智能缓存机制（检测已有包文件，避免重复打包）
• ✅ 断点续传（基于哈希验证，上传失败可继续）
• ✅ 上传状态检查（避免重复上传相同版本）
• ✅ 临时文件管理（验证通过后再移动到最终位置）
• ✅ 支持增量打包（基于文件哈希对比）和全量打包
• ✅ 支持打包前/后脚本钩子
• ✅ 自动识别操作系统，执行对应的 shell 脚本
• ✅ 分片上传，支持上传进度显示
• ✅ 彩色输出，清晰的日志信息
• ✅ 自动生成 zip 压缩包，包含元数据文件

安装

# 全局安装
npm install -g @travelx/packager

# 或使用 npx
npx @travelx/packager

配置文件

在项目目录创建 travelx.json 配置文件：

{
  "packageId": "web-app",
  "version": "1.2.3",
  "releaseNotes": "修复了若干问题，优化了性能",
  "fullPackage": true,
  "sourcePath": "./dist",
  "prePackScripts": [
    "./scripts/clean.sh",
    "./scripts/build.sh"
  ],
  "postPackScripts": [
    "./scripts/verify.sh"
  ],
  "server": {
    "url": "https://deploy.example.com",
    "token": "your-access-token"
  }
}

配置项说明

| 字段 | 类型 | 必需 | 说明 | |------|------|------|------| | packageId | string | 是 | 包 ID，对应 Client 配置中的 applications[].id | | version | string | 是 | 版本号（如 1.2.3） | | releaseNotes | string | 是 | 版本更新说明 | | fullPackage | boolean | 是 | 打包模式：true=全量，false=增量 | | sourcePath | string | 是 | 源文件目录路径 | | prePackScripts | string[] | 否 | 打包前执行的脚本列表 | | postPackScripts | string[] | 否 | 打包后执行的脚本列表 | | server | object | 否 | 服务端配置（不配置则跳过上传） | | server.url | string | 是（如果配置 server）| 服务端 URL | | server.token | string | 是（如果配置 server）| Access token |

使用方法

# 在项目目录执行（自动查找 travelx.json）
pkg

# 或使用完整命令
npx @travelx/packager

打包流程

全量模式流程

1. 读取并验证配置文件
2. 执行 prePackScripts
3. 扫描源文件目录
4. 收集所有文件
5. 创建 zip 压缩包（包含元数据）
6. 执行 postPackScripts
7. 如果配置了 server，分片上传到服务端

增量模式流程

1. 读取并验证配置文件
2. 执行 prePackScripts
3. 调用服务端 API 获取上一个版本信息
4. 显示上一个版本信息，等待用户确认
5. 计算文件差异（基于 SHA-256 哈希对比）
6. 收集差异文件
7. 创建 zip 压缩包（包含元数据）
8. 执行 postPackScripts
9. 如果配置了 server，分片上传到服务端

脚本钩子

打包前脚本（prePackScripts）

• 在扫描文件前执行
• 用于清理、编译等操作
• 脚本执行失败直接退出整个流程

打包后脚本（postPackScripts）

• 在创建压缩包后执行
• 用于验证包完整性等操作
• 脚本执行失败直接退出整个流程

脚本执行环境

• Windows: 使用 cmd.exe /c 执行
• Linux/Mac: 使用 /bin/bash 执行

输出示例

════════════════════════════════════════════════════
  TravelX Packager
════════════════════════════════════════════════════

[步骤 1/7] 读取配置文件
ℹ 读取配置文件: /path/to/travelx.json
✓ 配置验证通过

[步骤 2/7] 执行打包前脚本
ℹ 准备执行 2 个脚本
ℹ [1/2] 执行脚本: ./scripts/clean.sh
✓ 脚本执行成功: ./scripts/clean.sh
ℹ [2/2] 执行脚本: ./scripts/build.sh
✓ 脚本执行成功: ./scripts/build.sh
✓ 所有脚本执行完成

[步骤 3/7] 全量模式
ℹ 跳过增量对比

[步骤 4/7] 扫描源文件
✓ 扫描完成，共 123 个文件

[步骤 5/7] 打包模式: 全量
✓ 压缩包创建成功: /path/to/package-1.2.3.zip
ℹ 包大小: 15.23 MB

[步骤 6/7] 执行打包后脚本
ℹ 没有配置打包后脚本

[步骤 7/7] 上传发布包
ℹ 开始上传: /path/to/package-1.2.3.zip
ℹ 文件大小: 15.23 MB
ℹ 分片大小: 5.00 MB
ℹ 总分片数: 4
ℹ 上传分片 [1/4]
✓ 分片 [1/4] 上传成功
ℹ 上传分片 [2/4]
✓ 分片 [2/4] 上传成功
ℹ 上传分片 [3/4]
✓ 分片 [3/4] 上传成功
ℹ 上传分片 [4/4]
✓ 分片 [4/4] 上传成功
✓ 上传完成

════════════════════════════════════════════════════
✓ 打包完成！
════════════════════════════════════════════════════
ℹ 包文件: /path/to/package-1.2.3.zip
ℹ 版本号: 1.2.3
ℹ 包 ID: web-app
ℹ 模式: full
════════════════════════════════════════════════════

包内元数据

生成的 zip 包内包含 .travelx-manifest.json 元数据文件：

{
  "packageId": "web-app",
  "version": "1.2.3",
  "mode": "full",
  "releaseNotes": "修复了若干问题，优化了性能",
  "createdAt": "2024-01-21T10:00:00.000Z",
  "files": [
    {
      "path": "app.js",
      "hash": "abc123...",
      "size": 12345
    },
    {
      "path": "styles.css",
      "hash": "def456...",
      "size": 6789
    }
  ]
}

开发

# 安装依赖
npm install

# 构建
npm run build

# 监听模式构建
npm run dev

# 链接到全局（用于测试）
npm link

License

MIT