pre-commit配置详解

哆啦code梦2026-01-30 14:37

pre-commit-config.yaml 是一个 pre-commit 框架 使用的配置文件，它定义了你在提交代码（git commit）前要自动执行哪些 代码检查或格式化任务。

✅ 一、它是做什么的？

当你运行：

bash 复制代码 
git commit -m "fix: 修复登录bug"

在提交前，pre-commit 会自动检查你这次提交的代码是否符合规范，比如：

  • 代码格式是否正确（Prettier、ESLint、Black 等）
  • 是否有未格式化的文件
  • 是否包含敏感信息（如密码、API Key）
  • 提交信息是否符合规范（可选）

✅ 如果检查失败，git commit 会 被阻止，直到你修复问题。

✅ 二、文件位置和命名

  • 文件名：.pre-commit-config.yaml
  • 位置：项目根目录（和 package.json、requirements.txt 同级）

📌 注意：文件名以 . 开头，是隐藏文件。

✅ 三、典型配置示例

yaml 复制代码 
# .pre-commit-config.yaml

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.5.0
    hooks:
      - id: check-yaml
      - id: check-added-large-files
      - id: check-merge-conflict
      - id: end-of-file-fixer
      - id: trailing-whitespace

  - repo: https://github.com/eslint/eslint
    rev: v8.56.0
    hooks:
      - id: eslint
        args: [--ext, .js,.jsx,.ts,.tsx]

  - repo: https://github.com/prettier/prettier
    rev: v3.2.5
    hooks:
      - id: prettier
        args: [--write]

  - repo: https://github.com/pycqa/isort
    rev: 5.13.2
    hooks:
      - id: isort
        args: [--profile=black]

  - repo: https://github.com/PyCQA/flake8
    rev: 6.1.0
    hooks:
      - id: flake8

✅ 四、作用详解

功能 说明
🔍 自动检查代码质量 防止提交格式混乱、语法错误的代码
🧹 自动格式化代码 比如 Prettier 会自动帮你排版 JS/TS/HTML
🚫 阻止不合规提交 一旦检查失败，git commit 就不会成功
🤝 团队协作统一标准 所有人用一样的规则，避免"你的代码看起来像屎"

✅ 五、如何使用？

1. 安装 pre-commit 工具（一次即可）
bash 复制代码 
pip install pre-commit   # Python 项目
# 或
npm install -g pre-commit  # Node.js 项目
2. 安装钩子到 .git/hooks/
bash 复制代码 
pre-commit install

这条命令会把 pre-commit 框架的钩子安装到 .git/hooks/，以后每次 git commit 都会触发。

3. 可选：手动运行所有检查
bash 复制代码 
pre-commit run --all-files

或者
添加 pre-commit本地自动化

在项目中添加一个 package.json 脚本

复制代码 
"scripts": {
  "pre-commit": "pre-commit run --all-files"
}

然后安装 husky

复制代码 
npm install husky --save-dev
npx husky add .husky/commit-msg 'npx --no-install commitlint --edit $1'
npx husky add .husky/pre-commit 'npm run pre-commit'

✅ 六、常见搭配工具

工具 用途
ESLint 检查 JS/TS 语法错误、代码风格
Prettier 自动格式化代码（缩进、引号等）
Black Python 代码自动格式化工具
isort 自动排序 Python 导入语句
flake8 Python 代码风格检查
check-yaml 检查 YAML 文件格式是否正确

✅ 七、总结

pre-commit-config.yaml 是一个 代码质量守门员的配置文件，它告诉 Git："在你提交代码之前，先让我检查一遍！"

💡 小贴士

  • 可以配合 husky 使用（尤其前端项目），实现更强大的自动化。
  • 推荐把 .pre-commit-config.yaml 提交到 Git，让整个团队统一标准。

附录（Python+React项目 pre-commit配置）

yaml 复制代码 
# .pre-commit-config.yaml
# 专为 Python + React 全栈项目设计
# 支持：Python (Black, isort, flake8)，JS/TS (Prettier, ESLint)，React

repos:
  # ========================
  # Python 代码检查与格式化
  # ========================

  # Black：自动格式化 Python 代码
  - repo: https://github.com/psf/black
    rev: 23.3.0
    hooks:
      - id: black
        language_version: python3

  # isort：自动排序 Python 导入语句
  - repo: https://github.com/pycqa/isort
    rev: 5.13.2
    hooks:
      - id: isort
        args: [--profile=black]

  # flake8：检查 Python 代码风格与潜在错误
  - repo: https://github.com/pycqa/flake8
    rev: 6.1.0
    hooks:
      - id: flake8
        args: [--extend-ignore=E203,W503]

  # ========================
  # React / JavaScript 代码检查与格式化
  # ========================

  # Prettier：统一 JS/TS/JSON/HTML/CSS 格式
  - repo: https://github.com/prettier/prettier
    rev: v3.2.5
    hooks:
      - id: prettier
        args: [--write]
        types: [javascript, typescript, json, yaml, html, css]

  # ESLint：检查 JS/TS 语法、错误、风格
  - repo: https://github.com/eslint/eslint
    rev: v8.56.0
    hooks:
      - id: eslint
        args: [--ext, .js,.jsx,.ts,.tsx]
        files: \.(js|jsx|ts|tsx)$

  # React Hooks 检查（ESLint 插件）
  - repo: https://github.com/evcohen/eslint-plugin-jsx-a11y
    rev: v6.8.0
    hooks:
      - id: eslint
        args: [--ext, .js,.jsx,.ts,.tsx]
        files: \.(js|jsx|ts|tsx)$
        additional_dependencies:
          - eslint-plugin-jsx-a11y@^6.8.0

  # ========================
  # 通用检查（跨语言）
  # ========================

  # 检查是否提交了大文件（如 .zip、.mp4）
  - repo: https://github.com/pre-commit/mirrors-check-added-large-files
    rev: v0.1.1
    hooks:
      - id: check-added-large-files
        args: [--max-size=10M]

  # 检查是否提交了合并冲突标记
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.5.0
    hooks:
      - id: check-merge-conflict

  # 自动修复文件末尾换行符（避免 Git 报错）
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.5.0
    hooks:
      - id: end-of-file-fixer

  # 自动清理文件末尾空白字符
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.5.0
    hooks:
      - id: trailing-whitespace

