files-hash/README.md

# 文件哈希 GitHub Action

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

## 使用方法

### 基本示例

```yaml
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 }}"
```

### 高级示例

#### 多种文件模式

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

#### 不同的哈希算法

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

#### 条件处理

```yaml
- 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`
- **多个文件**:
  ```yaml
  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 优雅地处理各种错误场景：

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

## 性能

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

## 实际项目示例

### 缓存键生成

```yaml
- 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 }}
```

### 构建产物验证

```yaml
- 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/
```

### 配置变更检测

```yaml
- 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!"
```