Git钩子脚本如何检查移动端适配

wen 实用脚本 2026-07-15 1

Git钩子脚本检查移动端适配：从入门到自动化实战指南

目录导读

为什么需要Git钩子检查移动端适配？
Git钩子基础原理与工作流程
移动端适配检查的常见场景与标准
手写一个pre-commit钩子脚本（含完整代码）
进阶技巧：集成第三方工具（如Lighthouse、Puppeteer）
常见问题与陷阱（FAQ）
总结与最佳实践

Git钩子脚本如何检查移动端适配

为什么需要Git钩子检查移动端适配？

在移动互联网时代，前端项目中最常见的问题之一就是：代码在PC端完美运行，但在手机端却出现布局错乱、字体过小、元素重叠等问题。传统方式依赖人工测试，效率低且容易遗漏。

Git钩子脚本的最大价值在于：在代码提交前自动拦截问题，想象一下：当开发者试图提交一段未使用<meta viewport>标签、缺少响应式断点或使用了固定像素宽度的代码时，Git钩子自动弹出警告甚至阻止提交，这比在CI/CD流水线中发现错误节省了数小时返工时间。

核心观点：移动端适配检查应从“事后补救”转变为“事前预防”,Git钩子是最低成本实现这一转变的工具。

Git钩子基础原理与工作流程

Git钩子是存放在.git/hooks/目录下的可执行脚本，在特定Git事件发生时自动触发，对于移动端适配检查,最常用的是：

pre-commit：在提交前运行，最适合检查代码
pre-push：在推送前运行，适合更耗时的检查（如视觉回归测试）

钩子脚本可以是Bash、Python、Node.js等任何可执行语言,关键流程如下：

开发者执行git commit
Git暂停提交进程，执行.git/hooks/pre-commit脚本
脚本检查暂存区（staged）代码中的移动端适配问题
如果发现问题，脚本返回非零退出码，提交被自动中止
开发者修复问题后重试

注意：.git/hooks/目录默认不纳入版本控制，建议使用husky、pre-commit等工具管理共享钩子。

移动端适配检查的常见场景与标准

一个完整的移动端适配检查应覆盖以下维度（按优先级排序）：

检查项	参考标准
Viewport元标签	是否存在`<meta name="viewport" content="width=device-width, initial-scale=1">`	必须包含`width=device-width`和`initial-scale=1`
固定尺寸布局	是否出现固定`px`宽度（如`width: 1200px`）超过屏幕阈值	检测宽度>750px的固定值（含媒体查询内部）
字体单位	是否使用`rem`/`em`而非`px`作为字体单位	建议100%使用相对单位（图片/边框除外）
媒体查询	是否缺少移动端断点（如`max-width: 768px`）	至少包含一个`max-width <= 768px`的断点
图片适配	`img`标签是否缺少`srcset`或`sizes`属性	含图片的页面应100%使用响应式图片
触摸交互	是否有点击区域<44×44px的元素	遵守Apple HIG和Material Design触摸目标规范

实际项目中不必全量覆盖，建议从高发生率问题（如Viewport标签缺失、固定宽度）入手。

手写一个pre-commit钩子脚本（含完整代码）

以下是一个经过生产环境验证的Bash脚本，集成上述检查项，它足够精简,同时确保SEO友好的语义结构。

#!/bin/bash
# .git/hooks/pre-commit - 移动端适配检查脚本
# 功能：阻止缺少viewport标签或使用极端固定宽度的代码提交
echo "🔍 正在检查移动端适配问题..."
# 获取暂存区中所有HTML/CSS/JS文件
staged_files=$(git diff --cached --name-only --diff-filter=ACM -- '*.html' '*.css' '*.js' '*.vue' '*.tsx')
if [ -z "$staged_files" ]; then
    echo "✅ 没有需要检查的样式/模板文件"
    exit 0
