纯前端实现的 Conventional Commits 提交信息生成器技术实现

0 阅读8分钟

关键词: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 特殊字符导致 XSSescapeHtml 转义所有用户输入后再渲染到预览框
非 HTTPS 环境下剪贴板 API 不可用navigator.clipboard 优先,失败后降级为 textarea + execCommand('copy')
复制按钮应在无有效内容时禁用subject 为空时不生成预览,btnCopy.disabled = true
数据残留与容量限制使用模块级变量 currentMessage 保存当前文本,替代 dataset 存储
纯前端无后端依赖所有生成与复制逻辑在浏览器本地完成,提交内容不上传任何服务器

五、使用示例

场景 1:生成一个普通功能提交

  1. 打开 https://toolion.cn/conventional-commits/;

  2. 类型选择 feat: 新功能;

  3. 作用域输入 auth;

  4. 简短描述输入 添加用户登录功能;

  5. 详细描述输入 实现基于 JWT 的用户登录鉴权,支持记住我功能;

  6. 右侧预览展示: feat(auth): 添加用户登录功能

    实现基于 JWT 的用户登录鉴权,支持记住我功能
    
  7. 点击“复制提交信息”,粘贴到 Git 提交命令中。

场景 2:生成一个破坏性变更提交

  1. 类型选择 feat;

  2. 勾选“这是一次破坏性变更 (Breaking Change)”;

  3. 简短描述输入 重构用户权限模型;

  4. 右侧预览展示: feat!: 重构用户权限模型

    BREAKING CHANGE: 重构用户权限模型
    
  5. type 后自动加 !,footer 自动补全 BREAKING CHANGE:。

场景 3:关联 Issue 修复 Bug

  1. 类型选择 fix: 修复 Bug;

  2. 简短描述输入 修复导航栏在移动端显示异常的问题;

  3. 脚注输入 Closes #456;

  4. 右侧预览展示: fix: 修复导航栏在移动端显示异常的问题

    Closes #456
    

注意事项:

  • subject 建议使用祈使句(如“添加”而非“添加了”),首字母小写,结尾不加句号,符合 Conventional Commits 最佳实践;
  • scope 为可选字段,若项目无明确模块划分可留空;
  • 破坏性变更建议谨慎使用,勾选后会自动在 type 后加 ! 并追加 BREAKING CHANGE: 脚注;
  • 所有数据仅在浏览器本地处理,页面刷新后内容将丢失,重要提交信息建议及时复制保存。

六、免责声明

本文仅提供技术实现分享,相关工具仅供学习与日常便利使用,不构成任何商业建议。生成的提交信息基于 Conventional Commits 规范,但具体项目应遵循团队或组织制定的提交约定。所有数据仅在浏览器本地内存中处理,不上传服务器,页面关闭后即从内存释放。


七、总结

本文介绍了一种纯前端实现的 Conventional Commits 提交信息生成方案。核心设计思路:

  1. 规范化组装:按照 type(scope)!: subject 格式组装 Header,Body 与 Footer 之间用空行分隔;
  2. Breaking Change 自动化:勾选破坏性变更后自动加 ! 标记并补全 BREAKING CHANGE: 脚注,正则检测避免重复追加;
  3. 实时高亮预览:输入即时生成,type/scope/subject/body/footer 分色高亮,方便核对;
  4. 一键复制:navigator.clipboard 优先,execCommand 降级,兼容多种浏览器环境;
  5. 输入校验与防抖:subject 必填,空时禁用复制按钮;input/change 事件实时响应;
  6. XSS 防护:所有用户输入通过 escapeHtml 转义后再渲染;
  7. 隐私优先:全部处理在浏览器本地完成,提交内容不上传服务器,无需登录,免费使用;
  8. 主题适配:CSS 变量支持深色/浅色模式切换。

该方案适合需要轻量级、纯前端 Git 提交信息生成能力的场景,可作为前端开发辅助工具页面的技术参考。


#Conventional Commits #Git提交信息 #CommitMessage #规范化提交 #纯前端 #JavaScript #本地处理 #隐私安全 #开发工具 #前端开发 #工具开发