Git钩子脚本如何检查许可证合规

Git钩子脚本（Git Hooks）作为一种轻量级自动化工具，能够直接在代码提交（commit）、推送（push）等阶段触发检查，从源头拦截不合规代码，本文将通过真实案例和代码段，详细展示如何构建一个检查许可证合规的Git钩子脚本,并解答开发者常见疑问。

核心价值：在代码进入版本控制之前，自动识别高风险的许可证违规场景,而非事后补救。

Git钩子脚本基础概念

什么是Git钩子？

Git钩子是Git版本控制系统附带的自定义脚本，在特定操作（如pre-commit、pre-push）时自动执行，它们分为客户端钩子和服务端钩子，本文主要介绍客户端pre-commit和pre-push钩子的使用。

钩子脚本生命周期与触发点

• pre-commit：在提交之前运行，可用于检查代码风格、密钥泄露或许可证合规。
• prepare-commit-msg：编辑提交信息前触发,适合自动填充合规声明。
• pre-push：在推送远程仓库前执行,适合验证所有提交是否合规。
• post-commit：提交后用于记录日志或通知,不用于拦截。

注意：Git钩子存储在.git/hooks/目录下，默认不可执行,用户需手动将其脚本设置为可执行权限。

许可证合规检查的核心机制

许可证检测原理

常见开源许可证以LICENSE或LICENSE.md文件形式存在于根目录，或通过文件头部注释声明,脚本的核心逻辑是扫描以下内容：

1. 项目自身许可证文件：确认主许可证类型及其条款。
2. 引入的依赖包许可证：通过package.json（Node.js）、requirements.txt（Python）、Cargo.toml（Rust）等文件获取依赖列表。
3. 代码文件头部注释：检测每个文件的版权声明（如// Copyright 2024, MIT License）。
4. 许可证兼容性矩阵：对比两个许可证是否冲突（例如GPL与专有许可证不兼容）。

常用工具与库

• license-checker（Node.js）: 遍历依赖树,输出许可证列表。
• licensee（Ruby）: 分析 .gitignore 和 LICENSE 文件出具合规报告。
• scanCode（Python）: 深度扫描版权与许可证信息,适合大型项目。

实战构建许可证检测钩子脚本

步骤1：环境准备

确保项目已安装：

# Node.js环境
npm install -g license-checker
# 或Python环境
pip install scancode-toolkit

步骤2：编写pre-commit钩子脚本

创建文件 .git/hooks/pre-commit如下：

#!/bin/bash
# pre-commit: 检查所有新增或修改文件的许可证合规
set -e
echo "📋 开始许可证合规检查..."
# 获取本次提交的变更文件（仅.staged文件）
CHANGED_FILES=$(git diff --cached --name-only --diff-filter=ACM)
# 检测项目根目录是否存在LICENSE文件
LICENSE_FILE="LICENSE"
if [ ! -f "$LICENSE_FILE" ]; then
    echo "❌ 错误：根目录缺少LICENSE文件，请先创建许可证声明！"
    exit 1
fi
# 分析依赖的许可证
if [ -f "package.json" ]; then
    echo "🔍 扫描Node.js依赖许可证..."
    LICENSE_OUTPUT=$(license-checker --production --summary 2>/dev/null || echo "未安装license-checker")
    if echo "$LICENSE_OUTPUT" | grep -qi "GPL\|AGPL"; then
        echo "⚠️ 警告：检测到GPL/AGPL类许可证，可能存在兼容性风险！"
        echo "$LICENSE_OUTPUT" | head -20
    exit 1
    fi
fi
# 检查新增文件的头部注释是否包含许可证信息
for FILE in $CHANGED_FILES; do
    if [[ "$FILE" == *.py || "$FILE" == *.js || "$FILE" == *.ts ]]; then
        HEADER=$(head -5 "$FILE")
        if ! echo "$HEADER" | grep -qi "license\|copyright"; then
            echo "⚠️ 警告：文件 $FILE 未包含许可证头部声明！"
            # 此处生产环境应exit 1，但为演示改为警告
        fi
    fi
done
echo "✅ 许可证初步检查通过，继续提交..."
exit 0

步骤3：赋予可执行权限并测试

chmod +x .git/hooks/pre-commit
# 尝试提交测试
git add .
git commit -m "测试提交"

步骤4：扩展pre-push钩子

创建 .git/hooks/pre-push,增加更严格的依赖审计：

#!/bin/bash
# pre-push: 完整许可证扫描（耗时较长，适合持续集成场景）
echo "🔄 执行深度许可证合规扫描..."
# 扫描整个项目的依赖
if command -v license-checker &> /dev/null; then
    license-checker --production --csv --out /tmp/audit.csv
    # 扫描结果送给安全团队分析
fi
# 可集成到CI/CD：若发现禁止许可证（如WTFPL、Unlicense），直接拒绝推送
exit 0

常见问题与最佳实践（FAQ）

Q1：钩子脚本如何获取并使用许可证黑名单？

A：维护一个license-blocklist.txt文件，内含禁止使用的许可证名称，脚本使用grep -f读取该文件并对比扫描结果。

BLOCKED=$(cat .license-blocklist.txt)
if echo "$LICENSE_OUTPUT" | grep -iqE "$BLOCKED"; then
    echo "❌ 发现黑名单许可证，禁止提交！"
    exit 1
fi

Q2：检查依赖时，如何处理嵌套依赖（间接依赖）的合规？

A：使用license-checker的--depth参数（如--depth 3）控制递归层次，但深度越深检查越慢，建议只检查直接依赖（--production模式）。

Q3：若项目本身使用GPL，能否引入MIT模块？

A：可以，GPL允许动态链接MIT代码（视为单独作品），反之MIT代码调用GPL库需遵守GPL条款，脚本应基于“copyleft传染性”规则生成报告，而非简单拦截，建议整合第三方合规工具（如FOSSA或Snyk）的API。

Q4：如何在团队中推广Git钩子使用？

A：将钩子脚本放入项目根目录的.githooks/文件夹，并在README.md中说明，或使用husky（Node.js）工具自动初始化钩子：

npm install --save-dev husky
npx husky install

Q5：脚本处理大量文件时性能下降，如何优化？

A：使用git diff的--name-only减少文件扫描量；复杂许可证匹配使用正则缓存；仅对新增文件（--diff-filter=A）进行头部注释扫描,避免每次检查全部文件。

本文详细展示了如何利用Git钩子脚本实现许可证合规的自动检查，从理论概念到实战代码，再到常见问题解答,核心收获包括：

• 前置拦截：在代码进入版本库前，自动识别许可证缺失、冲突或黑名单问题。
• 轻量集成：无需专用服务器,仅需安装少量依赖即可工作。
• 可扩展性：通过集成license-checker、scanCode等工具,覆盖语言和框架范围。

未来趋势中，CI/CD管道（如GitHub Actions）将取代本地钩子成为主流的合规检查场景，但其核心逻辑与本文所述一致，建议开发者将钩子脚本作为“第一道防线”,同时配合自动化CI向合规团队输出可追溯报告。