- 开发工具
【免费下载链接】gitmoji
An emoji guide for your commit messages. 😜
Gitmoji 是一套旨在标准化并解释 GitHub 提交信息（commit message）中 Emoji 用法的社区约定：通过为不同意图的提交分配含义明确的 Emoji，让提交历史无需阅读正文即可一眼识别每次提交的目的。本文以本仓库根目录 README.md 为主线，结合gitmojisnpm 数据包源码、JSON 数据与 JSON Schema，系统讲解 Gitmoji 约定的提交格式、命令行客户端gitmoji-cli的安装使用、npm 数据包与 HTTP API 的消费方式，以及数据校验与发布机制。读完本文，你将能在自己的项目中落地一套可复制、可校验、可持续维护的 Emoji 提交规范。
Gitmoji 是什么：用 Emoji 表达提交意图
在提交信息中使用 Emoji，提供了一种仅凭看 Emoji 就能识别一次提交的目的或意图的简单方式。由于 Emoji 种类繁多，容易各写各的，因此 Gitmoji 倡议建立一份统一指南，帮助大家更轻松、更一致地使用 Emoji。其核心理念可以概括为：
- 约定优于随意：为「修 Bug」「加功能」「重构」「改文档」等高频场景固定对应的 Emoji；
- 可读性优先：在历史记录、PR 列表、Git 工具界面中，Emoji 比纯文字更快被眼球捕捉；
- 可编程化：Emoji 数据以结构化 JSON 发布，可供 CLI、CI 校验、编辑器插件等程序化消费。
本仓库即 Gitmoji 约定的官方数据与网站实现：gitmojis是发布到 npm 的数据包（见 packages/gitmojis/package.json，版本 3.15.0），仓库还包含基于 Next.js 构建的展示网站packages/website。
标准提交格式：<intention> [scope?][:?] <message>
README 给出了一个可直接照搬进团队的提交格式模板：
<intention> [scope?][:?] <message>三个组成部分的含义：
| 占位符 | 必填 | 说明 |
|---|---|---|
intention | 是 | 来自 Gitmoji 列表中的一个 Emoji，表达本次提交的意图 |
scope | 否 | 可选的字符串，为变更范围补充上下文信息（例如模块名、包名） |
message | 是 | 对本次变更的简短说明 |
[:?]表示冒号为可选分隔符，因此下面几种写法都是合法的：
git commit -m "✨ Add user profile page" git commit -m "🐛(auth): Fix token refresh race condition" git commit -m "♻️(core): Extract cache layer"对照本仓库的权威数据源 packages/gitmojis/src/gitmojis.json（共 64 条），常见意图与 Emoji 的对应关系包括：
🎨Improve structure / format of the code —— 改善代码结构或格式；⚡️Improve performance —— 提升性能；🔥Remove code or files —— 删除代码或文件；🐛Fix a bug —— 修复 Bug；✨Introduce new features —— 引入新功能；📝Add or update documentation —— 新增或更新文档；💥Introduce breaking changes —— 引入破坏性变更；🚀Deploy stuff —— 部署；♻️Refactor code —— 重构；🚨Fix compiler / linter warnings —— 修复编译或 Lint 告警；🧪Add a failing test —— 添加失败用例（TDD）。
使用命令行客户端 gitmoji-cli
为了从命令行直接使用 Gitmoji，官方提供了交互式客户端gitmoji-cli，它可以帮你把 Emoji 选择、格式化提交信息的过程变成引导式交互。全局安装命令（README 原文）：
npm i -g gitmoji-cli安装后即可在终端中通过交互界面挑选 Emoji 并组合出符合<intention> [scope?][:?] <message>格式的提交信息，避免手工记忆 Emoji 与意图的对应关系，也减少输入错误。需要说明的是，gitmoji-cli是独立于本仓库发布维护的配套项目，其完整子命令与配置项以其自身文档为准。
以 npm 包形式消费 Emoji 数据：gitmojis
Gitmoji 约定中的全部 Emoji 已被打包成一个 Node 模块发布，方便作为依赖引入到自己的工具链中。仓库内对应包的说明见 packages/gitmojis/README.md。
安装
npm i gitmojis基本用法（ES Module）
import { gitmojis } from 'gitmojis' console.log(gitmojis)输出为对象数组，每个元素形如：
[ { emoji: '🎨', entity: '🎨', code: ':art:', description: 'Improve structure / format of the code.', name: 'art', semver: null }, { emoji: '⚡️', entity: '⚡', code: ':zap:', description: 'Improve performance.', name: 'zap', semver: null }, // ... ]字段语义与 TypeScript 类型
每个 Gitmoji 条目包含 6 个字段，其类型定义见 packages/gitmojis/src/index.d.ts：
| 字段 | 类型 | 说明 | 示例 |
|---|---|---|---|
emoji | string | Emoji 的 Unicode 字符 | '🎨'、'⚡️' |
entity | `&#${string};` | 十六进制或十进制的 HTML 实体 | '🎨'、'🚑' |
description | string | 该 Emoji 的使用场景说明 | 'Improve structure / format of the code.' |
name | string | 语义化名称（kebab-case） | 'art'、'white-check-mark' |
semver | 'patch' \| 'minor' \| 'major' \| null | 关联的语义化版本影响范围，未指定时为null | 'patch'、'minor'、null |
code | `:${string}:` | 以短码形式格式化的字符 | ':art:'、':zap:' |
其中semver字段是 Gitmoji 与语义化版本（SemVer）打通的关键：例如✨（新功能）标记为minor、💥（破坏性变更）标记为major，而⚡️、🐛、🚑️等大量条目标记为patch，部分条目录为null（不涉及版本影响）。从数据结构可以推断，semver的设计意图是支持基于提交信息自动推断版本号变更级别的工具。
包入口与模块格式
gitmojis的入口实现见 packages/gitmojis/src/index.js：
import gitmojisJson from './gitmojis.json' assert { type: 'json' } export { default as schema } from './schema.json' assert { type: 'json' } export const gitmojis = gitmojisJson.gitmojis也就是说，包对外导出两个成员：
gitmojis：直接取自gitmojis.json中的gitmojis数组；schema：对应的 JSON Schema，可用于运行时校验数据合法性。
在 packages/gitmojis/package.json 中，包被声明为"type": "module"，并通过exports字段同时提供 ESM 与 CJS 两个入口（dist/index.mjs/dist/index.cjs），types指向dist/index.d.ts，因此支持import与require两种引入方式，并天然带 TypeScript 类型提示。构建工具链采用unbuild（"build": "unbuild"），开发时用nodemon监听src目录自动重建。
数据合法性的双重保障
Gitmoji 数据不是手写即完事，而是有 schema 约束与自动化校验：
- JSON Schema：见 packages/gitmojis/src/schema.json，采用 JSON Schema draft 2020-12。它要求顶层对象必须有
gitmojis数组，且每个条目必须包含emoji、entity、code、description、name、semver六个字段，其中semver只能是"major"、"minor"、"patch"或null；数组本身还要求minItems: 1与uniqueItems: true，从结构上保证列表非空且不重复。 - CI 校验脚本：
package.json中提供了lint:json与lint命令，用ajv-cli依据 schema 校验数据文件：
# 校验 gitmojis.json 是否符合 schema.json pnpm run lint:json # 在 JSON 校验基础上再执行 prettier 格式检查 pnpm run lint这意味着任何新增或修改的 Emoji 条目，都必须同时通过 schema 语义校验与 prettier 格式检查才能合入。
通过 HTTP API 消费：curl 一行获取
如果你不希望以 npm 依赖的方式引入，也可以直接通过 HTTP API 消费同一份数据（README 原文）：
curl https://gitmoji.dev/api/gitmojis该接口返回与 npm 包一致的{ "gitmojis": [...] }JSON 结构。从仓库实现看，网站侧通过 packages/website/scripts/generate-api.js 在构建期静态生成该 API 的 JSON 文件：
const { gitmojis } = require('gitmojis') const fs = require('fs') const path = require('path') const outputDir = path.join(__dirname, '../public/api/gitmojis') fs.mkdirSync(outputDir, { recursive: true }) fs.writeFileSync( path.join(outputDir, 'index.json'), JSON.stringify({ gitmojis }, null, 2) )即：构建时从gitmojis包读取数据，落盘到public/api/gitmojis/index.json，由静态站点托管。这样 API 与 npm 包共享同一数据源，保证多入口消费的一致性。此外，数据文件中还声明了"$schema": "https://gitmoji.dev/api/gitmojis/schema"，让编辑器也可以直接按 schema 校验该 JSON。
在网站中集成：Gitmoji 展示与搜索
本仓库的网站包（packages/website）围绕这份 JSON 数据构建了完整的展示与搜索体验：
GitmojiList组件（packages/website/src/components/GitmojiList/index.tsx）负责渲染全部 Gitmoji 列表；emojiColorsMap.ts（packages/website/src/components/GitmojiList/emojiColorsMap.ts）为不同 Emoji 提供展示色；SearchParamsSync.tsx（packages/website/src/components/GitmojiList/SearchParamsSync.tsx）将搜索/过滤条件同步到 URL 查询参数，便于分享与书签；- 配套的单元测试覆盖了列表渲染与交互逻辑（如 packages/website/src/components/GitmojiList/tests/gitmojiList.spec.tsx）。
如果你要在自己的项目里做类似的 Emoji 展示页，可以直接以gitmojis包的gitmojis数组为数据源，配合description做搜索匹配、用code显示短码、用semver做版本影响标识。
仓库工程结构速览
本仓库采用 pnpm + Turbo 的 monorepo 组织方式（见 package.json、pnpm-workspace.yaml 与 turbo.json），包含两个工作区包：
packages/gitmojis：数据包本体，产出gitmojis与schema两个导出；packages/website：Next.js 展示网站，含页面、组件、测试与静态 API 生成脚本。
根目录package.json要求 Node 22 与 pnpm >= 8，并提供"dev": "pnpm turbo --parallel dev"一键并行启动所有包的开发模式。数据从 packages/gitmojis/src/gitmojis.json 单一事实源流出，npm 包、HTTP API、网站展示三条消费链路共用这一份数据，这是整个项目保持「一处维护、处处一致」的关键设计。
为项目添加 Gitmoji 徽章
如果你正在自己的项目中使用 Gitmoji，README 提供了官方的徽章代码，可以直接放在自己项目的 README 顶部（徽章指向 gitmoji 官网）：
<a href="https://gitmoji.dev"> <img src="https://img.shields.io/badge/gitmoji-%20😜%20😍-FFDD67.svg?style=flat-square" alt="Gitmoji" /> </a>该徽章使用 shields.io 动态生成，向读者传达「本项目遵循 Gitmoji 提交约定」这一信息。
贡献与许可
Gitmoji 欢迎社区参与：贡献指南、新增 Emoji 的流程（先开 issue 讨论、再提交 Pull Request 并附带数据更新）都定义在仓库的.github/CONTRIBUTING.md中，新增 Emoji 时必须同时更新 packages/gitmojis/src/gitmojis.json，并通过pnpm run lint的 schema 与格式校验。仓库代码以 MIT 协议开源发布。
小结
围绕一份结构化 JSON 数据，Gitmoji 生态打通了「约定 → 数据 → 工具 → 消费」的完整链路：<intention> [scope?][:?] <message>提供了统一的提交书写范式；gitmoji-cli解决了命令行下的交互式使用；gitmojisnpm 包与https://gitmoji.dev/api/gitmojisHTTP API 让任何语言、任何工具都能以结构化方式消费全部 Emoji 元数据；JSON Schema 与 ajv 校验保证了数据在合入前始终合法。无论你是想在团队内推行统一的提交规范，还是想基于 Emoji 数据构建自己的提交辅助或分析工具，都可以直接从本仓库的 gitmojis.json 与 schema.json 出发快速落地。
- 开发工具
【免费下载链接】gitmoji
An emoji guide for your commit messages. 😜
相关推荐
Penpot 仓库 Git 提交规范全解：Commit Message 格式、emoji 类型与 AI 辅助署名指南
Penpot 仓库 Git 提交规范全解：Commit Message 格式、emoji 类型与 AI 辅助署名指南 导读：本文以 Penpot 开源仓库的贡献
前端设计系统图形学协同办公Lean 4 仓库 Git 提交规范：从 Commit Message 到自动化 Changelog 的工程实践
Lean 4 仓库 Git 提交规范：从 Commit Message 到自动化 Changelog 的工程实践 Lean 4（ leanprover/lean
编程语言编译器形式化验证语言运行时标准库oh-my-posh 提交规范实战：基于 Conventional Commits 生成标准化的 commit message
oh my posh 提交规范实战：基于 Conventional Commits 生成标准化的 commit message 本指南以 oh my posh
CLI开发工具
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
