Markdown Emoji 表情符号：语法、速查表与平台兼容性指南

写 Markdown 文档的时候，加个合适的 emoji 表情能让内容更有表现力——README 里用 🚀 表示"快速开始"，提交信息里用 ✅ 表示任务完成，笔记里用 ⚠️ 标记注意事项。

但问题来了：markdown emoji 到底怎么输入？为什么我在 GitHub 上写 :smile: 能变成 😄，换到别的平台却原样显示？这篇文章把 markdown emoji 的几种用法、常用速查表、以及平台兼容性一次性讲清楚。无论你是在 GitHub 写 README、在博客平台发文章，还是用 VS Code 写笔记，都能找到适合你的方法。

Markdown 中的 Emoji：三种输入方法

在 Markdown 里用 emoji，说到底就三种路子：直接复制粘贴 emoji 字符、用 shortcode 简码语法、用 Unicode 编码。三种方法各有适用场景，下面逐一说明。

方法一：直接复制粘贴（最简单，兼容性最广）

最直接的方式就是把 emoji 当普通文字，直接粘贴到 Markdown 文件里：

今天心情不错 😄，分享一下学习心得！

TODO 列表：
- ✅ 完成 Markdown 基础语法
- 🔄 学习 markdown emoji 表情符号
- ⭐ 写一篇教程

渲染效果：

今天心情不错 😄，分享一下学习心得！

TODO 列表：

• ✅ 完成 Markdown 基础语法
• 🔄 学习 markdown emoji 表情符号
• ⭐ 写一篇教程

怎么快速输入 emoji？

• macOS：按 Control + Command + Space，调出 emoji 选择面板
• Windows 10/11：按 Win + .（Windows 键 + 句号键），打开 emoji 面板
• 手机：直接用系统自带键盘的 emoji 页面
• 在线复制：访问 Emojipedia 或 emoji-all，搜索后复制

说实话，我日常写文档 80% 的场景用的就是这种方式——简单粗暴，在哪都能用。因为 emoji 本质上就是 Unicode 字符，只要你的 Markdown 渲染器能处理 UTF-8 文本（基本上所有现代渲染器都支持），直接粘贴就完事了。

不过这个方法也有个不太方便的地方：如果你经常需要输入同一些 emoji，每次都要调出面板找半天，效率不太高。这时候 shortcode 语法就派上用场了。

方法二：Shortcode 简码语法（GitHub 等平台专属）

很多平台支持用 :名称: 的格式插入 emoji，这种写法叫 emoji shortcode（简码）。比如：

欢迎使用 :rocket: Markdown Emoji :heart_eyes:

常用标记：
:white_check_mark: 已完成
:x: 未完成
:warning: 注意事项
:bulb: 小提示
:star: 推荐

在 GitHub 上渲染后会变成：

欢迎使用 🚀 Markdown Emoji 😍

常用标记： ✅ 已完成 ❌ 未完成 ⚠️ 注意事项 💡 小提示 ⭐ 推荐

shortcode 的好处是：纯文本可读性好。看源码时 :white_check_mark: 比 ✅ 更容易理解意图，在 commit message 和 issue 评论里用起来很方便。

但 shortcode 最大的问题是平台依赖。GitHub 支持的 shortcode 列表来自 gemoji 库，不同平台支持的列表不完全一样。我在 CSDN 上测试 :smile: 可以正常渲染，但在简书和掘金上就原样显示文本——这一点后面兼容性部分会详细说。

顺便提一句，如果你用 VS Code 写 Markdown，可以装一个 Markdown Emoji 插件，它能在预览中解析 shortcode，这样写的时候就能看到实际效果。

方法三：Unicode 编码（兼容性最保险）

每种 emoji 在 Unicode 标准中都有一个唯一的编码。你可以用 HTML 实体的方式插入：

笑脸：😀
红心：❤
火箭：🚀
对号：✅

渲染效果：😀 ❤️ 🚀 ✅

这种方式的优势是：所有支持 HTML 的 Markdown 渲染器都能正确处理。不过说实话，日常写文档谁也记不住这些编码，实际用的场景比较少。主要在一些不支持 shortcode、又不太方便直接粘贴的特殊环境里有用武之地。

参考：Unicode Consortium 维护着完整的 emoji 编码列表，可在 Unicode Full Emoji List 查询。

三种方法对比

我的建议是：日常写东西直接粘贴就行；写 commit message 或 issue 用 shortcode 更规范；Unicode 编码知道有这个方法就好，真碰到需要的时候再查。

Markdown Emoji 常用速查表

下面整理了一份常用的 emoji shortcode 速查表。写文档最常用的基本都在这里了，完整列表可以参考 GitHub Emoji Cheat Sheet 或 emoji-cheat-sheet.com。

表情与手势

标记与符号

项目管理常用

在 commit message 中使用 emoji

很多团队喜欢在 commit message 前加 emoji 来标明提交类型，这是一种常见的 Conventional Commits 变体：

✨ feat: 新增 markdown emoji 速查功能
🐛 fix: 修复 emoji shortcode 渲染异常
📝 docs: 更新 emoji 使用文档
🎨 style: 调整 emoji 对齐方式
♻️ refactor: 重构 emoji 解析逻辑
🧪 test: 添加 emoji 渲染测试用例
🚀 release: v2.0.0 正式发布