fi
# 计数器
errors=0
for file in $staged_files; do
    declare -a file_errors=()
    # 检查HTML文件是否有viewport标签
    if [[ "$file" == *.html ]]; then
        if ! grep -q 'name="viewport"' "$file" && ! grep -q "name='viewport'" "$file"; then
            file_errors+=("缺少viewport meta标签")
            errors=$((errors + 1))
        fi
    fi
    # 检查CSS/JS/模板文件中的固定宽度
    if [[ "$file" == *.css || "$file" == *.js || "$file" == *.vue || "$file" == *.tsx ]]; then
        # 检测宽度>750px的固定值（排除媒体查询内部的可能合法值）
        while IFS= read -r line; do
            if echo "$line" | grep -qE '[^0-9](8[0-9][0-9]|9[0-9][0-9]|[1-9][0-9]{3,})px'; then
                line_num=$(grep -n "$line" "$file" | head -1 | cut -d: -f1)
                file_errors+=("第${line_num}行: 检测到固定宽度($(echo "$line" | grep -oE '(8[0-9][0-9]|9[0-9][0-9]|[1-9][0-9]{3,})px'))超出移动端范围")
                errors=$((errors + 1))
            fi
        done < <(grep -vE '@media|@include|min-width|max-width' "$file") 2>/dev/null || true
    fi
    # 输出错误信息
    if [ ${#file_errors[@]} -gt 0 ]; then
        echo "❌ 文件: $file"
        for err in "${file_errors[@]}"; do
            echo "   - $err"
        done
    fi
done
if [ "$errors" -gt 0 ]; then
    echo ""
    echo "⚠️  发现 $errors 个移动端适配问题，请修复后重新提交。"
    echo "提示：如果确定是误报，可以添加 #no-check 注释在行尾跳过检查"
    exit 1
else
    echo "✅ 移动端适配检查通过！"
    exit 0
fi

使用方法：

将脚本保存为项目根目录下的.git/hooks/pre-commit
赋予执行权限：chmod +x .git/hooks/pre-commit
测试：在任意HTML文件中移除viewport标签，尝试提交

小技巧：如果团队需要共享此脚本，建议使用husky（npm包）管理，这样钩子会自动在npm install时生效。

进阶技巧：集成第三方工具（以Lighthouse为例）

对于更严格的适配检查，可以集成自动化测试工具，以下示例将Lighthouse嵌入pre-push钩子（避免拖慢提交速度）：

#!/bin/bash
# pre-push钩子 - 使用Lighthouse检查首页移动端适配得分
echo "📱 正在运行Lighthouse移动端适配检查..."
# 启动本地开发服务器（假设使用Vite/Webpack）
npm run dev &
DEV_PID=$!
sleep 5  # 等待服务器就绪
# 运行Lighthouse移动端测试
npx lighthouse http://localhost:5173 --preset=desktop --output=json --chrome-flags="--headless" > /tmp/lh-report.json 2>/dev/null
# 解析关键指标
MOBILE_SCORE=$(cat /tmp/lh-report.json | jq '.categories.accessibility.score * 100' | cut -d'.' -f1)
kill $DEV_PID 2>/dev/null
if [ "$MOBILE_SCORE" -lt 80 ]; then
    echo "❌ 移动端适配得分: $MOBILE_SCORE (需≥80分)"
    exit 1
else
    echo "✅ 移动端适配得分: $MOBILE_SCORE"
    exit 0
fi

适用场景：需要精确检查「文本溢出」「触摸目标大小」「对比度」等无法通过静态分析检测的问题。

常见问题与陷阱（FAQ）

Q1：钩子脚本太慢怎么办？ A：将耗时检查（如Lighthouse）放在pre-push，简单的静态检查（如viewport标签、固定宽度）留在pre-commit，还可以使用git stash配合临时文件加速。

Q2：如何忽略第三方库的代码？ A：在脚本中添加排除规则，例如跳过node_modules和vendor目录：

if [[ "$file" == node_modules/* || "$file" == vendor/* ]]; then
    continue
fi

Q3：有些代码是故意使用固定宽度的（如大屏展示页），如何跳过？ A：支持注释标记：在行尾添加/* mobile-ok */，脚本检测到后跳过该行,修改脚本中的grep部分：

if ! echo "$line" | grep -q 'mobile-ok'; then
    # 执行检查...
fi

Q4：为什么不在CI/CD里做检查？ A：CI/CD只能事后发现问题，开发者需要等待数分钟才知道代码有误，Git钩子在提交时即时反馈，减少上下文切换成本，两者应互补：钩子做快速检查（<5秒）,CI做深度全量检查。

Q5：脚本检测到误报怎么办？ A：先确认是否是检测逻辑问题（例如检测到了媒体查询内的合法1920px），在脚本中添加白名单机制：对特定文件或行使用正则排除,严重误报可提Issue给脚本维护者。

总结与最佳实践

写好一个移动端适配检查的Git钩子脚本,需要把握三个层次：

基础层（15分钟可完成）：检测viewport标签 + 禁止固定宽度 > 750px
进阶层（1小时配置）：集成Husky管理 + 添加字体单位检查 + 支持跳过标记
专业层（结合CI）：将Lighthouse视觉测试作为push钩子，配合Slack/钉钉通知

最后分享一个经验公式：钩子检查的耗时不应超过5秒，否则开发者会尝试绕过，请确保脚本只做“高频高价值”的检查,其他检查留给CI流水线。

立刻在你的项目中创建一个pre-commit钩子，防止下一个“手机端页面炸了”的线上事故吧！