实战指南：vite-plugin-pack-orchestrator一站式搞定压缩校验与哈希

📦 Vite 构建打包利器：vite-plugin-pack-orchestrator

🤔 为何要重新开发一个打包工具？

虽然社区中已存在诸如 vite-plugin-zip-pack、vite-plugin-compress 等 Vite 打包插件，它们虽能使用，但往往难以完美契合实际需求——通常仅支持 ZIP 格式，且功能相对局限。

在真实的项目交付与部署流程中，打包环节的需求往往更为复杂：

1. 多格式适配 🗜️ — 团队协作可能需要 ZIP，Linux 服务器部署偏好 TAR.GZ，而长期归档则可能选用压缩率更高的 7Z，单一格式无法满足所有场景。
2. 完整性校验 🔐 — 交付给客户或上线前，通常需要 MD5/SHA1 等校验码来确保文件未被篡改或损坏，保证版本一致性。
3. 动态命名规则 ✏️ — 文件名中嵌入版本号、构建时间戳或内容哈希值，能让产物信息更加直观丰富。
4. CI/CD 流水线集成 🚀 — 自动化构建要求每次产物具备唯一标识，通过哈希自动重命名可避免人工干预，也比编写额外的 Shell 脚本更优雅便捷。

鉴于现有工具难以一站式解决上述痛点，vite-plugin-pack-orchestrator 应运而生。

⚡ 核心优势对比

📥 安装方式

npm install vite-plugin-pack-orchestrator

🚀 基础用法

仅需简单配置即可开始使用：

// vite.config.ts
import { defineConfig } from ‘vite’;
import orchestrator from ‘vite-plugin-pack-orchestrator’;

export default defineConfig({
plugins: [
orchestrator({
pack: {
outDir: ‘dist’, // 待打包目录，默认为 ‘dist’
format: ‘zip’, // 压缩类型：zip | tar | tar.gz | 7z
fileName: ‘myapp’, // 输出文件名
},
}),
],
build: { outDir: ‘dist’ },
});

运行 vite build 命令后，项目根目录下将生成 myapp.zip 文件。

⚙️ 详细配置说明

pack — 核心打包参数

pack: {
outDir: ‘dist’, // 源文件目录（相对项目根路径），默认 ‘dist’
fileName: ‘myapp’, // 输出名称，支持占位符替换
format: ‘zip’, // 格式选择：’zip’ | ‘tar’ | ‘tar.gz’ | ‘7z’
compressionLevel: 9, // 压缩等级 0-9，默认为 9（最高压缩）
archiveOutDir: ‘./releases’, // 产物存放路径，默认在项目根目录
exclude: [‘**/*.map’], // 忽略文件规则（glob 语法）
include: [‘**/*.js’], // 包含文件规则（可选，默认包含全部）
}

fileName 动态占位符

文件名模板支持以下变量，构建时会自动解析替换：

// 示例：fileName 设为 ‘release-[version]-[timestamp]’
// 输出：release-1.2.0-1714012345678.zip

// 示例：fileName 设为 ‘[name]-v[version]’
// 输出：my-awesome-app-v1.2.0.zip

// 示例：fileName 设为 ‘[name]-[hash]’
// 输出：my-awesome-app-a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6.zip

// 示例：fileName 设为 ‘[name]-[hash:8]’
// 输出：my-awesome-app-a1b2c3d4.zip

若未指定扩展名，插件会依据 format 配置自动补全 .zip、.tar.gz 等后缀。

🔗 hooks — 生命周期钩子

onBeforeBuild — 构建前置处理

在 Vite 启动打包流程前触发，适用于执行清理等准备工作：

hooks: {
onBeforeBuild: async () => {
// 在此处执行构建前的预处理逻辑
},
}

onBundleGenerated — 产物生成阶段

在 Vite bundle 生成完毕、压缩开始前触发，可获取构建产物元数据：

hooks: {
onBundleGenerated: (bundle) => {
console.log(‘当前生成的文件列表:’, Object.keys(bundle));
},
}

onAfterBuild — 压缩后置处理（核心亮点）

这是该插件最具价值的特性。 压缩包生成后，插件会自动计算 MD5 / SHA1 / SHA256 三种校验和，并将其注入到 onAfterBuild 回调中。利用这些校验信息，你可以实现基于内容哈希的自动重命名。

