feat: 初始化文件哈希 GitHub Action 项目
This commit is contained in:
201
README.md
Normal file
201
README.md
Normal file
@@ -0,0 +1,201 @@
|
||||
# 文件哈希 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!"
|
||||
```
|
||||
Reference in New Issue
Block a user