files-hash/README.md

文件哈希 GitHub Action

一个轻量级的 GitHub Action，用于计算指定文件或文件组的哈希值。非常适合需要文件完整性验证、变更检测或文件指纹识别的 CI/CD 工作流。

使用方法

基本示例

name: Calculate File Hashes
on: [push]

jobs:
  hash:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Calculate hash for source files
        uses: actions/files-hash@v0.1
        id: hash-step
        with:
          files: |
            src/**/*.js
            package.json
          algorithm: sha256

      - name: Use the hash
        run: |
          echo "Hash: ${{ steps.hash-step.outputs.hash }}"
          echo "Files processed: ${{ steps.hash-step.outputs.file-count }}"

高级示例

多种文件模式

- name: Hash multiple file types
  uses: actions/files-hash@v0.1
  with:
    files: |
      src/**/*.js
      src/**/*.ts
      *.json
      !node_modules/**
    algorithm: sha512

不同的哈希算法

- name: MD5 hash for quick comparison
  uses: actions/files-hash@v0.1
  with:
    files: dist/*
    algorithm: md5

条件处理

- name: Hash only if files exist
  uses: actions/files-hash@v0.1
  with:
    files: |
      build/**/*
      dist/**/*
    algorithm: sha256
  continue-on-error: true

输入参数

输入参数	描述	必需	默认值
files	文件路径或 glob 模式（每行一个）	✅ 是	-
algorithm	哈希算法：md5、sha1、sha256、sha512	❌ 否	sha256

文件模式

files 输入支持多种模式：

• 单个文件: package.json
• 多个文件:

  files: |
    file1.txt
    file2.txt
  

• Glob 模式: src/**/*.js（src 目录及子目录中的所有 JS 文件）
• 通配符: *.json（当前目录中的所有 JSON 文件）
• 目录: src/（递归处理 src 目录中的所有文件）

输出结果

输出	描述	类型
hash	所有处理文件的组合哈希值	string
file-count	成功处理的文件数量	number

工作原理

1. 文件发现: 解析输入模式并查找匹配的文件
2. 验证: 检查文件存在性和可读性
3. 哈希计算: 使用指定算法计算各个文件的哈希值
4. 组合: 从所有单个文件哈希值创建组合哈希值
5. 输出: 设置 GitHub Actions 输出供后续步骤使用

组合哈希值的计算方式：

1. 按字母顺序对所有文件路径进行排序（确保一致性）
2. 计算每个文件的哈希值
3. 从所有单个哈希值的连接创建新的哈希值

这确保了相同的文件集始终产生相同的组合哈希值，无论它们的处理顺序如何。

支持的算法

算法	输出长度	使用场景
md5	32 字符	快速比较、传统系统
sha1	40 字符	Git 兼容性、通用用途
sha256	64 字符	推荐 - 安全性和性能的良好平衡
sha512	128 字符	最高安全性、加密应用

错误处理

该 Action 优雅地处理各种错误场景：

• 文件缺失: 直接抛出错误
• 权限错误: 提供包含文件路径的清晰错误信息
• 无效算法: 列出支持的算法
• 空文件集: 失败并提供描述性消息

性能

• 并发处理: 同时处理多个文件
• 流式处理: 高效处理大文件，无需加载到内存中
• 内存管理: 针对大文件集和大文件进行优化
• 进度日志: 为长时间运行的操作提供清晰的进度指示器

实际项目示例

缓存键生成

- name: Generate cache key
  uses: actions/files-hash@v0.1
  id: cache-key
  with:
    files: |
      package-lock.json
      yarn.lock
      pnpm-lock.yaml
    algorithm: sha256

- name: Cache dependencies
  uses: actions/cache@v3
  with:
    path: node_modules
    key: deps-${{ steps.cache-key.outputs.hash }}

构建产物验证

- name: Build application
  run: npm run build

- name: Calculate build hash
  uses: actions/files-hash@v0.1
  id: build-hash
  with:
    files: dist/**/*
    algorithm: sha256

- name: Upload artifacts with hash
  uses: actions/upload-artifact@v3
  with:
    name: build-${{ steps.build-hash.outputs.hash }}
    path: dist/

配置变更检测

- name: Check config changes
  uses: actions/files-hash@v0.1
  id: config-hash
  with:
    algorithm: sha1
    files: |
      .github/workflows/**
      config/**
      *.config.js

- name: Notify on config changes
  if: steps.config-hash.outputs.hash != env.LAST_CONFIG_HASH
  run: echo "Configuration files have changed!"