这种方式在 Markdown All in One 项目的贡献规范中就有使用，源码可读性比纯文字好很多。

平台兼容性详解

前面提到 shortcode 不是所有平台都支持，这里做个详细的对比。这个表格是我结合 Markdown Guide 官方文档、GitHub 帮助文档以及实际测试整理的：

为什么 shortcode 在某些平台不生效？

这是因为 shortcode 不是 Markdown 核心规范的一部分。John Gruber 在 2004 年设计 Markdown 时根本没有考虑 emoji（那会儿 emoji 还没走出日本）。: 包裹的写法是 GitHub 在 GFM（GitHub Flavored Markdown）中引入的扩展语法，后来被 GitLab 等平台跟进。

所以如果你在掘金或简书写 :smile:，渲染器不认识这个语法，就会原样显示为 :smile: 文本。

静态站点生成器怎么开启 emoji 支持

如果你用静态站点生成器（如 Hugo、Jekyll），shortcode 默认可能不生效，需要额外配置：

Hugo：在配置文件中开启 emoji 处理器：

enableEmoji: true

Jekyll：安装 jemoji 插件：

# Gemfile
gem 'jemoji'

# _config.yml
plugins:
  - jemoji

Hexo：安装 hexo-filter-github-emojis 插件：

npm install hexo-filter-github-emojis --save

开发者集成：在自己的 Markdown 解析器中支持 Emoji

如果你在开发一个 Markdown 相关的应用，需要让解析器支持 emoji，这里介绍几个常用的方案。

markdown-it-emoji（Node.js）

markdown-it 是最流行的 Markdown 解析器之一，它有专门的 emoji 插件：

import markdownit from 'markdown-it';
import { full as emoji } from 'markdown-it-emoji';

const md = markdownit();
md.use(emoji);

// 渲染 :smile: 为 😄
const result = md.render('Hello :smile:');
// 输出: <p>Hello 😄</p>

插件提供三种配置模式：

• full：包含所有 Unicode emoji（约 1800+）
• light：只包含常用 emoji（约 300 个）
• bare：不预置任何 emoji 数据，需要你自己提供映射表

参考：markdown-it-emoji npm 文档

Python-Markdown + PyMdown Extensions

Python 用户可以用 PyMdown Extensions 的 emoji 扩展：

import markdown
from pymdownx import emoji

md = markdown.Markdown(extensions=['pymdownx.emoji'])
result = md.convert('Hello :smile:')

一个需要注意的坑：数据库存储

有一次我帮同事排查一个问题，他在 MySQL 数据库里存带 emoji 的文章内容时报错了。原因很简单：MySQL 的 utf8 字符集最多支持 3 字节的字符，而大多数 emoji 需要 4 字节。

解决方法是把表的字符集改成 utf8mb4：

ALTER TABLE articles CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

这个问题在 PostgreSQL 和 SQLite 中不存在，它们默认就支持完整的 Unicode。但如果你用 MySQL，这一点一定要提前注意，不然存到 emoji 的时候才发现就晚了。

常见问题

为什么我的 emoji 显示为方框或问号？

这通常是因为：

1. 字体不支持：系统的字体缺少对应的 emoji 字形。Windows 7 及更早版本对 emoji 的支持很差
2. 编码问题：文件没有保存为 UTF-8 编码
3. 数据库字符集：如上面提到的，MySQL 需要使用 utf8mb4

Markdown emoji shortcode 有没有完整的列表？

有的。最权威的参考是：

• GitHub 官方支持的 emoji 列表
• Unicode Full Emoji List
• Emojipedia — 按关键词搜索最方便

怎么在 Markdown 表格 中使用 emoji？

直接用就行，emoji 在表格中和其他文字没有区别：

| 状态 | 任务 |
|------|------|
| ✅ | 完成 Markdown 表格语法 |
| 🔄 | 学习 markdown emoji |
| ⏳ | 掌握 [Markdown 链接](/markdown/link语法/) |

Shortcode 和直接粘贴哪个更好？

看场景。写 Markdown 代码块 旁边的注释或个人笔记，直接粘贴效率更高；写 commit message、issue、PR 描述这些需要长期维护的团队内容，shortcode 的可读性优势更明显。在不确定平台支持的情况下，直接粘贴是最安全的选择。

参考来源

• Markdown Guide - Extended Syntax — 确认 emoji 不属于 Markdown 核心规范
• GitHub gemoji — GitHub emoji shortcode 映射库
• Unicode Full Emoji List — Unicode 官方 emoji 编码列表
• markdown-it-emoji — markdown-it emoji 插件文档
• PyMdown Extensions — Python Markdown emoji 扩展
• Material for MkDocs — MkDocs emoji 配置文档
• Stack Exchange - Support Emoji in Markdown — 社区对 shortcode 支持的讨论

emoji 语法本身没几行，但坑都在细节里——shortcode 在哪些平台能用、数据库怎么存、静态站点怎么配置，这些才是实际写东西时真正会碰到的问题。希望这份指南能帮你少走些弯路。如果你对 Markdown 注释 或其他 Markdown 语法也有疑问，可以看看这个系列的其他文章。