前端工程化← 返回文章列表

Biome 与 Git Hooks：前端提交自动校验实践

介绍基于 Biome、lint-staged 与 simple-git-hooks 的 Git 提交检查方案，实现暂存区代码检查、格式化与 Conventional Commits 提交规范约束。

LJ
李建辉·前端全干工程师

· 8 分钟

本页目录展开 / 收起

读完你能做什么

  • 区分本地提交钩子与 CI 校验的职责，不把安全边界放在可跳过的钩子里。
  • 用 Biome 检查暂存文件，并用规则校验 Conventional Commits。
  • 保持本地反馈快速，同时让远端流水线做最终裁决。

本地钩子优化的是反馈速度，不是强制安全。开发者可以跳过钩子，因此分支保护和 CI 必须重复关键检查。

在多人协作的代码仓库中，常常遇到以下问题：

  • 代码格式不一致，Git Diff 中掺杂大量纯格式改动的噪音；
  • 遗留调试代码或明显错误（未使用的变量、空的 catch 块、未清理的 debugger）；
  • 提交信息随意（如 git commit -m "fix"、"111"），后续排查追溯历史变更困难。

在本地提交阶段接入自动化校验，可以在代码推送到远程前拦截基础质量问题。

工具选型对比

TEXT
传统方案 vs 现代方案:
┌──────────────────────────────┬──────────────────────────────┐
│       传统常见组合           │       轻量方案               │
├──────────────────────────────┼──────────────────────────────┤
│ • ESLint + Prettier          │ • Biome                      │
│   (规则冲突处理、插件多)     │   (单二进制统一 Format + Lint)│
│ • Husky                      │ • Simple-Git-Hooks           │
│   (脚本配置较重)             │   (直接写入 .git/hooks)      │
│ • Commitlint (传统 Node)     │ • 规范化 Conventional Commit │
└──────────────────────────────┴──────────────────────────────┘

核心配置与实战搭建步骤

1. 安装核心轻量依赖

BASH
pnpm add -D @biomejs/biome simple-git-hooks lint-staged @commitlint/cli @commitlint/config-conventional

2. 配置 biome.json

在根目录下初始化 Biome 配置：

JSON
{
  "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
  "vcs": {
    "enabled": true,
    "clientKind": "git",
    "useIgnoreFile": true
  },
  "files": {
    "ignoreUnknown": true,
    "includes": ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.json"]
  },
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 100
  },
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true,
      "correctness": {
        "noUnusedVariables": "error"
      },
      "complexity": {
        "noForEach": "warn"
      }
    }
  }
}

3. 配置 lint-staged：仅针对暂存区文件校验

在 package.json 中添加 lint-staged 配置，确保只扫描本次 git add 的文件，绝不浪费时间全量重扫：

JSON
{
  "lint-staged": {
    "*.{js,ts,tsx,jsx,json}": [
      "biome check --write --no-errors-on-unmatched"
    ],
    "*.{css,scss}": [
      "stylelint --fix"
    ]
  }
}

4. 配置 simple-git-hooks 接管 Git 钩子

在 package.json 中配置 pre-commit 与 commit-msg 钩子：

JSON
{
  "simple-git-hooks": {
    "pre-commit": "pnpm lint-staged",
    "commit-msg": "pnpm commitlint --edit ${1}"
  },
  "scripts": {
    "prepare": "simple-git-hooks"
  }
}

在终端运行一次 npx simple-git-hooks，它会直接将极简的 shell 脚本写入 .git/hooks/ 目录中，零运行时守护开销。

提交信息规范（Conventional Commits）

通过 commitlint.config.cjs 规范团队提交格式：

JS
module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [
      2,
      'always',
      ['feat', 'fix', 'docs', 'style', 'refactor', 'perf', 'test', 'chore', 'revert'],
    ],
    'subject-case': [0],
  },
};

提交验证效果

  • ❌ git commit -m "update" -> 被拦截报错，提示必须包含 feat:, fix: 等有效类型；
  • ✅ git commit -m "feat(auth): 增加 Cloudflare Turnstile 人机验证支持" -> 自动格式化代码并通过校验。

官方资料

工程经验小结

本地 Git Hooks 的核心价值是提供即时反馈，但它不是绝对的安全门禁。开发者可以通过 git commit --no-verify 跳过本地校验，因此远程仓库的 CI 流水线与分支保护规则仍然是不可替代的最终防线。

在向已有大型项目引入 Biome 时，建议优先采用增量检查策略（通过 lint-staged），只对本次变更的文件生效，避免因为历史代码遗留的格式或 Lint 问题阻塞正常的业务交付。

继续阅读

评论