本文目录导读：
- 📖 目录导读
- 什么是Git钩子 & 为什么需要品牌规范检查
- 品牌规范检查的核心要素
- 预提交钩子（pre-commit）：在本地提交前拦截
- 准备钩子（prepare-commit-msg）：自动填充或修正提交信息
- 提交-接收钩子（commit-msg）：验证提交信息
- 推送钩子（pre-push）：在推送远程前执行完整品牌审核
- 实战脚本示例：检查品牌关键词、图片路径与文件名规范
- 常见品牌违规案例及脚本应对
- 集成CI/CD与远程钩子：确保团队协作的最后一公里
- Q&A 问答环节
Git钩子脚本如何检查品牌规范：自动化合规审查的完整指南
📖 目录导读
- 什么是Git钩子 & 为什么需要品牌规范检查
- 品牌规范检查的核心要素
- 预提交钩子（pre-commit）： 在本地提交前拦截不合规内容
- 准备钩子（prepare-commit-msg）： 自动填充或修正提交信息
- 提交-接收钩子（commit-msg）： 验证提交信息是否符合品牌模板
- 推送钩子（pre-push）： 在推送远程前执行完整品牌审核
- 实战脚本示例：检查品牌关键词、图片路径与文件名规范
- 常见品牌违规案例及脚本应对
- 集成CI/CD与远程钩子： 确保团队协作的最后一公里
- Q&A 问答环节
什么是Git钩子 & 为什么需要品牌规范检查
Git钩子（Git Hooks） 是存储在.git/hooks目录下的可执行脚本，在特定Git事件（如commit、push）触发前或后自动运行，它们就像是代码仓库的“安全检查员”,能在问题进入版本历史之前被发现。
品牌规范检查的必要性：
- 企业品牌资产（如Logo、字体、配色、术语）若被误用或篡改,会损害品牌一致性。
- 跨团队协作时，开发人员可能无意中引入不合规的资源路径、拼写错误或过时的品牌关键词。
- 自动化检查能节省人工Review时间,并防止合规性问题流入生产环境。
品牌规范检查的核心要素
在编写钩子脚本前,需要明确品牌规范的内容：
| 检查项 | 示例规范 | 脚本如何捕捉 |
|---|---|---|
| 关键词/术语 | 品牌名必须写为“BrandName”而非“BRANDNAME” | 正则匹配文本差异 |
| 图片资源路径 | 所有品牌Logo应位于assets/brand/目录 |
检查新增文件路径 |
| 配色代码 | 主色必须使用#3B82F6（指定品牌蓝） |
扫描CSS/SCSS文件 |
| 版权声明 | 每个文件头部必须有© 2025 BrandName |
检查文件头注释 |
| 约定名称 | 不得包含old-前缀的文件名 |
使用glob模式过滤 |
| 邮件签名 | 对外邮件模板的Footer必须一致 | 扫描HTML/MD文件 |
预提交钩子（pre-commit）：在本地提交前拦截
作用：在git commit执行前，扫描所有暂存区（staged）的文件,如果发现品牌违规则拒绝提交。
脚本示例（bash）：
#!/bin/bash
# .git/hooks/pre-commit
# 定义违规规则
BRAND_KEYWORDS=("BrandName" "BrandColor" "BrandSlogan")
FORBIDDEN_WORDS=("temp-brand" "old-logo" "unreviewed")
# 检查暂存区中所有新增或修改的文件
for file in $(git diff --cached --name-only --diff-filter=ACM); do
# 检查文件名是否包含禁止词
for word in "${FORBIDDEN_WORDS[@]}"; do
if echo "$file" | grep -qi "$word"; then
echo "❌ 品牌违规：文件名 '$file' 包含禁止词 '$word'"
exit 1
fi
done
# 检查文件内容是否包含错误品牌名（忽略二进制文件）
if [[ ! "$file" =~ \.(png|jpg|jpeg|svg|ico|woff2?)$ ]]; then
for keyword in "${BRAND_KEYWORDS[@]}"; do
if grep -qn "$keyword" "$file"; then
echo "✅ 发现品牌关键词 '$keyword' 在 $file"
fi
done
# 检查未授权变体
if grep -qP "(?i)(\bbrandname\b|\bbrandcolor\b)" "$file"; then
echo "⚠️ 警告：'$file' 中使用了不精确的品牌大小写"
exit 1
fi
fi
done
要点：使用git diff --cached确保只检查即将提交的内容,未staged的修改不被干扰。
准备钩子（prepare-commit-msg）：自动填充或修正提交信息
作用：在提交信息编辑器打开前,自动注入品牌要求的格式模板，
[BRAND-1234] 类型: 简短描述
- 改动说明
- 关联品牌组件脚本片段：
#!/bin/bash # .git/hooks/prepare-commit-msg COMMIT_MSG_FILE=$1 # 如果提交信息为空（非merge/amend场景），注入模板 if [ -z "$(head -1 "$COMMIT_MSG_FILE")" ]; then cat > "$COMMIT_MSG_FILE" << EOF #[Brand-XXX] 提交类型: 描述 # 品牌规范：请确保提交信息包含有效Jira编号 # 使用以下前缀：feat/fix/docs/refactor EOF fi
提交-接收钩子（commit-msg）：验证提交信息
脚本示例：
#!/bin/bash # .git/hooks/commit-msg MSG=$(cat "$1") # 必须包含品牌专属编号（如Jira编号） if ! echo "$MSG" | grep -qE "^\[BRAND-[0-9]+\]"; then echo "❌ 提交信息必须以 '[BRAND-XXX]' 开头（如 [BRAND-1234]）" exit 1 fi # 禁止包含非品牌术语 if echo "$MSG" | grep -qi "deprecated\|legacy\|outdated"; then echo "⚠️ 提交信息包含禁止词汇，请改用品牌推荐的术语（如'archived'）" exit 1 fi
推送钩子（pre-push）：在推送远程前执行完整品牌审核
此钩子适合执行重量级检查，
- 全量扫描所有被推送的分支中是否包含品牌密钥（如API key、内部路径）
- 检查是否有未通过品牌合规的commit message
脚本示例：
#!/bin/bash
# .git/hooks/pre-push
remote="$1"
url="$2"
# 获取即将推送的commits
for commit in $(git rev-list origin/main..HEAD); do
# 检查该commit的message
msg=$(git log --format=%B -n1 "$commit")
if ! echo "$msg" | grep -q "Brand\|品牌"; then
echo "❌ Commit $commit 缺少品牌引用（应包含'Brand'关键词）"
exit 1
fi
# 检查该commit引入的文件
for file in $(git diff-tree --no-commit-id -r --name-only "$commit"); do
# 检查是否包含了过时品牌名（如旧版Logo路径）
if [[ "$file" == *"old-brand"* ]]; then
echo "❌ 文件路径包含'old-brand'，请迁移至新品牌目录"
exit 1
fi
done
done
实战脚本示例：检查品牌关键词、图片路径与文件名规范
综合脚本（Python版，更易扩展）：
#!/usr/bin/env python3
# .git/hooks/pre-commit 或作为独立脚本调用
import subprocess, sys, re
def get_staged_files():
result = subprocess.run(
['git', 'diff', '--cached', '--name-only', '--diff-filter=ACM'],
capture_output=True, text=True
)
return result.stdout.strip().split('\n') if result.stdout else []
def check_brand_compliance(filepath):
errors = []
# 规则1：文件名不能包含 'ex-brand', 'old-brand'
if re.search(r'(ex-brand|old-brand)', filepath, re.IGNORECASE):
errors.append(f"文件名包含过期品牌前缀: {filepath}")
# 规则2：图片必须放在 assets/brand/ 目录下
if filepath.endswith(('.png','.jpg','.svg')) and not filepath.startswith('assets/brand/'):
errors.append(f"品牌资源必须放入 'assets/brand/' 目录: {filepath}")
# 规则3：文件内容不能包含错误品牌名称大小写
if not filepath.endswith(('.png','.jpg','.ico','.woff2')):
with open(filepath, 'r', errors='ignore') as f:
content = f.read()
if re.search(r'BrandName', content) and not re.search(r'BrandName', content):
pass # 此处仅为示例，实际需精确匹配
if re.search(r'color: #000000', content): # 假设品牌主色非纯黑
errors.append(f"发现非品牌色 #000000: {filepath}")
return errors
def main():
files = get_staged_files()
all_errors = []
for f in files:
if f: # 避免空字符串
all_errors.extend(check_brand_compliance(f))
if all_errors:
print("❌ 品牌规范违规项：")
for err in all_errors:
print(f" - {err}")
sys.exit(1)
else:
print("✅ 品牌规范检查通过")
if __name__ == "__main__":
main()
常见品牌违规案例及脚本应对
| 违规场景 | 示例 | 脚本处理方式 |
|---|---|---|
| 使用了旧版Logo文件名 | logo-v1.png |
禁止包含v1、old等字符 |
| 拼写错误品牌名 | BranName |
正则匹配 [Bb]rand[Nn]ame 并报错 |
| 使用了非品牌字体 | font-family: Arial |
扫描CSS文件，只允许font-family: BrandFont |
| 版权年份过期 | © 2023 |
检查当前年份并提示更新 |
| 图片路径错误 | img/logo.png 而非 assets/brand/logo.png |
验证路径是否以assets/brand/开头 |
集成CI/CD与远程钩子：确保团队协作的最后一公里
本地钩子可以被跳过（git commit --no-verify）,因此需要远程校验：
- 在CI/CD中执行品牌检查：在构建阶段运行与本地相同的脚本，使用
git log或git diff分析改动。 - 使用GitHub Actions示例：
name: Brand Compliance Check on: [push, pull_request] jobs: brand-check: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Run brand hook script run: bash .github/scripts/brand-check.sh - 服务端钩子（如Gitea/GitLab）：通过pre-receive钩子拒绝不合规推送。
Q&A 问答环节
Q1：Git钩子脚本存储在本地，如何让团队所有成员都生效？
A：将脚本放在项目根目录的scripts/hooks/下，然后通过git init后复制到.git/hooks/，或使用git config core.hooksPath scripts/hooks让Git自动读取。
Q2：品牌规范检查主要针对哪些文件类型？
A：建议覆盖文本文件（.md、.html、.js、.css、.py等）和品牌资源文件（.svg、.png、.jpg、.ico），二进制文件（.exe、.zip）可跳过。
Q3：如何避免钩子脚本运行过慢？
A：限制扫描范围（只检查staged文件）、使用git diff只查增量内容、对大型二进制文件跳过内容扫描。
Q4：如果团队使用了不同的品牌规范版本怎么办？
A：在项目中维护一个BRAND_RULES.json配置文件，脚本读取该文件动态调整规则,支持分支差异化。
Q5：钩子脚本是否支持Windows环境？
A：Bash脚本在Windows的Git Bash下运行，Python脚本需配置Python环境；建议使用跨平台脚本（如Python或Node.js）避免兼容性问题。
