写 Markdown 这些年我见过最可惜的一种情况内容写得很扎实但通篇都是灰扑扑的纯文本读者扫两眼就跳走了。我自己最开始也把 Emoji 当花架子直到在某项目的 README 里用了一组状态标记住在隔壁工位的同事专门跑过来问是怎么做出来的我才意识到——Emoji 在 Markdown 里从来不是装饰它就是信息本身。这篇文章想解决三个问题第一Markdown 里到底有哪几种插入 Emoji 的方式各自的边界在哪儿第二上千个表情怎么选不同用途该用哪一类第三在不同平台GitHub、Obsidian、Typora、静态博客、甚至 Markdown 转 Word上为什么同一个表情时灵时不灵遇到方框、乱码、丢失该怎么处理。无论你是写技术文档、维护 README还是在 Obsidian 里记笔记这篇都值得存一份。1. 为什么写 Markdown 一定要会点 Emoji1.1 先弄清楚你用的到底是哪种 Markdown很多人以为 Markdown 只有一种其实不是。用 Emoji 之前先得知道自己面对的是哪个方言。最基础的 Markdown 标准语法里根本没有 Emoji 这个概念它只定义了标题、列表、引用、代码块这些但 GitHub 在它的 Flavored MarkdownGFM里扩展了 Emoji 短代码于是:smile:这种写法才能在 GitHub 上活过来。这就是为什么你会遇到一个经典现象同样的文档在 GitHub 上看是笑脸复制到某个本地编辑器里就变成一行奇怪的:smile:字符串。不是编辑器坏了是它没有实现 GitHub 那套扩展。我一般把 Markdown 分成四类标准 CommonMark、GitHub 风格 GFM、编辑器特有方言比如 Obsidian 的 callout、以及博客系统自带的渲染扩展。插入 Emoji 的所有坑本质上都来自这四类之间的差异。有了这个概念后面所有问题都好解释短代码能不能渲染取决于渲染器Unicode 表情能不能显示取决于操作系统和字体转换到 Word 会不会丢取决于转换工具。1.2 Emoji 能给文章带来什么实际收益先说结论Emoji 最大的价值是让扫读效率变高。现在很少有人逐字读文档都是先扫标题、列表、状态标记判断这段值不值得看。Emoji 相当于给这些关键位置提前标了荧光笔。举个例子同样是更新日志纯文本版本是这样的- 修复登录超时问题 - 增加导出功能 - 已知问题移动端样式错乱加上状态标记之后- [修复] 登录超时问题 - [新增] 数据导出功能 - [注意] 移动端样式错乱下个版本处理看起来清楚了一点但还是不够醒目。如果你换成✅ 修复登录超时、✨ 新增数据导出、⚠️ 移动端样式错乱整个 changelog 的可读性会明显上一个台阶。GitHub 上大量高星项目的 README 都这么做不是因为他们闲是因为这真的能降低读者的理解成本。另外还有一层情绪价值。写技术文章的人经常忽略读者感受——通篇冷冰冰的文字读者很难判断作者的态度。一个 代表着这里我想了一下一个 代表下面是我的思路语气自然就出来了。Markdown 本身是纯文本Emoji 是它少数能表达语气的工具不用白不用。2. 在 Markdown 里插入 Emoji 的四种姿势2.1 姿势一GitHub 短代码最省事但看平台GitHub 短代码就是:冒号中间写英文名:这种格式。比如:smile:显示为 :rocket:显示为 。这套方案最大的优点是纯文本可读性极好哪怕不渲染你看到:warning:也能猜出它要表达警告。而且 GitHub 官方维护了上千个代码别名不用记 Unicode 码点。日常最常用的一批我给个对照表短代码显示效果短代码显示效果:smile::rocket::wink::memo::laughing::bulb::heart:❤️:warning:⚠️:1::x:❌:-1::white_check_mark:✅但短代码有两个硬边界。一是离开 GitHub 生态GitHub、GitLab、部分支持 GFM 的站点就不渲染很多本地编辑器会把它原样输出成文本。二是它只在普通正文和列表里生效放在代码块里就彻底失效——你在反引号包裹的代码块里写:smile:它永远只会显示字面字符串这是设计如此不是 bug。所以我的经验是短代码适合确定会发到 GitHub/GitLab 的文档用本地笔记和跨平台内容优先考虑第二种方式。2.2 姿势二直接粘贴 Unicode 表情通用性最强直接把 或者 这个字符粘贴进 Markdown 源文件这是我认为最稳妥的方案。它的本质是插入一个 Unicode 字符跟插入一个 中 字没有区别任何渲染器、任何编辑器、任何博客系统只要能正常显示中文就一定能正常显示这个字符。代价是源文件的纯文本可读性下降了。你打开源文件看到的是 而不是:smile:在代码评审、diff 对比的时候会稍微影响阅读。另外Unicode 标准每年更新同一个表情在不同年代的操作系统上可能长得不一样甚至新版系统引入的某些表情在旧版系统上直接显示成方框。我自己常用的策略是这样如果文档要长期维护、多平台分发比如一篇要同步到博客和公众号的文章全部用 Unicode 表情如果是 GitHub 上的仓库文档用短代码如果是 Obsidian 这类本地笔记两种都行但我更建议 Unicode因为笔记经常要导出成 PDF 或 Word短代码在导出链路里很容易变成一串英文。2.3 姿势三用系统输入法就地插入Windows 上用Win .会弹出 Emoji 选择面板macOS 上用Ctrl Cmd 空格移动端输入法里长按表情按钮也能调出来。这个操作不需要离开编辑器是我日常最常用的方式尤其是改文档时补一两个表情。有人问这和直接粘贴有什么区别本质没区别输入法也是帮你插入 Unicode 字符。但它有筛选和搜索功能比如在 Windows 面板里输入 smile 能把所有口部表情列出来找起来比翻收藏列表快。唯一要注意的是部分输入法会在粘贴时带出零宽空格等不可见字符后文问题排查部分我会专门讲。2.4 姿势四HTML 实体备胎方案Markdown 允许内嵌 HTML所以你可以写#128640;来表示 。这套方案在实际写作里几乎没人用因为可读性极差而且不是所有平台的安全过滤都放行 HTML。我提它纯粹是为了让你在遇到老旧的渲染环境时有个兜底——如果你在某个发布系统里既不能用短代码又不能直接粘贴字符有些后台会转义或过滤HTML 实体是最后的选择。日常写作忘掉它就好。3. 上千个表情的速查图谱按用途分好类3.1 文档状态标记类最推荐我写东西最常碰到的需求不是表达心情而是给内容打状态标签。一套稳定的状态标记能让文档从没头没尾变成一目了然。下面这组我几乎每篇文档都用用途Unicode短代码已完成✅:white_check_mark:未完成/待办☐ 或 ⬜:ballot_box_with_check:反义失败/错误❌:x:警告/注意⚠️:warning:施工中/开发中:construction:新功能/亮点✨:sparkles:重要/必读:pushpin:想法/灵感:bulb:关键提示:key:禁止/不可做:no_entry_sign:这里有个容易混淆的点很多人分不清 ✅ 和 ☑️。我的约定是 ✅ 表示这件事已经做完了☑️ 表示这是个可勾选的状态项配合 GFM 的任务列表- [x]使用。如果你在 README 的功能列表里想表达支持、不支持、计划中三个状态用 ✅ / ❌ / 组合是最直观的读者不用读任何说明就能看懂。3.2 表情面孔与手势这组主要用于正文表达语气我按使用频率排了序。高频区 正常开心、 笑哭、 微笑、 尴尬汗、 思考、 赞同、 感谢、 庆祝。中频区 眨眼、 喜欢、 大哭、、 酷、 震惊、 困、 摊手表示我也没办法。写技术内容时我对这类表情有两条规矩第一一篇 3000 字的文章面孔类表情不超过 5 个否则显得轻浮第二不要在 bug 描述、事故复盘这类严肃场景里用大笑表情读者会觉得你在嘲笑他们。表情传递的态度比文字更直接控制数量比追求丰富重要得多。3.3 物品工具与符号标记这类是技术文档里的主力比面孔表情有用得多。我用得最多的是这组用途Unicode短代码文件/文档:page_facing_up:文件夹:file_folder:链接:link:数据库️:file_cabinet:近义搜索:mag:代码 / ⌨️:computer:/:keyboard:配置/设置⚙️:gear:测试:test_tube:版本/发布️:label:时间/日历:calendar:趋势/上升:chart_with_upwards_trend:性能/极速⚡:zap:比如文档里写本项目使用 PostgreSQL 存储数据 ️API 层通过 Redis 做缓存 ⚡读者一眼就能定位信息块。这里有个增效做法给文档里的每种资源固定一种图标形成你自己的视觉字典。我的开源项目 README 约定是数据库用 ️接口用 命令行工具用 ⌨️环境变量用 ⚙️这样全仓库文档风格统一维护起来也省心。3.4 自然、动物与食物这类在正经技术文档里用得少但也不是没用。特性演示、示例代码、个人博客里它们能制造记忆点。比如用 但让我意外地容易区分 iOS/Android 两个分支的表格用 表示初期版本用 表示发布都属于恰到好处。我必须提醒一句动物和食物表情在跨平台渲染时差异最大。同一个 在 Apple 平台上长得非常可爱在 Windows 上可能完全认不出来是什么。如果内容要跨平台发布这类表情能不用就不用或者选那些形态稳定的比如 ☀️、、️ 这些自然现象类相对统一。3.5 数字序号与方向箭头写步骤说明和章节导航时这两类简直是救星。数字可以用 1️⃣ 2️⃣ 3️⃣ 这种带圈数字在操作步骤场景里比纯文本的 1. 醒目很多。方向箭头 ⬆️ ⬇️ ⬅️ ➡️ 配合 ↪️ 常用于表格里表示增减变化比如版本对比表格里v2.0 ⬆️ 速度提升 30% 比 v2.0 速度提升 30% 直观得多。需要注意带圈数字的表情其实是一组组合字符数字 变体选择符 组合围圈符。在某些老旧的渲染器上会拆成三个字符显示变成 1️⃣ 碎掉。稳妥做法是直接用 Unicode 里的圈数字字符 ① ② ③它们显示更稳定只是视觉上没那么立体。4. 不同渲染平台上的真实表现4.1 GitHub / GitLab / 国内代码托管平台GitHub 对 Emoji 的支持是最完整的短代码天然可用表情列表超过上千个而且它会跟随你的操作系统表情字体渲染。GitLab 基本兼容 GitHub 的短代码但表情数量和个别别名有差异。国内几家代码托管平台对 GFM 的支持参差不齐有的只渲染部分短代码我在这种平台上的做法是全部改成 Unicode 表情宁可牺牲源文件可读性也不能让文档在读者面前显示成一堆:xxx:。还有一个容易踩的坑GitHub 的短代码在 Markdown 注释里也会尝试渲染在 issue 模板、PR 模板里写!-- :smile: --并不会显示注释里那个表情。注释里的内容会被当作注释丢弃但你要是把短代码写在注释外、又放在代码块里它就会原样显示。写模板时要注意。4.2 Obsidian、Typora、VS Code 等本地编辑器本地编辑器的情况比较分裂。Typora 对 Unicode 表情支持很好所见即所得但:smile:短代码默认不渲染部分版本支持通过设置开启。Obsidian 也是同样的倾向Unicode 表情完美显示短代码需要用社区插件比如 Emoji Shortcodes才能补全提示和渲染。VS Code 的内置 Markdown 预览比较特殊它默认就能把常见短代码渲染成表情而且官方市场的 Markdown Preview Enhanced 插件也可以配置支持。三个编辑器的共同点是Unicode 表情都是没问题的短代码则各有各的脾气。所以我的建议很明确本地笔记和写作全部用 Unicode。尤其是 Obsidian 用户你的笔记经常要导出分享短代码导出后大概率变成火星文。4.3 Hexo、Hugo、VuePress 等静态博客静态博客能不能用 Emoji取决于两层Markdown 渲染器和主题样式。Hexo 默认的 marked 渲染器对:smile:短代码不处理需要安装 hexo-filter-github-emojis 这类插件Hugo 则内置了 shortcode 支持GitHub 风格表情可以直接用但要在配置里开启。VuePress/VitePress 这类基于 Node 的工具链一般通过 markdown-it 插件扩展短代码。如果你用的静态博客不支持短代码最省事的方案还是那句老话直接粘贴 Unicode 表情。我维护过两个博客一个 Hexo 一个 Hugo全部用 Unicode省去了所有插件兼容性问题换主题、换渲染器都不用回头改文章。静态博客还有一个手机端渲染问题部分主题的字体栈没配表情字体电脑上正常手机上变成方框通常需要在 CSS 里加上 system-ui、Apple Color Emoji、Segoe UI Emoji 这些字体。4.4 微信公众号、知乎、语雀这类富文本场景这些平台本质上不是 Markdown 原生渲染而是通过各种编辑器把 Markdown 转成富文本再粘贴发布。你的 Emoji 能不能保留取决于转换——粘贴这条链路上的每一步。经验是Unicode 表情基本都能存活短代码大概率死掉。微信编辑器对 Emoji 的支持还行但来源不明的一批字符比如部分特殊符号和旗帜类表情会被过滤。另外提醒一个很多人没注意的问题微信公众平台有自己的一套 Emoji 字符集某些微信端能显示的表情在电脑浏览器里看是方框反过来也一样。如果文章要适配多端阅读尽量选最基础、最通用的那些表情。我在公众号发技术文章时只用一组非常保守的字符✅ ❌ ⚠️ 再花哨的一律不用。5. 实战技巧把 Emoji 用出秩序感5.1 先定一套文档表情字典使用 Emoji 最忌讳的是随意。今天用 ✅ 表示完成明天用 后天用 读者根本建立不起映射关系。我的做法是给每个项目建一个表情字典写在项目根目录的 CONTRIBUTING 或者 README 开头状态标记 ✅ 已完成 开发中 ❌ 未实现 ⚠️ 注意/限制 文档约定 使用说明 相关链接 设计思路 已知问题这套字典不仅自己写文档时用也方便协作者遵守。我们团队现在 PR 描述、issue 标题都用这套约定筛选信息的速度快了很多。如果你的文档是给自己看的字典不用写下来但心里要有数否则写完一个月自己都不认识自己的表情。5.2 任务清单和高频组合用法GFM 的任务列表- [ ]配合 Emoji 是个很实用的组合。我习惯这样记录每日工作- [x] 完成登录模块重构 ✅ - [x] 补充 API 文档 - [ ] 排查移动端样式问题 - [ ] 周五前发 v2.3 版本 注意我把表情放在行尾而不是行首。因为 Markdown 任务列表的[x]本身就是状态标识行首再加表情会造成视觉冗余。行尾的表情承担的是额外说明功能完成的事项说明成果类型未完成的事项说明当前状态。这个用法在 Obsidian 的看板插件里也很顺手配合查询语法一眼就能筛出哪些任务是施工中。标题里用 Emoji 要克制。我的原则是一级标题不用二级标题偶尔用于区分内容分区比如安装 配置 ⚙️常见问题 ❓三级及以下标题全部不用。一旦每个标题都带表情页面会显得非常吵闹扫读时反而抓不到重点。5.3 表格里用 Emoji 的排版细节Markdown 表格是最容易暴露 Emoji 问题的场景。主要原因是 Emoji 的显示宽度不固定有的占一个字符宽度如 ⚡有的占两个如 导致表格列的视觉宽度参差不齐源代码里的对齐也不好看。我总结了三条经验。第一尽量把 Emoji 放在单元格靠后的位置不要放在最开头因为表格里最左侧的对齐线读者看得最认真表情会干扰对齐判断。第二列标题别用 Emoji保持列名纯粹列内容里再放。第三如果同一列里既有中文又有英文又有 Emoji建议把该列设为左对齐并给 Emoji 后面手动加一个空格观感会更统一。还有一个隐藏坑复制表格到 Excel 时Emoji 字符有时会影响 CSV 的字段分隔尤其当你在表格里用了逗号或者制表符时。这个问题在下一节详细说。6. 常见问题与排查实录6.1 显示成方框 / 豆腐块怎么办方框俗称豆腐块是最常见的翻车现场原因几乎只有一个当前系统或应用缺少对应的表情字体。Windows 7 及更老系统不支持彩色 EmojiLinux 发行版默认没装 Noto Color Emoji 的也很多有些远程服务器上的浏览器因为没字体直接渲染成空框。排查步骤我给个清单先在手机上看同一份文件如果手机正常、电脑异常基本确定是电脑字体问题然后升级操作系统或安装对应字体——Windows 更新、macOS 保持最新、Linux 安装 fonts-noto-color-emoji 包如果系统是最新的还显示方框大概率是编辑器或渲染器的字体设置问题去设置里把 UI 字体和代码字体改成系统默认即可。我处理过一次 VS Code 里预览正常、但导出 PDF 全是方框的情况最后发现是导出工具用的字体里没有表情换导出主题就好了。6.2 短代码不渲染显示成 :smile: 文本这个前面已经解释过根本原因是渲染器不支持 GFM 的 Emoji 扩展。排查方法也简单看文档具体在哪个平台显示异常如果是在 GitHub 之外的地方大概率不是 bug是能力边界。但有一个反直觉的情况GitHub 上部分短代码在特定栏目比如 Actions 的日志、部分讨论区不渲染因为那里的 Markdown 渲染器被精简过。如果在非 GitHub 平台必须用短代码两个替代方案查目标平台的文档是否支持短代码扩展比如 Hugo 开启 enableEmoji或者干脆全文替换成 Unicode。我这里有个快捷方法写文档时先用短代码发布前用一个正则把:[a-zA-Z0-9_-]:匹配出来对照映射表替换成 Unicode 字符。这是很多博客作者的常规操作比手工逐个改快得多。6.3 转 Word / PDF 后表情丢失或变黑白Markdown 转 Word 最常见的是用 pandoc或者先转 HTML 再复制到 Word。表情丢失或者变成黑白符号核心原因是目标格式的表情字体映射不一致且部分转换器会丢弃颜色信息。我的处理方案分两种。要一份能编辑的 Word先转 HTML在浏览器打开再用 CtrlA 全选复制到 Word这样表情是作为真实字符进去的大概率保留要一份 PDF用编辑器自带的导出功能Typora、Obsidian 都行而不是走 pandoc 直转因为编辑器的打印链路通常配置好了表情字体。如果一定要 pandoc建议用--pdf-enginexelatex并配合字体配置但说实话对普通用户成本偏高不划算。6.4 表格复制到 Excel 乱码 / 对齐错乱Markdown 表格复制到 Excel 经常出现两个问题中文乱码、列错位。中文乱码的根源是编码——Markdown 文件是 UTF-8 编码系统剪贴板转成其他编码时丢字符。列错位则和复制方式有关直接全选网页上的表格复制Excel 可能把 Markdown 的管道符|也当成内容粘进去了。想减少痛苦我建议这样如果目标只是 Excel 数据别用 Markdown 表格直接在 Markdown 里写 CSV 格式用 Excel 的数据 - 自文本/CSV导入选择 UTF-8 编码一次搞定。Markdown 表格从来不是用来做数据交换的它是给人读的不是给 Excel 读的。至于 Markdown 表格转 Excel 这个需求现在不少在线转换工具能直接处理输出一个 UTF-8 with BOM 的 CSVExcel 打开基本无压力。6.5 文件名和目录里千万别用 Emoji我在项目里见过有同事给图片命名成截图.png然后 Markdown 里写。本地编辑器能正常显示一推上 Git 就出问题——不同平台的 Git 对非 ASCII 文件名的处理不同有的仓库 clone 下来文件名正常有的直接变成一串百分号编码。更麻烦的是部分静态博客的 URL 生成逻辑会把 Emoji 转成百分号编码导致链接很长且缓存困难。我的原则是文件名、目录名、URL 路径、代码标识符里一律不用 Emoji。表情只存在于文档内容里用来标记和装饰不参与任何机器要解析的信息。这条规则帮我避免过至少三次本地好好的线上就崩了的经历。6.6 一个实用的 10 分钟自查清单最后给你一份我每次发布前必过的自查清单照着做能避开大部分坑短代码只在 GitHub/GitLab 生态用其他平台发布前全部替换成 Unicode检查目标平台是否支持彩色表情字体不支持就换保守字符文件名、目录名、URL 里绝对不出现 Emoji表格里的 Emoji 保持在单元格中后部不用在表头转 Word/PDF 前先做一份 HTML 中转复制粘贴后检查有没有混入零宽空格用编辑器显示所有字符的插件扫一遍一篇文档里面孔类表情不超过 5 个状态标记类可以随意跨平台发布时只使用最通用的表情✅ ❌ ⚠️ 使用 Obsidian、Typora 等本地工具优先 Unicode少用短代码发布前在手机端预览一遍和电脑端对比渲染差异我个人在实际操作里的体会是Emoji 的使用不是越多越好而是越有秩序越好。与其收藏一份再长的清单不如先定下你自己的一套规则。把常用的几十个表情用顺手比手握上千个却每次都在翻箱倒柜找要高效得多。尤其是团队协作的时候一套约定俗成的表情用法比写一页规范文档管用——因为读者看到表情的瞬间就理解了状态根本不给你机会读那页文档。
Markdown 中 Emoji 插入全指南：从短代码到跨平台兼容
写 Markdown 这些年我见过最可惜的一种情况内容写得很扎实但通篇都是灰扑扑的纯文本读者扫两眼就跳走了。我自己最开始也把 Emoji 当花架子直到在某项目的 README 里用了一组状态标记住在隔壁工位的同事专门跑过来问是怎么做出来的我才意识到——Emoji 在 Markdown 里从来不是装饰它就是信息本身。这篇文章想解决三个问题第一Markdown 里到底有哪几种插入 Emoji 的方式各自的边界在哪儿第二上千个表情怎么选不同用途该用哪一类第三在不同平台GitHub、Obsidian、Typora、静态博客、甚至 Markdown 转 Word上为什么同一个表情时灵时不灵遇到方框、乱码、丢失该怎么处理。无论你是写技术文档、维护 README还是在 Obsidian 里记笔记这篇都值得存一份。1. 为什么写 Markdown 一定要会点 Emoji1.1 先弄清楚你用的到底是哪种 Markdown很多人以为 Markdown 只有一种其实不是。用 Emoji 之前先得知道自己面对的是哪个方言。最基础的 Markdown 标准语法里根本没有 Emoji 这个概念它只定义了标题、列表、引用、代码块这些但 GitHub 在它的 Flavored MarkdownGFM里扩展了 Emoji 短代码于是:smile:这种写法才能在 GitHub 上活过来。这就是为什么你会遇到一个经典现象同样的文档在 GitHub 上看是笑脸复制到某个本地编辑器里就变成一行奇怪的:smile:字符串。不是编辑器坏了是它没有实现 GitHub 那套扩展。我一般把 Markdown 分成四类标准 CommonMark、GitHub 风格 GFM、编辑器特有方言比如 Obsidian 的 callout、以及博客系统自带的渲染扩展。插入 Emoji 的所有坑本质上都来自这四类之间的差异。有了这个概念后面所有问题都好解释短代码能不能渲染取决于渲染器Unicode 表情能不能显示取决于操作系统和字体转换到 Word 会不会丢取决于转换工具。1.2 Emoji 能给文章带来什么实际收益先说结论Emoji 最大的价值是让扫读效率变高。现在很少有人逐字读文档都是先扫标题、列表、状态标记判断这段值不值得看。Emoji 相当于给这些关键位置提前标了荧光笔。举个例子同样是更新日志纯文本版本是这样的- 修复登录超时问题 - 增加导出功能 - 已知问题移动端样式错乱加上状态标记之后- [修复] 登录超时问题 - [新增] 数据导出功能 - [注意] 移动端样式错乱下个版本处理看起来清楚了一点但还是不够醒目。如果你换成✅ 修复登录超时、✨ 新增数据导出、⚠️ 移动端样式错乱整个 changelog 的可读性会明显上一个台阶。GitHub 上大量高星项目的 README 都这么做不是因为他们闲是因为这真的能降低读者的理解成本。另外还有一层情绪价值。写技术文章的人经常忽略读者感受——通篇冷冰冰的文字读者很难判断作者的态度。一个 代表着这里我想了一下一个 代表下面是我的思路语气自然就出来了。Markdown 本身是纯文本Emoji 是它少数能表达语气的工具不用白不用。2. 在 Markdown 里插入 Emoji 的四种姿势2.1 姿势一GitHub 短代码最省事但看平台GitHub 短代码就是:冒号中间写英文名:这种格式。比如:smile:显示为 :rocket:显示为 。这套方案最大的优点是纯文本可读性极好哪怕不渲染你看到:warning:也能猜出它要表达警告。而且 GitHub 官方维护了上千个代码别名不用记 Unicode 码点。日常最常用的一批我给个对照表短代码显示效果短代码显示效果:smile::rocket::wink::memo::laughing::bulb::heart:❤️:warning:⚠️:1::x:❌:-1::white_check_mark:✅但短代码有两个硬边界。一是离开 GitHub 生态GitHub、GitLab、部分支持 GFM 的站点就不渲染很多本地编辑器会把它原样输出成文本。二是它只在普通正文和列表里生效放在代码块里就彻底失效——你在反引号包裹的代码块里写:smile:它永远只会显示字面字符串这是设计如此不是 bug。所以我的经验是短代码适合确定会发到 GitHub/GitLab 的文档用本地笔记和跨平台内容优先考虑第二种方式。2.2 姿势二直接粘贴 Unicode 表情通用性最强直接把 或者 这个字符粘贴进 Markdown 源文件这是我认为最稳妥的方案。它的本质是插入一个 Unicode 字符跟插入一个 中 字没有区别任何渲染器、任何编辑器、任何博客系统只要能正常显示中文就一定能正常显示这个字符。代价是源文件的纯文本可读性下降了。你打开源文件看到的是 而不是:smile:在代码评审、diff 对比的时候会稍微影响阅读。另外Unicode 标准每年更新同一个表情在不同年代的操作系统上可能长得不一样甚至新版系统引入的某些表情在旧版系统上直接显示成方框。我自己常用的策略是这样如果文档要长期维护、多平台分发比如一篇要同步到博客和公众号的文章全部用 Unicode 表情如果是 GitHub 上的仓库文档用短代码如果是 Obsidian 这类本地笔记两种都行但我更建议 Unicode因为笔记经常要导出成 PDF 或 Word短代码在导出链路里很容易变成一串英文。2.3 姿势三用系统输入法就地插入Windows 上用Win .会弹出 Emoji 选择面板macOS 上用Ctrl Cmd 空格移动端输入法里长按表情按钮也能调出来。这个操作不需要离开编辑器是我日常最常用的方式尤其是改文档时补一两个表情。有人问这和直接粘贴有什么区别本质没区别输入法也是帮你插入 Unicode 字符。但它有筛选和搜索功能比如在 Windows 面板里输入 smile 能把所有口部表情列出来找起来比翻收藏列表快。唯一要注意的是部分输入法会在粘贴时带出零宽空格等不可见字符后文问题排查部分我会专门讲。2.4 姿势四HTML 实体备胎方案Markdown 允许内嵌 HTML所以你可以写#128640;来表示 。这套方案在实际写作里几乎没人用因为可读性极差而且不是所有平台的安全过滤都放行 HTML。我提它纯粹是为了让你在遇到老旧的渲染环境时有个兜底——如果你在某个发布系统里既不能用短代码又不能直接粘贴字符有些后台会转义或过滤HTML 实体是最后的选择。日常写作忘掉它就好。3. 上千个表情的速查图谱按用途分好类3.1 文档状态标记类最推荐我写东西最常碰到的需求不是表达心情而是给内容打状态标签。一套稳定的状态标记能让文档从没头没尾变成一目了然。下面这组我几乎每篇文档都用用途Unicode短代码已完成✅:white_check_mark:未完成/待办☐ 或 ⬜:ballot_box_with_check:反义失败/错误❌:x:警告/注意⚠️:warning:施工中/开发中:construction:新功能/亮点✨:sparkles:重要/必读:pushpin:想法/灵感:bulb:关键提示:key:禁止/不可做:no_entry_sign:这里有个容易混淆的点很多人分不清 ✅ 和 ☑️。我的约定是 ✅ 表示这件事已经做完了☑️ 表示这是个可勾选的状态项配合 GFM 的任务列表- [x]使用。如果你在 README 的功能列表里想表达支持、不支持、计划中三个状态用 ✅ / ❌ / 组合是最直观的读者不用读任何说明就能看懂。3.2 表情面孔与手势这组主要用于正文表达语气我按使用频率排了序。高频区 正常开心、 笑哭、 微笑、 尴尬汗、 思考、 赞同、 感谢、 庆祝。中频区 眨眼、 喜欢、 大哭、、 酷、 震惊、 困、 摊手表示我也没办法。写技术内容时我对这类表情有两条规矩第一一篇 3000 字的文章面孔类表情不超过 5 个否则显得轻浮第二不要在 bug 描述、事故复盘这类严肃场景里用大笑表情读者会觉得你在嘲笑他们。表情传递的态度比文字更直接控制数量比追求丰富重要得多。3.3 物品工具与符号标记这类是技术文档里的主力比面孔表情有用得多。我用得最多的是这组用途Unicode短代码文件/文档:page_facing_up:文件夹:file_folder:链接:link:数据库️:file_cabinet:近义搜索:mag:代码 / ⌨️:computer:/:keyboard:配置/设置⚙️:gear:测试:test_tube:版本/发布️:label:时间/日历:calendar:趋势/上升:chart_with_upwards_trend:性能/极速⚡:zap:比如文档里写本项目使用 PostgreSQL 存储数据 ️API 层通过 Redis 做缓存 ⚡读者一眼就能定位信息块。这里有个增效做法给文档里的每种资源固定一种图标形成你自己的视觉字典。我的开源项目 README 约定是数据库用 ️接口用 命令行工具用 ⌨️环境变量用 ⚙️这样全仓库文档风格统一维护起来也省心。3.4 自然、动物与食物这类在正经技术文档里用得少但也不是没用。特性演示、示例代码、个人博客里它们能制造记忆点。比如用 但让我意外地容易区分 iOS/Android 两个分支的表格用 表示初期版本用 表示发布都属于恰到好处。我必须提醒一句动物和食物表情在跨平台渲染时差异最大。同一个 在 Apple 平台上长得非常可爱在 Windows 上可能完全认不出来是什么。如果内容要跨平台发布这类表情能不用就不用或者选那些形态稳定的比如 ☀️、、️ 这些自然现象类相对统一。3.5 数字序号与方向箭头写步骤说明和章节导航时这两类简直是救星。数字可以用 1️⃣ 2️⃣ 3️⃣ 这种带圈数字在操作步骤场景里比纯文本的 1. 醒目很多。方向箭头 ⬆️ ⬇️ ⬅️ ➡️ 配合 ↪️ 常用于表格里表示增减变化比如版本对比表格里v2.0 ⬆️ 速度提升 30% 比 v2.0 速度提升 30% 直观得多。需要注意带圈数字的表情其实是一组组合字符数字 变体选择符 组合围圈符。在某些老旧的渲染器上会拆成三个字符显示变成 1️⃣ 碎掉。稳妥做法是直接用 Unicode 里的圈数字字符 ① ② ③它们显示更稳定只是视觉上没那么立体。4. 不同渲染平台上的真实表现4.1 GitHub / GitLab / 国内代码托管平台GitHub 对 Emoji 的支持是最完整的短代码天然可用表情列表超过上千个而且它会跟随你的操作系统表情字体渲染。GitLab 基本兼容 GitHub 的短代码但表情数量和个别别名有差异。国内几家代码托管平台对 GFM 的支持参差不齐有的只渲染部分短代码我在这种平台上的做法是全部改成 Unicode 表情宁可牺牲源文件可读性也不能让文档在读者面前显示成一堆:xxx:。还有一个容易踩的坑GitHub 的短代码在 Markdown 注释里也会尝试渲染在 issue 模板、PR 模板里写!-- :smile: --并不会显示注释里那个表情。注释里的内容会被当作注释丢弃但你要是把短代码写在注释外、又放在代码块里它就会原样显示。写模板时要注意。4.2 Obsidian、Typora、VS Code 等本地编辑器本地编辑器的情况比较分裂。Typora 对 Unicode 表情支持很好所见即所得但:smile:短代码默认不渲染部分版本支持通过设置开启。Obsidian 也是同样的倾向Unicode 表情完美显示短代码需要用社区插件比如 Emoji Shortcodes才能补全提示和渲染。VS Code 的内置 Markdown 预览比较特殊它默认就能把常见短代码渲染成表情而且官方市场的 Markdown Preview Enhanced 插件也可以配置支持。三个编辑器的共同点是Unicode 表情都是没问题的短代码则各有各的脾气。所以我的建议很明确本地笔记和写作全部用 Unicode。尤其是 Obsidian 用户你的笔记经常要导出分享短代码导出后大概率变成火星文。4.3 Hexo、Hugo、VuePress 等静态博客静态博客能不能用 Emoji取决于两层Markdown 渲染器和主题样式。Hexo 默认的 marked 渲染器对:smile:短代码不处理需要安装 hexo-filter-github-emojis 这类插件Hugo 则内置了 shortcode 支持GitHub 风格表情可以直接用但要在配置里开启。VuePress/VitePress 这类基于 Node 的工具链一般通过 markdown-it 插件扩展短代码。如果你用的静态博客不支持短代码最省事的方案还是那句老话直接粘贴 Unicode 表情。我维护过两个博客一个 Hexo 一个 Hugo全部用 Unicode省去了所有插件兼容性问题换主题、换渲染器都不用回头改文章。静态博客还有一个手机端渲染问题部分主题的字体栈没配表情字体电脑上正常手机上变成方框通常需要在 CSS 里加上 system-ui、Apple Color Emoji、Segoe UI Emoji 这些字体。4.4 微信公众号、知乎、语雀这类富文本场景这些平台本质上不是 Markdown 原生渲染而是通过各种编辑器把 Markdown 转成富文本再粘贴发布。你的 Emoji 能不能保留取决于转换——粘贴这条链路上的每一步。经验是Unicode 表情基本都能存活短代码大概率死掉。微信编辑器对 Emoji 的支持还行但来源不明的一批字符比如部分特殊符号和旗帜类表情会被过滤。另外提醒一个很多人没注意的问题微信公众平台有自己的一套 Emoji 字符集某些微信端能显示的表情在电脑浏览器里看是方框反过来也一样。如果文章要适配多端阅读尽量选最基础、最通用的那些表情。我在公众号发技术文章时只用一组非常保守的字符✅ ❌ ⚠️ 再花哨的一律不用。5. 实战技巧把 Emoji 用出秩序感5.1 先定一套文档表情字典使用 Emoji 最忌讳的是随意。今天用 ✅ 表示完成明天用 后天用 读者根本建立不起映射关系。我的做法是给每个项目建一个表情字典写在项目根目录的 CONTRIBUTING 或者 README 开头状态标记 ✅ 已完成 开发中 ❌ 未实现 ⚠️ 注意/限制 文档约定 使用说明 相关链接 设计思路 已知问题这套字典不仅自己写文档时用也方便协作者遵守。我们团队现在 PR 描述、issue 标题都用这套约定筛选信息的速度快了很多。如果你的文档是给自己看的字典不用写下来但心里要有数否则写完一个月自己都不认识自己的表情。5.2 任务清单和高频组合用法GFM 的任务列表- [ ]配合 Emoji 是个很实用的组合。我习惯这样记录每日工作- [x] 完成登录模块重构 ✅ - [x] 补充 API 文档 - [ ] 排查移动端样式问题 - [ ] 周五前发 v2.3 版本 注意我把表情放在行尾而不是行首。因为 Markdown 任务列表的[x]本身就是状态标识行首再加表情会造成视觉冗余。行尾的表情承担的是额外说明功能完成的事项说明成果类型未完成的事项说明当前状态。这个用法在 Obsidian 的看板插件里也很顺手配合查询语法一眼就能筛出哪些任务是施工中。标题里用 Emoji 要克制。我的原则是一级标题不用二级标题偶尔用于区分内容分区比如安装 配置 ⚙️常见问题 ❓三级及以下标题全部不用。一旦每个标题都带表情页面会显得非常吵闹扫读时反而抓不到重点。5.3 表格里用 Emoji 的排版细节Markdown 表格是最容易暴露 Emoji 问题的场景。主要原因是 Emoji 的显示宽度不固定有的占一个字符宽度如 ⚡有的占两个如 导致表格列的视觉宽度参差不齐源代码里的对齐也不好看。我总结了三条经验。第一尽量把 Emoji 放在单元格靠后的位置不要放在最开头因为表格里最左侧的对齐线读者看得最认真表情会干扰对齐判断。第二列标题别用 Emoji保持列名纯粹列内容里再放。第三如果同一列里既有中文又有英文又有 Emoji建议把该列设为左对齐并给 Emoji 后面手动加一个空格观感会更统一。还有一个隐藏坑复制表格到 Excel 时Emoji 字符有时会影响 CSV 的字段分隔尤其当你在表格里用了逗号或者制表符时。这个问题在下一节详细说。6. 常见问题与排查实录6.1 显示成方框 / 豆腐块怎么办方框俗称豆腐块是最常见的翻车现场原因几乎只有一个当前系统或应用缺少对应的表情字体。Windows 7 及更老系统不支持彩色 EmojiLinux 发行版默认没装 Noto Color Emoji 的也很多有些远程服务器上的浏览器因为没字体直接渲染成空框。排查步骤我给个清单先在手机上看同一份文件如果手机正常、电脑异常基本确定是电脑字体问题然后升级操作系统或安装对应字体——Windows 更新、macOS 保持最新、Linux 安装 fonts-noto-color-emoji 包如果系统是最新的还显示方框大概率是编辑器或渲染器的字体设置问题去设置里把 UI 字体和代码字体改成系统默认即可。我处理过一次 VS Code 里预览正常、但导出 PDF 全是方框的情况最后发现是导出工具用的字体里没有表情换导出主题就好了。6.2 短代码不渲染显示成 :smile: 文本这个前面已经解释过根本原因是渲染器不支持 GFM 的 Emoji 扩展。排查方法也简单看文档具体在哪个平台显示异常如果是在 GitHub 之外的地方大概率不是 bug是能力边界。但有一个反直觉的情况GitHub 上部分短代码在特定栏目比如 Actions 的日志、部分讨论区不渲染因为那里的 Markdown 渲染器被精简过。如果在非 GitHub 平台必须用短代码两个替代方案查目标平台的文档是否支持短代码扩展比如 Hugo 开启 enableEmoji或者干脆全文替换成 Unicode。我这里有个快捷方法写文档时先用短代码发布前用一个正则把:[a-zA-Z0-9_-]:匹配出来对照映射表替换成 Unicode 字符。这是很多博客作者的常规操作比手工逐个改快得多。6.3 转 Word / PDF 后表情丢失或变黑白Markdown 转 Word 最常见的是用 pandoc或者先转 HTML 再复制到 Word。表情丢失或者变成黑白符号核心原因是目标格式的表情字体映射不一致且部分转换器会丢弃颜色信息。我的处理方案分两种。要一份能编辑的 Word先转 HTML在浏览器打开再用 CtrlA 全选复制到 Word这样表情是作为真实字符进去的大概率保留要一份 PDF用编辑器自带的导出功能Typora、Obsidian 都行而不是走 pandoc 直转因为编辑器的打印链路通常配置好了表情字体。如果一定要 pandoc建议用--pdf-enginexelatex并配合字体配置但说实话对普通用户成本偏高不划算。6.4 表格复制到 Excel 乱码 / 对齐错乱Markdown 表格复制到 Excel 经常出现两个问题中文乱码、列错位。中文乱码的根源是编码——Markdown 文件是 UTF-8 编码系统剪贴板转成其他编码时丢字符。列错位则和复制方式有关直接全选网页上的表格复制Excel 可能把 Markdown 的管道符|也当成内容粘进去了。想减少痛苦我建议这样如果目标只是 Excel 数据别用 Markdown 表格直接在 Markdown 里写 CSV 格式用 Excel 的数据 - 自文本/CSV导入选择 UTF-8 编码一次搞定。Markdown 表格从来不是用来做数据交换的它是给人读的不是给 Excel 读的。至于 Markdown 表格转 Excel 这个需求现在不少在线转换工具能直接处理输出一个 UTF-8 with BOM 的 CSVExcel 打开基本无压力。6.5 文件名和目录里千万别用 Emoji我在项目里见过有同事给图片命名成截图.png然后 Markdown 里写。本地编辑器能正常显示一推上 Git 就出问题——不同平台的 Git 对非 ASCII 文件名的处理不同有的仓库 clone 下来文件名正常有的直接变成一串百分号编码。更麻烦的是部分静态博客的 URL 生成逻辑会把 Emoji 转成百分号编码导致链接很长且缓存困难。我的原则是文件名、目录名、URL 路径、代码标识符里一律不用 Emoji。表情只存在于文档内容里用来标记和装饰不参与任何机器要解析的信息。这条规则帮我避免过至少三次本地好好的线上就崩了的经历。6.6 一个实用的 10 分钟自查清单最后给你一份我每次发布前必过的自查清单照着做能避开大部分坑短代码只在 GitHub/GitLab 生态用其他平台发布前全部替换成 Unicode检查目标平台是否支持彩色表情字体不支持就换保守字符文件名、目录名、URL 里绝对不出现 Emoji表格里的 Emoji 保持在单元格中后部不用在表头转 Word/PDF 前先做一份 HTML 中转复制粘贴后检查有没有混入零宽空格用编辑器显示所有字符的插件扫一遍一篇文档里面孔类表情不超过 5 个状态标记类可以随意跨平台发布时只使用最通用的表情✅ ❌ ⚠️ 使用 Obsidian、Typora 等本地工具优先 Unicode少用短代码发布前在手机端预览一遍和电脑端对比渲染差异我个人在实际操作里的体会是Emoji 的使用不是越多越好而是越有秩序越好。与其收藏一份再长的清单不如先定下你自己的一套规则。把常用的几十个表情用顺手比手握上千个却每次都在翻箱倒柜找要高效得多。尤其是团队协作的时候一套约定俗成的表情用法比写一页规范文档管用——因为读者看到表情的瞬间就理解了状态根本不给你机会读那页文档。
