关键词:Conventional Commits、Git 提交信息、Commit Message、规范化提交、纯前端、JavaScript
一、背景与需求
在团队协作开发中,Git 提交信息的规范性直接影响代码库的可维护性与可追溯性。混乱的提交信息(如 fix bug、update、asdf)会导致代码评审困难、自动化发布流水线难以解析、变更日志(Changelog)无法自动生成。
Conventional Commits 规范(项目地址:www.conventionalcommits.org/)通过统一的提交信息格…
<type>(<scope>): <subject>
<body>
<footer>
但手动记忆并严格遵循该规范对开发者有一定学习成本,尤其在 type、scope、breaking change 标记等细节上容易出错。
现有的在线生成工具普遍存在以下问题:
- 需要注册登录,或将提交内容上传到服务器,代码上下文泄露风险高;
- 仅支持部分 type 字段,缺少 breaking change、
!标记与 BREAKING CHANGE 脚注的自动补全; - 缺乏实时预览与一键复制功能,生成后仍需手动调整格式。
基于此,我开发了 Toolion Conventional Commits 提交信息生成器(toolion.cn/conventiona… Git 提交信息生成工具,支持 type、scope、subject、body、footer 等字段,全部处理在浏览器本地完成,无需登录,免费使用。
二、核心功能
| 功能模块 | 说明 |
|---|---|
| 类型 (type) 选择 | 支持 feat、fix、docs、style、refactor、perf、test、build、ci、chore、revert 等 11 种规范类型 |
| 作用域 (scope) | 可选,用于标识变更影响范围,如 auth、ui、api |
| 简短描述 (subject) | 必填,用一句话描述本次修改,建议使用祈使句、首字母小写、结尾不加句号 |
| 详细描述 (body) | 可选,用于说明提交动机、实现方案或注意事项 |
| 脚注 (footer) | 可选,用于关联 Issue(如 Closes #123)或说明破坏性变更 |
| 破坏性变更 (Breaking Change) | 勾选后在 type 后自动加 ! 标记,并在 footer 自动补全 BREAKING CHANGE: |
| 实时预览 | 输入字段变化时,右侧即时生成并高亮展示完整提交信息 |
| 一键复制 | 将生成的提交信息复制到剪贴板,支持 navigator.clipboard 与 execCommand 降级方案 |
| 纯前端本地处理 | 所有计算与渲染在浏览器内完成,提交内容不上传服务器,支持离线运行 |
| 免费无需注册 | 打开页面即可使用,无登录、无订阅、无水印 |
| 深色/浅色主题 | CSS 变量适配深色模式,状态持久化到本地存储 |
三、技术实现
3.1 整体架构
该工具是一个纯前端单页面应用(单 HTML 文件),未引入 Vue/React 等前端框架,全部逻辑使用原生 JavaScript 实现:
浏览器端(纯原生 JavaScript)
├── 输入层:type 下拉框、scope/body/footer 文本框、subject 文本框、breaking change 复选框
├── 生成层:解析输入 → 组装 Header → 组装 Body/Footer → 生成完整提交信息
├── 预览层:语法高亮渲染(type/scope/subject/body/footer 分色)
└── 输出层:复制到剪贴板、主题切换、表单输入防抖
3.2 提交信息组装逻辑
核心函数 generateCommit() 负责从表单读取字段,按照 Conventional Commits 规范组装完整信息:
function generateCommit() {
const type = typeEl.value.trim();
const scope = scopeEl.value.trim();
const subject = subjectEl.value.trim();
const body = bodyEl.value.trim();
let footer = footerEl.value.trim();
const isBreaking = breakingEl.checked;
// subject 为必填项,为空时提示并禁用复制按钮
if (!subject) {
previewBox.textContent = '请在左侧填写「简短描述」以生成 Commit Message。';
currentMessage = '';
btnCopy.disabled = true;
return;
}
// 处理 Breaking Change 标记
let breakingMark = '';
if (isBreaking) {
breakingMark = '!';
// 避免 footer 中重复追加 BREAKING CHANGE
if (!hasBreakingChangeKeyword(footer)) {
if (footer) footer += '\n';
footer += 'BREAKING CHANGE: ' + subject;
}
}
// 组装 Header:type(scope)!: subject 或 type!: subject
const header = scope
? `${type}(${scope})${breakingMark}: ${subject}`
: `${type}${breakingMark}: ${subject}`;
// 组装完整文本,body 与 footer 之间用空行分隔
let fullMessage = header;
if (body) fullMessage += '\n\n' + body;
if (footer) fullMessage += '\n\n' + footer;
// 渲染带高亮的预览
// ...
currentMessage = fullMessage;
btnCopy.disabled = false;
}
关键点:
- Header 格式:
type(scope)!: subject(有 scope)或type!: subject(无 scope);breaking change 时在 type 与(或:之间插入!; - Breaking Change 脚注自动补全:勾选破坏性变更后,若 footer 中未包含
BREAKING CHANGE:关键字,自动在 footer 末尾追加BREAKING CHANGE: <subject>; - 空行分隔:Header、Body、Footer 之间使用双换行符(
\n\n)分隔,符合规范; - 必填校验:
subject为空时不生成预览,复制按钮保持禁用状态。
3.3 Breaking Change 关键字检测
为避免重复追加 BREAKING CHANGE:,工具会先检测 footer 中是否已存在该关键字:
function hasBreakingChangeKeyword(text) {
return /breaking[\s-]change\s*:/i.test(text);
}
关键点:
- 大小写不敏感:通过
/i标志匹配BREAKING CHANGE:、breaking change:等变体; - 空格或连字符:
[\s-]同时支持BREAKING CHANGE:与BREAKING-CHANGE:两种写法; - 仅在 footer 中未检测到关键字时才自动追加,避免重复。
3.4 预览高亮渲染
生成的提交信息在右侧预览框中以 HTML 形式渲染,对各字段分色高亮,便于用户直观核对:
let html = '';
html += `<span class="hl-type">${escapeHtml(type)}</span>`;
if (scope) {
html += `(<span class="hl-scope">${escapeHtml(scope)}</span>)`;
}
if (isBreaking) html += `<span class="hl-type">!</span>`;
html += `: <span class="hl-subject">${escapeHtml(subject)}</span>`;
if (body) {
html += `<span class="hl-body">${escapeHtml(body)}</span>`;
}
if (footer) {
html += `<span class="hl-footer">${escapeHtml(footer)}</span>`;
}
previewBox.innerHTML = html;
关键点:
- XSS 防护:所有用户输入通过
escapeHtml转义& < > " ',防止恶意内容注入页面; - 分色方案:type 使用品牌色(
--brand)、scope 使用警告色(--warn)、subject 使用正文色(--ink)、body 使用次要色(--ink-soft)、footer 使用警告色; - 白空格保留:
white-space: pre-wrap保留换行与缩进,体段结构清晰。
3.5 复制到剪贴板
点击“复制提交信息”按钮后,将当前生成的完整文本写入剪贴板:
btnCopy.addEventListener('click', function () {
if (!currentMessage) return;
const done = function () {
btnCopy.textContent = '已复制!';
setTimeout(() => { btnCopy.textContent = '复制提交信息'; }, 1500);
};
if (navigator.clipboard && window.isSecureContext) {
navigator.clipboard.writeText(currentMessage).then(done).catch(() => fallbackCopy(currentMessage, done));
} else {
fallbackCopy(currentMessage, done);
}
});
function fallbackCopy(text, done) {
try {
const textArea = document.createElement('textarea');
textArea.value = text;
textArea.style.cssText = 'position:fixed;top:-9999px;left:-9999px;opacity:0;';
document.body.appendChild(textArea);
textArea.select();
document.execCommand('copy');
document.body.removeChild(textArea);
done();
} catch (e) {
alert('复制失败,请手动选择复制。');
}
}
关键点:
- 现代 API 优先:
navigator.clipboard.writeText(),仅在安全上下文(HTTPS)下可用; - 降级方案:创建隐藏
textarea配合document.execCommand('copy'),兼容非 HTTPS 或旧版浏览器; - 状态反馈:按钮文字临时改为“已复制!”,1.5 秒后恢复;
- 模块级缓存:
currentMessage变量保存当前完整文本,避免通过dataset存储导致残留或容量限制问题。
3.6 表单输入与实时响应
所有输入字段绑定 input 与 change 事件,任意字段变化时立即重新生成预览:
const inputs = [typeEl, scopeEl, subjectEl, bodyEl, footerEl, breakingEl];
inputs.forEach(el => {
el.addEventListener('input', generateCommit);
el.addEventListener('change', generateCommit);
});
初始化时禁用复制按钮,并调用一次 generateCommit() 渲染默认预览:
btnCopy.disabled = true;
generateCommit();
四、关键技术挑战与解决方案
| 挑战 | 解决方案 |
|---|---|
| Conventional Commits 格式严格,易手写出错 | 按规范组装 Header/Body/Footer,自动处理 ! 标记与 BREAKING CHANGE: 脚注 |
| 重复追加 Breaking Change 脚注 | 正则 /breaking[\s-]change\s*:/i 检测 footer 是否已存在关键字,仅不存在时追加 |
| 用户输入包含 HTML 特殊字符导致 XSS | escapeHtml 转义所有用户输入后再渲染到预览框 |
| 非 HTTPS 环境下剪贴板 API 不可用 | navigator.clipboard 优先,失败后降级为 textarea + execCommand('copy') |
| 复制按钮应在无有效内容时禁用 | subject 为空时不生成预览,btnCopy.disabled = true |
| 数据残留与容量限制 | 使用模块级变量 currentMessage 保存当前文本,替代 dataset 存储 |
| 纯前端无后端依赖 | 所有生成与复制逻辑在浏览器本地完成,提交内容不上传任何服务器 |
五、使用示例
场景 1:生成一个普通功能提交
-
打开
https://toolion.cn/conventional-commits/; -
类型选择
feat: 新功能; -
作用域输入
auth; -
简短描述输入
添加用户登录功能; -
详细描述输入
实现基于 JWT 的用户登录鉴权,支持记住我功能; -
右侧预览展示: feat(auth): 添加用户登录功能
实现基于 JWT 的用户登录鉴权,支持记住我功能 -
点击“复制提交信息”,粘贴到 Git 提交命令中。
场景 2:生成一个破坏性变更提交
-
类型选择
feat; -
勾选“这是一次破坏性变更 (Breaking Change)”;
-
简短描述输入
重构用户权限模型; -
右侧预览展示: feat!: 重构用户权限模型
BREAKING CHANGE: 重构用户权限模型 -
type后自动加!,footer 自动补全BREAKING CHANGE:。
场景 3:关联 Issue 修复 Bug
-
类型选择
fix: 修复 Bug; -
简短描述输入
修复导航栏在移动端显示异常的问题; -
脚注输入
Closes #456; -
右侧预览展示: fix: 修复导航栏在移动端显示异常的问题
Closes #456
注意事项:
subject建议使用祈使句(如“添加”而非“添加了”),首字母小写,结尾不加句号,符合 Conventional Commits 最佳实践;scope为可选字段,若项目无明确模块划分可留空;- 破坏性变更建议谨慎使用,勾选后会自动在
type后加!并追加BREAKING CHANGE:脚注; - 所有数据仅在浏览器本地处理,页面刷新后内容将丢失,重要提交信息建议及时复制保存。
六、免责声明
本文仅提供技术实现分享,相关工具仅供学习与日常便利使用,不构成任何商业建议。生成的提交信息基于 Conventional Commits 规范,但具体项目应遵循团队或组织制定的提交约定。所有数据仅在浏览器本地内存中处理,不上传服务器,页面关闭后即从内存释放。
七、总结
本文介绍了一种纯前端实现的 Conventional Commits 提交信息生成方案。核心设计思路:
- 规范化组装:按照
type(scope)!: subject格式组装 Header,Body 与 Footer 之间用空行分隔; - Breaking Change 自动化:勾选破坏性变更后自动加
!标记并补全BREAKING CHANGE:脚注,正则检测避免重复追加; - 实时高亮预览:输入即时生成,type/scope/subject/body/footer 分色高亮,方便核对;
- 一键复制:
navigator.clipboard优先,execCommand降级,兼容多种浏览器环境; - 输入校验与防抖:
subject必填,空时禁用复制按钮;input/change事件实时响应; - XSS 防护:所有用户输入通过
escapeHtml转义后再渲染; - 隐私优先:全部处理在浏览器本地完成,提交内容不上传服务器,无需登录,免费使用;
- 主题适配:CSS 变量支持深色/浅色模式切换。
该方案适合需要轻量级、纯前端 Git 提交信息生成能力的场景,可作为前端开发辅助工具页面的技术参考。
#Conventional Commits #Git提交信息 #CommitMessage #规范化提交 #纯前端 #JavaScript #本地处理 #隐私安全 #开发工具 #前端开发 #工具开发