只要返回一个新的文件路径，插件便会自动完成重命名操作：

hooks: {
onAfterBuild: (path, format, checksums) => {
// path — 压缩包当前的绝对路径
// format — 使用的压缩格式（’zip’ | ‘tar’ | ‘tar.gz’ | ‘7z’）
// checksums — 校验和数据对象：{ md5: string, sha1: string, sha256: string }
return path; // 若返回原路径，则不进行重命名
},
}

应用场景演示：

// 场景 1：在扩展名前插入 SHA1 短哈希（推荐做法）
// myapp.zip → myapp-3a7b2c1d.zip
onAfterBuild: (path, format, checksums) =>
path.replace(/(\.(?:zip|tar\.gz|tar|7z))$/, `-${checksums.sha1.slice(0, 8)}$1`);

// 场景 2：使用完整 MD5 作为文件名
// myapp.zip → a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6.zip
onAfterBuild: (path, format, checksums) =>
path.replace(/^.+(?=\.\w+$)/, checksums.md5);

// 场景 3：在原文件名后追加格式标识与哈希
// myapp.zip → myapp-zip-a1b2c3d4.zip
onAfterBuild: (path, format, checksums) =>
path.replace(/(\.\w+)$/, `-${format}-${checksums.sha256.slice(0, 8)}$1`);

// 场景 4：完全自定义命名，利用 format 参数动态匹配后缀
// myapp.zip → release-a1b2c3d4e5f6.zip
onAfterBuild: (path, format, checksums) =>
`release-${checksums.md5.slice(0, 12)}.${format}`;

// 场景 5：仅记录校验和而不重命名（例如写入校验文件）
onAfterBuild: async (path, format, checksums) => {
fs.writeFileSync(‘checksums.json’, JSON.stringify(checksums));
// 不返回值或返回原路径即表示不重命名
}

onError — 异常捕获

当打包过程出现错误时触发，便于对接监控告警系统：

hooks: {
onError: async (error) => {
console.error(‘打包异常：’, error.message);
// 此处可接入钉钉、企业微信等通知渠道
},
}

🔄 为什么 CI/CD 需要压缩后自动重命名？

在持续集成与部署体系中，构建产物的唯一性与可追溯性至关重要。如果每次构建都输出同名的 dist.zip，将无法区分不同版本的差异，回滚时也极易出错。

借助 onAfterBuild 钩子获取校验和后，可将哈希值嵌入文件名，实现自动化标识：

hooks: {
onAfterBuild: (path, format, checksums) =>
path.replace(/(\.zip)$/, `-${checksums.sha1.slice(0, 8)}$1`);
}

构建产物示例：

myapp-1.0.2-3a7b2c1d.zip
myapp-1.0.2-7f9e4b2a.zip

此时文件名即为版本指纹 🔑，无需维护额外的版本映射表，部署脚本可直接通过文件名定位特定版本。回滚操作也变得极其简单——只需部署上一个哈希对应的文件即可。结合 [version] [timestamp] 等占位符，追溯能力进一步增强。

🎯 生产环境配置参考

整合上述功能，以下是一份完整的生产级配置范例：

// vite.config.ts
import { defineConfig } from ‘vite’;
import orchestrator from ‘vite-plugin-pack-orchestrator’;

export default defineConfig({
plugins: [
orchestrator({
pack: {
outDir: ‘dist’, // 指定打包目录
fileName: ‘myapp-[version]’, // 文件名包含版本号
format: ‘zip’, // 使用 ZIP 格式
archiveOutDir: ‘./releases’, // 产物输出至 releases
exclude: [‘**/*.map’], // 过滤 sourcemap 文件
},
hooks: {
// 压缩完成后自动追加 SHA1 哈希
onAfterBuild: (path, format, checksums) =>
path.replace(/(\.(?:zip|tar\.gz|tar|7z))$/, `-${checksums.sha1.slice(0, 8)}$1`),
// 错误日志输出
onError: (error) => console.error(‘打包失败：’, error.message),
},
}),
],
build: { outDir: ‘dist’ },
});

通过 vite build 即可一步到位，彻底告别繁琐的外部打包脚本。

该插件轻量高效且代码开源，诚邀体验与反馈 🎉

• npm: vite-plugin-pack-orchestrator
• GitHub: wangkai000/vite-plugin-pack-orchestrator

来源: https://segmentfault.com/a/1190000047730817