Files

T

之前的措辞容易被读成"提交信息只能有一行"。现在把三段结构摆出来，并写明
首行、正文、脚注各自的要求与宽度上限，正文和脚注都标注为可省略。

顺带说明：正文不是违规内容，没有正文是允许而不是必须。

2026-09-30 16:56:04 +08:00

5.1 KiB

Raw Blame History

提交信息规范

本仓库的提交信息遵循 Conventional Commits 的结构，并在行首加一个 emoji 做视觉标记。描述用中文，类型关键字、作用域、脚注关键字保持英文。

格式

提交信息分三段，除首行外都可省略：

<emoji> <type>[(scope)][!]: <描述>          ← 首行，必写，永远只有一行
                                             ← 一个空行分隔（没有正文时连空行也不要）
[正文：可多段多行，说清为什么这么改]           ← 可选
                                             ← 一个空行分隔（没有脚注时可省略）
[脚注：Refs: / Closes: / BREAKING CHANGE:]   ← 可选

<emoji>：下面表格里该类型对应的 emoji，后面跟一个空格。emoji 是必需的，且必须与本行类型一致——📝 docs: 对，✨ docs: 不对。
<type>：小写英文关键字，见下表。
(scope)：可选，改动范围。用 () 包住一个简短英文标识，例如 docs(ci)、fix(client)、feat(host)。
!：可选，紧跟在 type 或 scope 之后、冒号之前，表示破坏性变更。
<描述>：中文，一句话，讲清这次改动做了什么；不换行、不用列表、不加句号。首行宽度不超过 72（中文字符按 2 个宽度算）。
正文：可选，中文，可以多段多行，每行不超过 72 个宽度。写"为什么这么改""影响面""迁移要注意什么"，不要复述 diff。描述一句话讲得清时就不要写正文。
脚注：可选（破坏性变更除外），关键字用英文。破坏性变更必须写 BREAKING CHANGE: <中文说明>，不能只靠 !。

上面说的"单行"指的是首行只有一行（不用列表、不折行）——正文是另一回事，需要时就写，多写几段不算违规。别把两者混起来：没有正文是允许的，不是要求。

类型与 emoji

类型	emoji	码位	用途
`feat`	✨	`U+2728`	新增功能
`fix`	🐛	`U+1F41B`	修复缺陷
`docs`	📝	`U+1F4DD`	只改文档
`refactor`	♻️	`U+267B U+FE0F`	重构，行为不变
`perf`	⚡️	`U+26A1 U+FE0F`	性能优化
`test`	✅	`U+2705`	变更测试
`build`	📦️	`U+1F4E6 U+FE0F`	构建系统或依赖
`ci`	💚	`U+1F49A`	CI 配置
`chore`	🔧	`U+1F527`	杂项，以上都不属于时用
`revert`	⏪️	`U+23EA U+FE0F`	回滚某次提交，正文写 `Refs: <被回滚的提交>`

复制上表里的 emoji，不要手敲。 带 U+FE0F 的那五个是「基础字符 + 变体选择符」两个码位，手敲时很容易只打出前一个字符；对工具来说 ♻（U+267B）和 ♻️（U+267B U+FE0F）是两个不同的字符串，比对会失败。写规范或写脚本时，比较 emoji 前先做一次 NFC 归一化，或把两边都按 \uFE0F? 处理。

示例

新增功能：

✨ feat(client): 会话行悬停区加删除按钮

官方 archive 与 pin 两个悬停按钮保持原位，本插件的删除按钮插在两者
之间，不再借用 archive 的 id 压级替换。

修复缺陷：

🐛 fix(host): 延迟删除台账只记录根会话

台账原先记录整棵树，但启动清扫以根为单位整棵删除，导致子会话被重复
删除并重复广播 api-session/removed。

破坏性变更：

♻️ refactor!: 行内按钮改用自己的槽位 id

BREAKING CHANGE: 悬停区布局变化，官方归档按钮回到原来的位置。按住旧
结构写样式的用户需要调整。

纯文档：

📝 docs: 安装说明改为只走 Git 标签与本地 tgz

工具链提示

emoji 在行首是本仓库的有意选择，视觉上整齐。代价是：以类型前缀开头的解析工具（commitlint、semantic-release、release-please 等）会读不到类型。如果以后要接这类工具，有两条路：

把 emoji 挪到冒号之后（feat: ✨ 描述），类型回到行首，规范其余部分不变；
保留行首 emoji，给工具写一个剥掉开头 emoji 与空格的预处理。可用的正则（\p{Extended_Pictographic} 已覆盖带与不带变体选择符两种写法）：
```
^(?:\p{Extended_Pictographic}\uFE0F?\s+)?(?<type>[a-z]+)(?:$(?<scope>[^)]*)$)?(?<breaking>!)?:\s(?<desc>.+)$
```

自查

scripts/check-commit-log.mjs 会按本规范检查现有提交的首行，只报告、不拦提交：

node scripts/check-commit-log.mjs        # 最近 10 条
node scripts/check-commit-log.mjs all    # 全部

它从本文件的类型表里读 emoji 对照表，所以改了表不用改脚本。规范之前的提交不符合是正常的。

启用提交模板（可选）

.gitmessage 是提交信息模板。启用后每次 git commit 会带上前缀提示，删掉不需要的部分即可：

git config commit.template .gitmessage

模板里以 # 开头的行会被 git 自动丢弃，不会进入提交信息。只对当前仓库生效；换机器要重新执行一次。

5.1 KiB Raw Blame History Unescape Escape

提交信息规范

格式

类型与 emoji

示例

工具链提示

自查

启用提交模板（可选）

5.1 KiB

Raw Blame History