Git钩子脚本如何禁止大文件提交

wen 实用脚本 2026-07-15 1

Git钩子脚本如何禁止大文件提交：从原理到实战的完整指南

目录导读

为什么需要禁止大文件提交
Git钩子脚本的核心原理
编写pre-commit钩子脚本的5种常见方案
高级实战：动态限制与自定义警告
常见问题与解答（FAQ）
最佳实践与注意事项

为什么需要禁止大文件提交

在多人协作的Git仓库中，大文件（如视频、设计稿、数据集）的意外提交会带来三个致命问题：

Git钩子脚本如何禁止大文件提交

仓库体积暴涨：一个100MB的二进制文件将永久存在于历史中，导致git clone速度从秒级变成分钟级。
操作效率下降：每次git push和git fetch都会传输这些冗余数据,浪费带宽和时间。
协作成本激增：团队成员被迫拉取包含无用大文件的完整历史，CI/CD流水线也会因此变慢。

根据Git托管服务商的经验数据，90%的仓库膨胀问题源于大文件的误提交，在提交前通过钩子脚本自动拦截，是成本最低、效果最明显的防护手段。

Git钩子脚本的核心原理

Git钩子是Git在特定事件（如提交、推送、合并）前后自动触发的脚本文件，存储在项目.git/hooks/目录下，其中pre-commit钩子会在每次git commit执行前运行,若返回非零退出码则阻止提交。

钩子工作流程图

用户执行 git commit
    ↓
Git调用 .git/hooks/pre-commit 脚本
    ↓
脚本检查暂存区文件（staged files）
    ↓
发现大文件 → 输出错误信息 → 返回非零退出码 → 提交被中止
    ↓
未发现大文件 → 返回0 → 提交继续执行

关键知识：暂存区(staging area)的检测

钩子脚本必须通过git diff --cached --name-only或git diff --staged获取暂存区文件列表，而不是工作目录的所有文件，这是为了防止误报未纳入版本控制的大文件（如node_modules）。

编写pre-commit钩子脚本的5种常见方案

方案1：基础文件大小检测（推荐初学者使用）

#!/bin/bash
# .git/hooks/pre-commit
max_size=10485760  # 10MB
while IFS= read -r file; do
    if [[ -n "$file" ]]; then
        file_size=$(git cat-file -s :"$file")
        if [[ $file_size -gt $max_size ]]; then
            echo "错误：文件 '$file' 大小 $(numfmt --to=iec $file_size) 超过限制 ($(numfmt --to=iec $max_size))"
            exit 1
        fi
    fi
done < <(git diff --cached --name-only --diff-filter=ACM)
exit 0

方案2：排除特定目录与扩展名

# 针对常见大文件类型做放行（如LFS管理的游戏资源）
excluded_extensions=("psd" "mp4" "zip")
excluded_dirs=("Assets/StreamingAssets" "vendor")
while IFS= read -r file; do
    extension="${file##*.}"
    for ext in "${excluded_extensions[@]}"; do
        if [[ "$extension" == "$ext" ]]; then continue 2; fi
    done
    for dir in "${excluded_dirs[@]}"; do
        if [[ "$file" == $dir/* ]]; then continue 2; fi
    done
    # 接方案1的检测逻辑
done < <(git diff --cached --name-only --diff-filter=ACM)

方案3：二进制文件强制拦截

# 利用 git diff 检测文件是否为二进制
if git show :"$file" | head -c 80 | grep -q "BINARY"; then
    echo "警告：二进制文件 '$file' 可能过大，请改用Git LFS"
    exit 1
fi

方案4：使用Git LFS的文件自动检查

# 检测大文件是否已启用LFS跟踪
tracked_patterns=$(git lfs track 2>/dev/null | grep -oP '^tracking "\K[^"]+')
if ! echo "$file" | grep -q -F "$(echo \"$tracked_patterns\" | sed 's/*/\\.*/g')"; then
    # 未匹配LFS模式的文件超过阈值则拒绝
fi

方案5：跨平台兼容版本（支持macOS/Linux/Windows）

# 兼容不同操作系统的 numfmt 或 du 命令
if command -v numfmt &> /dev/null; then
    size_human=$(numfmt --to=iec $file_size)
elif command -v stat &> /dev/null; then
    size_human=$(stat --printf="%s" /dev/null 2>/dev/null; echo "$file_size")
fi

高级实战：动态限制与自定义警告

场景：允许小文件稍大，但严格控制超大文件

# 差异化阈值：文本文件≤5MB，媒体文件≤50MB，其他≤10MB
case "$file" in
    *.md|*.txt|*.json) threshold=$((5*1048576)) ;;
    *.png|*.jpg|*.mp4) threshold=$((50*1048576)) ;;
    *) threshold=$((10*1048576)) ;;
esac

场景：集成CI验证，支持临时豁免

在commit message中添加标签如[BYPASS_SIZE_CHECK]可临时放行（需团队约定风险）：

commit_message=$(git log --format=%B -n1 HEAD 2>/dev/null || echo "")
if [[ "$commit_message" == *"[BYPASS_SIZE_CHECK]"* ]]; then
    exit 0
fi

场景：生成人类可读的错误报告

echo "┌─────────────────────────────────┐"
echo "│   Git大文件提交拦截报告        │"
echo "├─────────────────────────────────┤"
echo "│ 文件: $file                     │"
echo "│ 大小: $size_human               │"
echo "│ 限制: $max_size_human           │"
echo "│ 建议: 使用 git lfs track        │"
echo "└─────────────────────────────────┘"