avatar
Published on

Vite打包zip并改名为md5sum哈希案例

Vite打包zip并改名为md5sum哈希案例

在前端项目的 DevOps 持续集成/持续部署（CICD）流程中，对构建产物的管理是关键环节之一。其中，将 dist 目录打包为 ZIP 并以 MD5 哈希值命名，是保障文件完整性、优化部署效率的经典方案。本文将详细介绍这一实践的原理与实现，适用于各类 CICD 环境。

一、为什么要用 MD5 哈希值命名打包文件？

在解释具体实现前，我们先明确这一操作的核心价值：

  • 文件完整性验证：MD5 哈希值如同文件的「数字指纹」，只要文件内容有任何微小变化（哪怕一个字符），哈希值就会完全不同。通过比对部署前后的哈希值，可快速确认文件是否在传输或存储中被篡改。
  • 版本追溯与缓存优化：哈希值直接关联文件内容，不同版本的构建产物会生成不同的哈希文件名，避免 CDN 或浏览器缓存导致的「旧文件覆盖不及时」问题。
  • 自动化部署适配：在 CICD 流水线中，哈希文件名可作为版本标识，方便脚本判断是否需要重新部署（仅当哈希值变化时执行部署），减少无效操作。

二、什么是 md5sum？

md5sum 是 Unix/Linux 系统中常用的命令行工具，用于计算文件的 MD5 哈希值。其核心特性包括：

  • MD5 算法：一种加密哈希函数，可将任意长度的输入数据转换为固定的 128 位（32 个十六进制字符）哈希值。
  • 主要用途：
    • 验证文件传输/存储的完整性（哈希值一致则文件未被篡改）；
    • 软件分发时提供校验依据（用户可比对官方哈希值确认文件合法性）；
    • 辅助数据去重（相同内容的文件哈希值相同）。

注意：MD5 因存在碰撞攻击风险，不适合用于高安全性场景（如密码加密），但在文件完整性验证场景中仍被广泛使用（因其计算高效、结果固定）。

三、Vite 项目实现：打包为 ZIP 并以 MD5 命名

以下是基于 Vite 构建工具的具体实现方案，核心步骤为：打包 dist 目录为 ZIP → 计算 ZIP 文件的 MD5 哈希值 → 重命名 ZIP 为哈希值 + 扩展名。

1. 安装依赖

需要两个关键工具：

  • vite-plugin-zip-pack：Vite 插件，用于将 dist 目录打包为 ZIP；
  • crypto：Node.js 内置模块，用于计算 MD5 哈希值（无需额外安装）。

安装命令：

npm i vite-plugin-zip-pack -D

2. Vite 配置代码实现

在 vite.config.ts 中添加如下配置：

import fs from 'fs'
import path from 'path'
import crypto from 'crypto'
import zipPack from 'vite-plugin-zip-pack'
import { defineConfig } from 'vite'

export default defineConfig({
    plugins: [
        // 其他插件...
        zipPack({
            inDir: 'dist', // 需要打包的目录（构建产物目录）
            outDir: 'zip/', // ZIP 文件的输出目录
            outFileName: 'dist.zip', // 临时 ZIP 文件名（后续会被重命名）
            done: () => {
                // 打包完成后执行：计算 MD5 并重命名
                const originPath = 'zip/' // ZIP 所在目录
                const originFilePath = `${originPath}dist.zip` // 临时 ZIP 文件路径

                // 读取 ZIP 文件内容
                const fileContents = fs.readFileSync(originFilePath)

                // 计算 MD5 哈希值
                const hash = crypto.createHash('md5') // 创建 MD5 哈希对象
                hash.update(fileContents) // 传入文件内容
                const md5sum = hash.digest('hex') // 生成 32 位十六进制哈希值

                // 构建新文件名（MD5 哈希值 + 扩展名）
                const fileExtension = path.extname(originFilePath) // 获取扩展名（.zip）
                const newFileName = `${originPath}${md5sum}${fileExtension}` // 例如：zip/abc123def456.zip

                // 重命名文件
                fs.rename(originFilePath, newFileName, (err) => {
                    if (err) throw err
                    console.log(`✅ ZIP 文件已重命名为：${newFileName}`)

                    // （可选）删除目录中旧的 ZIP 文件，只保留最新版本
                    fs.readdir(originPath, (error, files) => {
                        if (error) throw error
                        ;(files || []).forEach((file) => {
                            // 跳过当前新文件，删除其他旧文件
                            if (file !== path.basename(newFileName)) {
                                fs.unlink(path.join(originPath, file), (unlinkErr) => {
                                    if (unlinkErr) throw unlinkErr
                                    console.log(`🗑️ 已删除旧文件：${file}`)
                                })
                            }
                        })
                    })
                })
            },
        }),
    ],
})

3. 实现说明

  • 打包流程：Vite 构建完成后，zipPack 插件会自动将 dist 目录压缩为 zip/dist.zip；
  • MD5 计算：通过 crypto.createHash("md5") 生成哈希对象，读取 ZIP 文件内容后计算哈希值；
  • 重命名逻辑：将临时文件 dist.zip 改为 [md5值].zip，例如 a1b2c3d4e5f6...5678.zip；
  • 清理旧文件：可选步骤，删除 zip 目录中除最新文件外的其他 ZIP，避免冗余存储。

四、在各类 CICD 流水线中集成

上述配置生成的 MD5 命名 ZIP 文件，可无缝集成到任何 CICD 环境中（包括企业内部自建流水线、Jenkins、GitLab CI、GitHub Actions 等），核心流程一致：

  1. 代码提交触发流水线，执行 npm run build 构建项目，自动生成 MD5 命名的 ZIP 包；
  2. 流水线脚本读取 zip 目录下的哈希命名 ZIP 文件（可通过 *.zip 匹配）；
  3. 将 ZIP 包上传至目标服务器、CDN 或存储服务；
  4. （可选）将当前 MD5 哈希值记录到版本管理系统（如数据库、配置文件），用于后续校验或回滚。

例如，在企业内部流水线的部署脚本中，可添加类似逻辑：

# 查找最新生成的 MD5 命名 ZIP 文件
ZIP_FILE=$(find ./zip -name "*.zip" | head -n 1)

# 上传文件到服务器
scp $ZIP_FILE user@server:/path/to/deploy

# 记录哈希值到版本日志
echo "Deployed: $(basename $ZIP_FILE .zip) at $(date)" >> deployment.log

通过将前端构建产物打包为 MD5 哈希命名的 ZIP，可在 CICD 流程中实现：

  • 严格的文件完整性验证，避免部署篡改文件；
  • 高效的版本管理，通过哈希值快速识别内容变化；
  • 通用的适配性，兼容各类 CICD 环境（无论是企业内部系统还是主流开源工具）。

该方案适用于各类前端项目（不仅限于 Vite），只需替换对应的打包工具（如 Webpack 的 zip-webpack-plugin）即可实现类似功能。在实际应用中，可根据项目需求调整是否保留旧文件、是否需要额外记录哈希值等细节。