快速初始化命令

yaml 复制代码 
# 1. 创建配置文件
echo '
repos:
  - repo: https://github.com/psf/black
    rev: 23.3.0
    hooks:
      - id: black
        language_version: python3.10.2
  - repo: https://github.com/pycqa/isort
    rev: 5.13.2
    hooks:
      - id: isort
        args: [--profile=black]
  - repo: https://github.com/pycqa/flake8
    rev: 6.1.0
    hooks:
      - id: flake8
        args: [--max-line-length=88]
  - repo: https://github.com/prettier/prettier
    rev: v3.2.5
    hooks:
      - id: prettier
        args: [--write]
  - repo: https://github.com/eslint/eslint
    rev: v8.56.0
    hooks:
      - id: eslint
        args: [--ext, .js,.jsx,.ts,.tsx]
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.5.0
    hooks:
      - id: check-added-large-files
      - id: check-merge-conflict
      - id: end-of-file-fixer
      - id: trailing-whitespace
  # 可选：添加 commit-msg 检查（用于 Git 提交信息规范）
  - repo: https://github.com/commitizen/cz-conventional-changelog
    rev: 3.3.0
    hooks:
      - id: commit-msg
        args: [--config, .cz-config.json]
' > .pre-commit-config.yaml

# 2. 安装 pre-commit
pip install pre-commit

# 3. 安装钩子
pre-commit install

💡 说明：

  • rev 使用稳定版本号，避免 CI 爆炸。
  • 支持 black + flake8 + isort 三件套，覆盖主流规范。
  • 如果你使用 commitizen，可以加 commit-msg 检查提交信息。
  • 如果用 Conventional Commits 规范提交信息，可以加一个 .cz-config.json
yaml 复制代码 
// .cz-config.json
{
  "types": [
    { "value": "feat", "name": "✨ Feature: A new feature" },
    { "value": "fix", "name": "🐛 Fix: A bug fix" },
    { "value": "docs", "name": "📘 Docs: Documentation only changes" },
    { "value": "style", "name": "🎨 Style: Changes that do not affect the meaning of the code" },
    { "value": "refactor", "name": "🧱 Refactor: A code change that neither fixes a bug nor adds a feature" },
    { "value": "perf", "name": "⚡ Performance: A code change that improves performance" },
    { "value": "test", "name": "✅ Test: Adding missing tests or correcting existing tests" },
    { "value": "build", "name": "🏗️ Build: Changes that affect the build system or external dependencies" },
    { "value": "ci", "name": "🤖 CI: Changes to our CI configuration files and scripts" },
    { "value": "revert", "name": "⏪ Revert: Reverts a previous commit" }
  ]
}

CI检查配置

yaml 复制代码 
# .gitlab-ci.yml
stages:
  - lint

# 检查代码规范
pre-commit-check:
  image: python:3.11
  stage: lint
  script:
    - pip install pre-commit
    - pre-commit run --all-files
  allow_failure: false  # 必须通过，否则阻断合并
  artifacts:
    when: always
    paths:
      - .pre-commit-config.yaml
    expire_in: 1 week
  retry: 1

✅ ci配置解析：

  • 使用 python:3.11 镜像（可按需替换为 python:3.10 等）
  • pre-commit run --all-files 会自动调用 .pre-commit-config.yaml 中定义的所有 hook
  • allow_failure: false 表示 必须通过，否则 GitLab 会标记为失败，阻止合并（配合 MR 使用更佳）
  • artifacts 用于保存配置文件，便于调试（可选）

八、附录

commit log

json 复制代码 
{ name: "feat", value: "feat", short: "功能" },
{ name: "fix", value: "fix", short: "修复" },
{ name: "docs", value: "docs", short: "文档" },
{ name: "style", value: "style", short: "样式" },
{ name: "refactor", value: "refactor", short: "重构" },
{ name: "perf", value: "perf", short: "性能" },
{ name: "test", value: "test", short: "测试" },
{ name: "build", value: "build", short: "构建" },
{ name: "ci", value: "ci", short: "CI/CD" },
{ name: "revert", value: "revert", short: "回滚" },
{ name: "wip", value: "wip", short: "开发中" }
相关推荐
陈哥聊测试1 年前
老板：你来弄个团队代码提交规范
程序员·devops·企业管理·it团队·测试团队·代码提交规范
热门推荐
01GitHub 镜像站点02Clawdbot 中文汉化版 接入微信、飞书03OpenCode 入门教程：介绍 · 安装 · 配置第三方 API (如 Claude)042026数学建模美赛题目特点与选题建议，常用四大模型汇总05一种新的LCA算法06Claude Code Skills 实用使用手册07UV安装并设置国内源08零门槛部署本地 AI 助手：Clawdbot/Meltbot 部署深度保姆级教程09在Trae中使用Pencil MCP10Linux下V2Ray安装配置指南