← 文章档案

AI 与工具

Git 约定式提交（Conventional Commits）速查

一句话：给 Git 提交信息加上统一的类型前缀，让人一眼看懂这次修改，也方便工具自动生成更新日志和判断版本变化。

8 分钟阅读

一句话：给 Git 提交信息加上统一的类型前缀，让人一眼看懂这次修改，也方便工具自动生成更新日志和判断版本变化。

一、标准格式

<type>[可选的(scope)][可选的!]: <description>

[可选的正文 body]

[可选的页脚 footer]

最常用的是简化版：

类型(模块): 简短描述

例如：

feat(today): add daily lesson
fix(auth): resolve login redirect issue
docs: update README
  • type（类型）：这次改动属于哪一类，例如 feat、fix。
  • scope（范围）：改动涉及的模块，例如 auth、ui、api，可以省略。
  • description（描述）：简短说明究竟做了什么；建议具体、直接。
  • !：标记破坏性变更（Breaking Change），一般不常用。
  • body / footer：需要解释背景、迁移方法或关联 Issue 时再写。

二、常见提交类型

类型英文原意什么时候用示例
featfeature新增功能feat(search): add keyword filtering
fixfix修复 Bugfix(ui): prevent button double click
refactorrefactor调整代码结构，但不新增功能、不修复 Bugrefactor(api): simplify query logic
docsdocumentation只修改文档docs: update setup guide
testtest新增或修改测试test(auth): add login tests
stylestyle只调整代码格式，不改变逻辑style: apply code formatting
perfperformance性能优化perf(graph): reduce render time
buildbuild修改构建工具、依赖和打包配置build(deps): upgrade Next.js
cicontinuous integration修改 CI/CD 自动化流程ci: add GitHub Actions checks
chorechore其他日常维护工作chore: remove obsolete scripts
revertrevert撤销以前的提交revert: revert search feature

规范中有明确版本语义的是 feat、fix 和破坏性变更标记。其余类型是社区常见约定，并非官方强制的完整清单。团队可按需要扩展。

容易混淆的几组

  • feat vs fix：增加原先没有的能力是 feat；原本应该正常工作却出错了，修好它是 fix。
  • refactor vs feat：重构只改变实现方式、保持外部行为；新增用户可感知的功能用 feat。
  • style vs UI 样式：这里的 style 通常指代码格式（空格、缩进、分号等），不是“修改页面视觉样式”的通用标签。改变用户界面行为或外观时，要根据实际改动选择 feat、fix 或 refactor 等。
  • build vs ci vs chore：构建与依赖用 build；GitHub Actions 等自动化流水线用 ci；其他杂项维护用 chore。
  • docs vs chore：修改 README、教程等文档时，优先用更准确的 docs。

三、在 Cyber 2nd Brain 项目里怎么写

feat(today): add daily lesson and review section
fix(today): show correct daily review status
feat(graph): support node filtering
perf(graph): improve graph rendering speed
refactor(database): extract shared query helpers
test(graph): cover node filtering behavior
docs(readme): explain local development setup
build(deps): update project dependencies
ci(github): run tests on pull requests
chore: remove unused assets

today、graph、database 等模块名只是示例，不是固定词汇。一个项目最好保持模块命名一致。

实用原则：一次提交尽量只做一类相关改动。 比如同时“新增筛选”和“修复登录问题”，如果可以独立提交，最好拆成两次，未来排查和回退会容易得多。

四、破坏性变更与版本号

如果改动会让已有接口、调用方式或配置不再兼容，可以加 !：

feat(api)!: change authentication response format

也可以在页脚中详细说明：

feat(api): change authentication response format

BREAKING CHANGE: clients must now read access_token instead of token.

Conventional Commits 与语义化版本（SemVer）可以对应：

提交含义版本变化（在正式版本 1.0.0 及以上的一般规则）举例
fixPATCH：修订版本1.2.3 → 1.2.4
featMINOR：次版本1.2.3 → 1.3.0
! 或 BREAKING CHANGEMAJOR：主版本1.2.3 → 2.0.0

这表示可以用自动化工具据此决定版本号，并不意味着执行 git commit 就会自动升级版本。低于 1.0.0 的版本和具体发布工具也可能有不同策略。

五、常用 Git 命令

创建提交：

git add .
git commit -m "feat(search): add keyword filtering"

查看精简提交历史：

git log --oneline -20

查看带分支线的提交树：

git log --all --graph --decorate --oneline -20

git add . 会暂存当前目录下的所有相关变更；如果只想提交部分文件，建议改用 git add <文件路径>，先检查 git status 和 git diff --staged。

六、给自己和 AI 编程助手的简单规则

个人项目没必要一开始记住全部类型。优先掌握以下六个：

feat      新功能
fix       修 Bug
refactor  代码重构
docs      文档
test      测试
chore     日常维护

可以放进 AI 编程助手的项目指令：

请使用 Conventional Commits 格式撰写 Git 提交信息：type(scope): description。优先使用 feat、fix、refactor、docs、test、chore；描述要具体，并基于实际代码改动选择类型。若包含不兼容变更，明确标记 ! 或 BREAKING CHANGE。不要把不相关的改动混进同一次提交。

七、来源与延伸阅读

Conventional Commits 不是 Git 或 GitHub 的强制功能。它深受 Angular 项目提交规范的影响，由开源社区协作形成独立规范，目的是让提交历史更易读、可被工具解析。

整理日期：2026-10-28。本文是个人速查笔记，不是对完整规范的逐字翻译。